AGENTS.md — Agentify

Identity

Agentify is an Agent Interface Compiler. It reads OpenAPI specifications and either returns structured data about the API (parse mode) or generates agent interface code (transform mode).

Install: npm install -g agentify-cli or use via npx agentify-cli.

How It Works

Agentify has a hybrid architecture. Some outputs are best generated deterministically (MCP servers, CLIs, A2A cards) while others — like documentation for intelligent agents — are better written by agents themselves using structured data.

Parse mode (agentify parse <spec>) outputs the intermediate representation (IR) as JSON. The IR contains product metadata, domain groupings, typed capabilities, auth configuration, and a scale-based generation strategy. Use this when you need to understand an API or write your own agent documentation.

Transform mode (agentify transform <spec>) generates runnable code and configuration files. It supports 9 output formats. Use this when you need deterministic artifacts.

Self-describe (agentify self-describe) outputs Agentify's own agent interface files.

Commands

Command	Purpose	Output
parse <spec>	Structured API analysis	JSON (AgentifyIR) to stdout
transform <spec>	Code generation	Files in output directory
self-describe	Agentify's own interfaces	skills.json, CLAUDE.md, AGENTS.md

Transform Options

• -o, --output <dir> — Output directory
• -n, --name <name> — Override project name
• -f, --format <formats...> — Select formats: mcp, claude.md, agents.md, cursorrules, skills, llms.txt, gemini.md, a2a, cli

When to Use Each Command

Use parse when you are an agent that wants to reason about an API — its domains, capabilities, auth scheme, and scale. The JSON output is designed for programmatic consumption. This is the right choice if you plan to write documentation, analyze API coverage, or build custom tooling.

Use transform when you need generated code: an MCP server with tool handlers, a standalone CLI, an A2A discovery card, or a skills manifest. These formats require structural correctness that benefits from deterministic generation.

Supported Inputs

• Swagger 2.0 and OpenAPI 3.x (JSON or YAML)
• URL or local file path
• Lenient parsing: non-compliant specs are handled gracefully

Key Capabilities

• Parses OpenAPI into a flat, agent-optimized intermediate representation
• Detects auth schemes (apiKey, bearer, oauth2, basic) and maps them to environment variables
• Groups endpoints into semantic domains automatically
• Selects generation strategy by API scale (small/medium/large)
• Sanitizes all spec inputs to prevent injection in generated code
• Scans generated output for security issues

Tested At Scale

API	Endpoints	Notes
Notion	13	Small, clean spec
Petstore	20	Swagger 2.0 reference
httpbin	73	Medium, diverse operations
Slack	174	Large, complex auth
Stripe	452	Very large, nested schemas
GitHub	1,093	Stress test scale

Constraints

• Requires Node.js 18+
• Remote specs require internet access
• Generated MCP servers need their own npm install and env configuration

Context

• Repository: https://github.com/koriyoshi2041/agentify
• npm: https://www.npmjs.com/package/agentify-cli
• License: MIT

---

Your API has new users it doesn't know about yet — AI agents.

Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Codex and Copilot read AGENTS.md. And if you want your API callable as a tool, you need an MCP server. That's a lot of files to write and keep in sync with your API spec.

Agentify reads your OpenAPI spec and writes them all.

npx agentify-cli transform https://petstore.swagger.io/v2/swagger.json

What You Get

One command generates up to 9 formats from a single OpenAPI spec:

Format	Used by
MCP Server	Claude, ChatGPT, Copilot (with Dockerfile)
CLAUDE.md	Claude Code
AGENTS.md	Codex, Copilot, Cursor, Gemini CLI
.cursorrules	Cursor IDE
Skills	Agent platforms
llms.txt	LLM search engines
GEMINI.md	Gemini CLI
A2A Card	Google Agent-to-Agent protocol
CLI	A standalone command-line tool that makes real API calls

Quick Start

# Transform any OpenAPI spec (Swagger 2.0 or OpenAPI 3.x)
npx agentify-cli transform https://petstore.swagger.io/v2/swagger.json

# Pick specific formats
npx agentify-cli transform ./my-api.yaml -f mcp claude.md agents.md

# Generate a standalone CLI tool
npx agentify-cli transform ./my-api.yaml -f cli -o my-api-cli

# Custom output directory and project name
npx agentify-cli transform https://api.example.com/openapi.json -o ./output -n my-project

Example output:

  Agentify v0.4.1
  Agent Interface Compiler

  +-- 20 endpoints detected -> SMALL API strategy
  +-- 3 domains identified (pet, store, user)
  +-- Auth: apiKey (SWAGGER_PETSTORE_API_KEY)
  +-- Strategy: Direct tool mapping — one tool per endpoint

  > Generated mcp + claude.md + agents.md + cursorrules + llms.txt + gemini.md + skills + a2a (15 files)
  > Output: ./swagger-petstore-mcp-server
  > Security scan: PASSED

Tested on Real APIs

Agentify handles APIs of any size — from 13-endpoint apps to 1,000+ endpoint platforms.

API	Endpoints	Domains	TypeScript	Server starts
Notion	13	5	PASS	PASS
Petstore (Swagger 2.0)	20	3	PASS	PASS
httpbin (non-compliant spec)	73	11	PASS	PASS
Slack Web API	174	55	PASS	PASS
Stripe	452	1	PASS	PASS
GitHub REST API	1,093	43	PASS	PASS

Every generated MCP server compiles with zero TypeScript errors and starts immediately. Non-compliant specs (like httpbin) are auto-normalized with warnings instead of rejected. The GitHub REST API — 1,093 endpoints across 43 domains — produces a working server with 1,093 tools.

How It Works

OpenAPI Spec (URL or file)
    |
    v
  PARSE ──> SANITIZE ──> ANALYZE ──> COMPILE ──> EMIT ──> SCAN ──> OUTPUT
              |              |           |          |        |
          Strip unsafe    Detect     Build IR    Run      Security
          patterns        domains,   (typed)     emitters  scan all
                          auth,                            generated
                          API scale                        code

Agentify parses your spec into an intermediate representation (AgentifyIR), then runs pluggable emitters to produce each output format. Every generated artifact goes through a security scan before being written to disk.

Security built in:

• Input sanitization (blocks eval, exec, Function constructor injection)
• Prompt injection pattern detection
• Generated code scanning

Contributing

New emitters are welcome. Each one implements a simple interface:

import type { Emitter, AgentifyIR, EmitterOptions, EmitterResult } from "../types";

export class MyFormatEmitter implements Emitter {
  readonly name = "my-format";
  readonly format = "my-format";

  async emit(ir: AgentifyIR, options: EmitterOptions): Promise<EmitterResult> {
    // Generate output files from the IR
    return { format: this.format, filesWritten: [...], warnings: [] };
  }
}

agentify/
+-- src/
|   +-- cli.ts              # CLI entry point
|   +-- parser/             # OpenAPI parsing + sanitization
|   +-- generator/          # Pluggable emitters for each format
|   +-- security/           # Input sanitization + output scanning
|   +-- types.ts            # AgentifyIR type definitions
+-- test/                   # Vitest test suite (136 tests)

Status

This is early. It works on Swagger 2.0 and OpenAPI 3.x specs, handles auth detection, domain grouping, and API scale analysis. If you try it and something breaks, open an issue — that helps a lot.

• OpenAPI parser, MCP emitter, security scanner, CLI
• 9 output formats: MCP, CLAUDE.md, AGENTS.md, .cursorrules, Skills, llms.txt, GEMINI.md, A2A, CLI
• Capability graph and semantic grouping
• Web UI and one-click deploy
• Custom emitter plugins

License

MIT