{
  "markdown": "# MCP Tool Factory (TypeScript)\n\nGenerate production-ready MCP (Model Context Protocol) servers from natural language descriptions, OpenAPI specs, database schemas, GraphQL schemas, or ontologies.\n\n[![npm version](https://img.shields.io/npm/v/@heshamfsalama/mcp-tool-factory.svg)](https://www.npmjs.com/package/@heshamfsalama/mcp-tool-factory)\n[![npm downloads](https://img.shields.io/npm/dm/@heshamfsalama/mcp-tool-factory.svg)](https://www.npmjs.com/package/@heshamfsalama/mcp-tool-factory)\n[![CI](https://github.com/HeshamFS/mcp-tool-factory-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/HeshamFS/mcp-tool-factory-ts/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Registry-purple.svg)](https://registry.modelcontextprotocol.io)\n\n## Why MCP?\n\nThe **Model Context Protocol (MCP)** is an open standard that enables AI assistants to securely connect with external data sources and tools. MCP servers expose tools that can be used by:\n\n- **Claude Code** and **Claude Desktop**\n- **OpenAI Agents SDK**\n- **Google ADK (Agent Development Kit)**\n- **LangChain** and **CrewAI**\n- Any MCP-compatible client\n\nMCP Tool Factory lets you generate complete, production-ready MCP servers in seconds.\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Natural Language** | Describe your tools in plain English |\n| **OpenAPI Import** | Convert any REST API spec to MCP tools |\n| **Database CRUD** | Generate tools from SQLite or PostgreSQL schemas |\n| **GraphQL Import** | Convert GraphQL schemas to MCP tools (queries to reads, mutations to writes) |\n| **Ontology Import** | Generate from RDF/OWL, JSON-LD, or YAML ontologies |\n| **Resources & Prompts** | Full support for all three MCP primitives: Tools, Resources, and Prompts |\n| **10 LLM Providers** | Anthropic, OpenAI, Google, Mistral, DeepSeek, Groq, xAI, Azure, Cohere + Claude Code via Vercel AI SDK |\n| **Cost Tracking** | Per-call cost calculation, budget limits, provider cost comparison |\n| **Parallel Generation** | Tool implementations generated concurrently for faster output |\n| **LLM Response Caching** | Deduplicates identical LLM calls with configurable TTL |\n| **Streamable HTTP** | Generated servers use the modern Streamable HTTP transport |\n| **Web Search** | Auto-fetch API documentation for better generation |\n| **Production Ready** | Logging, metrics, rate limiting, retries built-in |\n| **Type Safe** | Full TypeScript with strict mode |\n| **MCP Registry** | Generates server.json for registry publishing |\n| **Is an MCP Server** | Use it directly with Claude to generate servers on-the-fly |\n\n## Use as MCP Server\n\nMCP Tool Factory is itself an MCP server! Add it to Claude Desktop, Claude Code, Cursor, or VS Code to generate MCP servers through conversation.\n\n### Tier 1 — Zero Config (Claude Code)\n\nClaude Code auto-injects `CLAUDE_CODE_OAUTH_TOKEN` — no env vars needed:\n\n```bash\nclaude mcp add mcp-tool-factory -- node /path/to/mcp-tool-factory-ts/bin/mcp-server.js\n```\n\n### Tier 2 — Standard (Pick a Provider)\n\nSet one API key and go. The factory auto-detects the provider:\n\n**Claude Desktop / Cursor / VS Code** — add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, or `.vscode/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tool-factory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-tool-factory-ts/bin/mcp-server.js\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\nAny of these API keys will work: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `COHERE_API_KEY`.\n\n### Tier 3 — Full Control (Provider + Model + Budget)\n\nUse `MCP_FACTORY_PROVIDER`, `MCP_FACTORY_MODEL`, and `MCP_FACTORY_BUDGET` to override auto-detection:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tool-factory\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-tool-factory-ts/bin/mcp-server.js\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-key-here\",\n        \"MCP_FACTORY_PROVIDER\": \"openai\",\n        \"MCP_FACTORY_MODEL\": \"gpt-5.2\",\n        \"MCP_FACTORY_BUDGET\": \"0.50\"\n      }\n    }\n  }\n}\n```\n\n| Env Var | Purpose | Example |\n|---------|---------|---------|\n| `MCP_FACTORY_PROVIDER` | Override auto-detected provider | `openai`, `groq`, `deepseek` |\n| `MCP_FACTORY_MODEL` | Override default model | `gpt-5.2`, `deepseek-chat` |\n| `MCP_FACTORY_BUDGET` | Per-generation budget limit in USD | `0.50` |\n\n**Claude Code CLI with full control:**\n\n```bash\nclaude mcp add mcp-tool-factory \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MCP_FACTORY_PROVIDER=deepseek \\\n  -e MCP_FACTORY_MODEL=deepseek-chat \\\n  -e MCP_FACTORY_BUDGET=0.25 \\\n  -- node /path/to/mcp-tool-factory-ts/bin/mcp-server.js\n```\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `generate_mcp_server` | Generate from natural language description |\n| `generate_from_openapi` | Generate from OpenAPI specification |\n| `generate_from_database` | Generate from database schema |\n| `generate_from_graphql` | Generate from GraphQL schema |\n| `generate_from_ontology` | Generate from RDF/OWL, JSON-LD, or YAML ontology |\n| `validate_typescript` | Validate TypeScript code |\n| `list_providers` | List available LLM providers |\n| `get_factory_info` | Get factory capabilities |\n\n### Example Conversation\n\n> **You:** Create an MCP server for the GitHub API with tools to list repos, create issues, and manage pull requests\n>\n> **Claude:** *Uses `generate_mcp_server` tool*\n>\n> I've generated a complete MCP server with the following tools:\n> - `list_repositories` - List user repositories\n> - `create_issue` - Create a new issue\n> - `list_pull_requests` - List PRs for a repo\n> - `merge_pull_request` - Merge a PR\n>\n> Let me write these files to your project...\n\n## Quick Start\n\n### Installation\n\n```bash\n# Global installation\nnpm install -g @heshamfsalama/mcp-tool-factory\n\n# Or use npx\nnpx @heshamfsalama/mcp-tool-factory generate \"Create tools for managing a todo list\"\n```\n\n### Set Your API Key\n\nAt least one provider API key is required:\n\n```bash\n# Anthropic Claude (recommended)\nexport ANTHROPIC_API_KEY=your-key-here\n\n# Or Claude Code OAuth\nexport CLAUDE_CODE_OAUTH_TOKEN=your-token-here\n\n# Or any other supported provider\nexport OPENAI_API_KEY=your-key-here\nexport GOOGLE_API_KEY=your-key-here\nexport MISTRAL_API_KEY=your-key-here\nexport DEEPSEEK_API_KEY=your-key-here\nexport GROQ_API_KEY=your-key-here\nexport XAI_API_KEY=your-key-here\nexport AZURE_OPENAI_API_KEY=your-key-here\nexport COHERE_API_KEY=your-key-here\n```\n\n### Generate Your First Server\n\n```bash\n# From natural language\nmcp-factory generate \"Create tools for fetching weather data by city and converting temperatures\"\n\n# From OpenAPI spec\nmcp-factory from-openapi ./api-spec.yaml\n\n# From database\nmcp-factory from-database ./data.db\n\n# From GraphQL schema\nmcp-factory from-graphql ./schema.graphql\n\n# From ontology\nmcp-factory from-ontology ./ontology.owl --format rdf\n```\n\n## Usage\n\n### Natural Language Generation\n\n```bash\nmcp-factory generate \"Create tools for managing a todo list with priorities\" \\\n  --name todo-server \\\n  --output ./servers/todo \\\n  --web-search \\\n  --logging \\\n  --metrics\n```\n\n### OpenAPI Specification\n\n```bash\n# From local file\nmcp-factory from-openapi ./openapi.yaml --name my-api-server\n\n# With custom base URL\nmcp-factory from-openapi ./spec.json --base-url https://api.example.com\n```\n\n### Database Schema\n\n```bash\n# SQLite\nmcp-factory from-database ./myapp.db --tables users,posts,comments\n\n# PostgreSQL\nmcp-factory from-database \"postgresql://user:pass@localhost/mydb\" --type postgresql\n```\n\n### GraphQL Schema\n\n```bash\n# From a GraphQL SDL file\nmcp-factory from-graphql ./schema.graphql --name my-graphql-server\n\n# From a URL endpoint\nmcp-factory from-graphql https://api.example.com/graphql --name my-api-server\n```\n\nGraphQL queries are mapped to read-only MCP tools, and mutations are mapped to write tools. GraphQL types are automatically converted to Zod validation schemas.\n\n### Ontology\n\n```bash\n# From RDF/OWL (.owl, .rdf, .ttl)\nmcp-factory from-ontology ./ontology.owl --format rdf --name knowledge-server\n\n# From JSON-LD (.jsonld)\nmcp-factory from-ontology ./schema.jsonld --format jsonld --name linked-data-server\n\n# From custom YAML ontology\nmcp-factory from-ontology ./domain.yaml --format yaml --name domain-server\n```\n\nOWL Classes are mapped to MCP Resources, ObjectProperties become Tools, and DataProperties become tool parameters.\n\n### Test & Serve\n\n```bash\n# Run tests\nmcp-factory test ./servers/my-server\n\n# Start server for testing\nmcp-factory serve ./servers/my-server\n```\n\n## Generated Server Structure\n\n```\nservers/my-server/\n├── src/\n│   └── index.ts          # MCP server with tools, resources, and prompts\n├── tests/\n│   └── tools.test.ts     # Vitest tests (InMemoryTransport)\n├── package.json          # Dependencies\n├── tsconfig.json         # TypeScript config\n├── Dockerfile            # Container deployment\n├── README.md             # Usage documentation\n├── skill.md              # Claude Code skill file\n├── server.json           # MCP Registry manifest\n├── EXECUTION_LOG.md      # Generation trace (optional)\n└── .github/\n    └── workflows/\n        └── ci.yml        # GitHub Actions CI/CD\n```\n\nGenerated servers export a `createServer()` factory function for easy testing. The server uses Streamable HTTP transport with a single `/mcp` POST endpoint and a `/health` GET endpoint. Tests use `InMemoryTransport.createLinkedPair()` for fast, reliable in-process testing with vitest.\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `generate <description>` | Generate MCP server from natural language |\n| `from-openapi <spec>` | Generate from OpenAPI specification |\n| `from-database <path>` | Generate from database schema |\n| `from-graphql <schema>` | Generate from GraphQL schema |\n| `from-ontology <file>` | Generate from RDF/OWL, JSON-LD, or YAML ontology |\n| `test <server-path>` | Run tests for generated server |\n| `serve <server-path>` | Start server for testing |\n| `info` | Display factory information |\n\n### Generate Options\n\n```bash\nmcp-factory generate \"...\" \\\n  --output, -o <path>           # Output directory (default: ./servers)\n  --name, -n <name>             # Server name\n  --description, -d <desc>      # Package description\n  --github-username, -g <user>  # GitHub username for MCP Registry\n  --version, -v <ver>           # Server version (default: 1.0.0)\n  --provider, -p <provider>     # LLM provider (anthropic, openai, google, mistral, deepseek, groq, xai, azure, cohere, claude_code)\n  --model, -m <model>           # Specific model to use\n  --web-search, -w              # Search web for API documentation\n  --auth <vars...>              # Environment variables for auth\n  --health-check                # Include health check endpoint (default: true)\n  --logging                     # Enable structured logging (default: true)\n  --metrics                     # Enable Prometheus metrics\n  --rate-limit <n>              # Rate limiting (requests per minute)\n  --retries                     # Enable retry logic (default: true)\n  --budget <amount>             # Maximum spend in USD (aborts if exceeded)\n  --compare-costs               # Show cost comparison across providers before generating\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `ANTHROPIC_API_KEY` | Anthropic Claude API key | At least one |\n| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token | provider key |\n| `OPENAI_API_KEY` | OpenAI API key | is required |\n| `GOOGLE_API_KEY` | Google Gemini API key | for generation |\n| `MISTRAL_API_KEY` | Mistral AI API key | |\n| `DEEPSEEK_API_KEY` | DeepSeek API key | |\n| `GROQ_API_KEY` | Groq API key | |\n| `XAI_API_KEY` | xAI Grok API key | |\n| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key | |\n| `COHERE_API_KEY` | Cohere API key | |\n\n### LLM Providers\n\nAll providers use the [Vercel AI SDK](https://sdk.vercel.ai/) via a unified `UnifiedLLMProvider` class with lazy dynamic imports — only the `@ai-sdk/*` package for your chosen provider is loaded at runtime.\n\n| Provider | Models | Best For |\n|----------|--------|----------|\n| Anthropic | claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5 | Highest quality |\n| OpenAI | gpt-5.2, gpt-5.2-codex, o3, o4-mini | Fast generation |\n| Google | gemini-3-pro, gemini-3-flash, gemini-2.5-pro | Cost effective |\n| Mistral | mistral-large, codestral, magistral | European AI, code |\n| DeepSeek | deepseek-chat, deepseek-reasoner | Ultra low cost |\n| Groq | llama-3.3-70b, llama-4-maverick | Ultra-fast inference |\n| xAI | grok-4, grok-3, grok-code-fast | Reasoning |\n| Azure | gpt-4o (Azure-hosted) | Enterprise compliance |\n| Cohere | command-a, command-r+ | RAG, enterprise search |\n| Claude Code | claude-sonnet-4-5 (OAuth) | Claude Code users |\n\n## Programmatic Usage\n\n### Basic Usage\n\n```typescript\nimport { ToolFactoryAgent, writeServerToDirectory, formatCost } from '@heshamfsalama/mcp-tool-factory';\n\n// Create agent (auto-detects provider from env vars)\nconst agent = new ToolFactoryAgent();\n\n// Generate from description\nconst server = await agent.generateFromDescription(\n  'Create tools for managing a todo list with priorities',\n  {\n    serverName: 'todo-server',\n    webSearch: true,\n    parallel: true,           // Enable parallel generation (default)\n    maxConcurrency: 5,        // Max concurrent LLM calls (default)\n    budget: 1.00,             // Optional: abort if cost exceeds $1.00\n    productionConfig: {\n      enableLogging: true,\n      enableMetrics: true,\n    },\n  }\n);\n\n// Cost tracking — see how much the generation cost\nif (server.executionLog) {\n  console.log(`Cost: ${formatCost(server.executionLog.totalCost)}`);\n}\n\n// Write to directory\nawait writeServerToDirectory(server, './servers/todo');\n```\n\n### From OpenAPI\n\n```typescript\nimport { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';\nimport { readFileSync } from 'fs';\nimport yaml from 'js-yaml';\n\nconst spec = yaml.load(readFileSync('./openapi.yaml', 'utf-8'));\nconst agent = new ToolFactoryAgent({ requireLlm: false });\n\nconst server = await agent.generateFromOpenAPI(spec, {\n  serverName: 'my-api-server',\n  baseUrl: 'https://api.example.com',\n});\n\nawait writeServerToDirectory(server, './servers/api');\n```\n\n### From Database\n\n```typescript\nimport { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';\n\nconst agent = new ToolFactoryAgent({ requireLlm: false });\n\n// SQLite (auto-detected from file path)\nconst server = await agent.generateFromDatabase('./data/app.db', {\n  serverName: 'app-database-server',\n  tables: ['users', 'posts', 'comments'],\n});\n\n// PostgreSQL (auto-detected from connection string)\nconst pgServer = await agent.generateFromDatabase(\n  'postgresql://user:pass@localhost/mydb',\n  { serverName: 'postgres-server' }\n);\n\nawait writeServerToDirectory(server, './servers/app-db');\n```\n\n### From GraphQL\n\n```typescript\nimport { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';\nimport { readFileSync } from 'fs';\n\nconst schema = readFileSync('./schema.graphql', 'utf-8');\nconst agent = new ToolFactoryAgent({ requireLlm: false });\n\nconst server = await agent.generateFromGraphQL(schema, {\n  serverName: 'my-graphql-server',\n});\n\nawait writeServerToDirectory(server, './servers/graphql');\n```\n\n### From Ontology\n\n```typescript\nimport { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';\nimport { readFileSync } from 'fs';\n\nconst ontologyData = readFileSync('./ontology.owl', 'utf-8');\nconst agent = new ToolFactoryAgent({ requireLlm: false });\n\nconst server = await agent.generateFromOntology(ontologyData, {\n  serverName: 'knowledge-server',\n  format: 'rdf',\n});\n\nawait writeServerToDirectory(server, './servers/knowledge');\n```\n\n### Code Validation\n\n```typescript\nimport { validateTypeScriptCode, validateGeneratedServer } from '@heshamfsalama/mcp-tool-factory';\n\n// Validate TypeScript syntax\nconst result = await validateTypeScriptCode(code);\n// { valid: false, errors: [{ line: 4, column: 1, message: \"'}' expected.\" }] }\n\n// Validate complete server\nconst serverResult = await validateGeneratedServer(serverCode);\n// { valid: true, errors: [], summary: 'Generated server code is syntactically valid' }\n```\n\n## Use with AI Frameworks\n\n### Claude Code / Claude Desktop\n\nAdd to your MCP settings (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"./servers/my-server/src/index.ts\"]\n    }\n  }\n}\n```\n\n### OpenAI Agents SDK\n\n```python\nfrom agents import Agent\nfrom agents.mcp import MCPServerStdio\n\nasync with MCPServerStdio(\n    command=\"npx\",\n    args=[\"tsx\", \"./servers/my-server/src/index.ts\"]\n) as mcp:\n    agent = Agent(\n        name=\"My Agent\",\n        tools=mcp.list_tools()\n    )\n```\n\n### Google ADK\n\n```python\nfrom google.adk.tools.mcp_tool import MCPToolset\n\ntools = MCPToolset(\n    connection_params=StdioServerParameters(\n        command=\"npx\",\n        args=[\"tsx\", \"./servers/my-server/src/index.ts\"]\n    )\n)\n```\n\n### LangChain\n\n```python\nfrom langchain_mcp_adapters.client import MCPClient\n\nclient = MCPClient(\n    command=\"npx\",\n    args=[\"tsx\", \"./servers/my-server/src/index.ts\"]\n)\ntools = client.get_tools()\n```\n\n## Production Features\n\n### Structured Logging\n\n```bash\nmcp-factory generate \"...\" --logging\n```\n\nGenerates servers with [pino](https://github.com/pinojs/pino) structured JSON logging:\n\n```typescript\nconst logger = pino({ level: 'info' });\nlogger.info({ tool: 'get_weather', params }, 'Tool called');\n```\n\n### Prometheus Metrics\n\n```bash\nmcp-factory generate \"...\" --metrics\n```\n\nGenerates servers with [prom-client](https://github.com/siimon/prom-client) metrics:\n\n- `mcp_tool_calls_total` - Counter of tool invocations\n- `mcp_tool_duration_seconds` - Histogram of execution times\n\n### Rate Limiting\n\n```bash\nmcp-factory generate \"...\" --rate-limit 100\n```\n\nConfigurable rate limiting per client with sliding window.\n\n### Retry Logic\n\n```bash\nmcp-factory generate \"...\" --retries\n```\n\nExponential backoff retry for transient failures.\n\n### Structured Error Codes\n\nGenerated servers use structured error codes for consistent error handling:\n\n- `INVALID_INPUT` - Malformed or invalid tool parameters\n- `NOT_FOUND` - Requested resource does not exist\n- `AUTH_ERROR` - Authentication or authorization failure\n- `INTERNAL_ERROR` - Unexpected server error\n\n### Enhanced Health Check\n\nThe `/health` endpoint returns detailed server status:\n\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"1.0.0\",\n  \"uptime\": 3600,\n  \"memory\": { \"rss\": 52428800, \"heapUsed\": 20971520 },\n  \"transport\": \"streamable-http\"\n}\n```\n\n## MCP Registry Publishing\n\nPublish your generated servers to the [MCP Registry](https://registry.modelcontextprotocol.io) for discoverability.\n\n### Generate with Registry Support\n\n```bash\nmcp-factory generate \"Create weather tools\" \\\n  --name weather-server \\\n  --github-username your-github-username \\\n  --description \"Weather tools for Claude\" \\\n  --version 1.0.0\n```\n\nThis generates registry-compliant files:\n\n**package.json:**\n```json\n{\n  \"name\": \"@your-github-username/weather-server\",\n  \"mcpName\": \"io.github.your-github-username/weather-server\"\n}\n```\n\n**server.json:**\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.your-github-username/weather-server\",\n  \"packages\": [{\n    \"registryType\": \"npm\",\n    \"identifier\": \"@your-github-username/weather-server\",\n    \"transport\": { \"type\": \"stdio\" }\n  }],\n  \"tools\": [...]\n}\n```\n\n### Publish Workflow\n\n```bash\n# 1. Build and publish to npm\ncd ./servers/weather-server\nnpm install && npm run build\nnpm publish --access public\n\n# 2. Install mcp-publisher\nbrew install modelcontextprotocol/tap/mcp-publisher\n\n# 3. Authenticate\nmcp-publisher login github\n\n# 4. Publish to registry\nmcp-publisher publish\n```\n\nSee [Publishing Guide](docs/publishing.md) for detailed instructions.\n\n## Architecture\n\n```\n┌───────────────────────────────────────────────────────────────────────┐\n│                         MCP Tool Factory                               │\n├───────────────────────────────────────────────────────────────────────┤\n│  Input Sources                                                         │\n│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐│\n│  │ Natural   │ │  OpenAPI  │ │ Database  │ │ GraphQL   │ │Ontology ││\n│  │ Language  │ │   Spec    │ │  Schema   │ │  Schema   │ │RDF/YAML ││\n│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └────┬────┘│\n│        └──────────┬───┴─────────────┴─────────────┴────────────┘     │\n│                   ▼                                                    │\n│  ┌────────────────────────────────────────────────────────────────┐   │\n│  │                     ToolFactoryAgent                            │   │\n│  │  ┌─────────────────────────────────────────────────────────┐   │   │\n│  │  │  UnifiedLLMProvider (Vercel AI SDK)                      │   │   │\n│  │  │  Anthropic │ OpenAI │ Google │ Mistral │ DeepSeek       │   │   │\n│  │  │  Groq │ xAI │ Azure │ Cohere + Claude Code OAuth       │   │   │\n│  │  └─────────────────────────────────────────────────────────┘   │   │\n│  │  ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐  │   │\n│  │  │  LLM Cache   │ │  Cost        │ │ Parallel Generation   │  │   │\n│  │  │  (TTL-based) │ │  Tracking    │ │ (max concurrency: 5)  │  │   │\n│  │  └──────────────┘ └──────────────┘ └───────────────────────┘  │   │\n│  └────────────────────────────────────────────────────────────────┘   │\n│                   │                                                    │\n│                   ▼                                                    │\n│  ┌────────────────────────────────────────────────────────────────┐   │\n│  │                       Generators                                │   │\n│  │  ServerGenerator  │  DocsGenerator  │  TestsGenerator          │   │\n│  └────────────────────────────────────────────────────────────────┘   │\n│                   │                                                    │\n│                   ▼                                                    │\n│  ┌────────────────────────────────────────────────────────────────┐   │\n│  │                     GeneratedServer                             │   │\n│  │  Tools │ Resources │ Prompts │ Tests │ Docs │ Dockerfile       │   │\n│  └────────────────────────────────────────────────────────────────┘   │\n│                   │                                                    │\n│                   ▼                                                    │\n│  ┌────────────────────────────────────────────────────────────────┐   │\n│  │                Streamable HTTP Transport                        │   │\n│  │          POST /mcp  │  GET /health                             │   │\n│  └────────────────────────────────────────────────────────────────┘   │\n└───────────────────────────────────────────────────────────────────────┘\n```\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/HeshamFS/mcp-tool-factory-ts.git\ncd mcp-tool-factory-ts\n\n# Install dependencies\npnpm install\n\n# Build\npnpm run build\n\n# Run tests\npnpm test\n\n# Type check\npnpm run typecheck\n\n# Lint\npnpm run lint\n```\n\n## Project Structure\n\n```\nmcp-tool-factory-ts/\n├── src/\n│   ├── agent/              # Main ToolFactoryAgent\n│   ├── auth/               # OAuth2 providers\n│   ├── cache/              # LLM response caching with configurable TTL\n│   ├── cli/                # Command-line interface\n│   ├── config/             # Configuration management\n│   ├── database/           # Database introspection (SQLite, PostgreSQL)\n│   ├── execution-logger/   # Execution logging\n│   ├── generators/         # Code generators (server, docs, tests)\n│   ├── graphql/            # GraphQL SDL parsing and server generation\n│   ├── middleware/         # Validation middleware\n│   ├── models/             # Data models\n│   ├── observability/      # Telemetry and tracing\n│   ├── ontology/           # Ontology parsing (RDF/OWL, JSON-LD, YAML)\n│   ├── openapi/            # OpenAPI spec parsing\n│   ├── production/         # Production code generation\n│   ├── prompts/            # LLM prompt templates\n│   ├── providers/          # LLM providers (10 providers via Vercel AI SDK + Claude Code)\n│   ├── security/           # Security scanning\n│   ├── server/             # MCP server mode (factory-as-a-server)\n│   ├── templates/          # Handlebars templates for generated files\n│   ├── validation/         # Code validation and Zod schemas\n│   └── web-search/         # Web search integration\n├── docs/                   # Documentation\n├── tests/                  # Test files\n└── dist/                   # Built output\n```\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [CLI Reference](docs/cli-reference.md)\n- [API Reference](docs/api-reference.md)\n- [Examples](docs/examples.md)\n- [OpenAPI Guide](docs/openapi.md)\n- [Database Guide](docs/database.md)\n- [Providers Guide](docs/providers.md)\n- [Production Features](docs/production.md)\n- [Architecture](docs/architecture.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Contributing](docs/contributing.md)\n\n## Troubleshooting\n\n### Common Issues\n\n**API Key Not Found**\n```bash\n# Check your environment\necho $ANTHROPIC_API_KEY\n\n# Set it\nexport ANTHROPIC_API_KEY=your-key-here\n```\n\n**Generated Server Won't Start**\n```bash\n# Install dependencies first\ncd ./servers/my-server\nnpm install\nnpx tsx src/index.ts\n```\n\n**TypeScript Errors**\n```bash\n# Validate generated code\nimport { validateGeneratedServer } from '@heshamfsalama/mcp-tool-factory';\nconst result = await validateGeneratedServer(code);\nconsole.log(result.errors);\n```\n\nSee [Troubleshooting Guide](docs/troubleshooting.md) for more solutions.\n\n## Changelog\n\n### v0.3.0\n\n- **Vercel AI SDK Migration** - All LLM providers now use the [Vercel AI SDK](https://sdk.vercel.ai/) via a single `UnifiedLLMProvider` class with lazy dynamic imports. Removed ~473 LOC of provider-specific implementations. Only the `@ai-sdk/*` package for your chosen provider is loaded at runtime.\n- **10 LLM Providers** - Added Mistral, DeepSeek, Groq, xAI, Azure, and Cohere alongside existing Anthropic, OpenAI, Google, and Claude Code providers. All use the same unified interface.\n- **Cost Tracking** - Every LLM call now calculates estimated cost using a built-in pricing table for 50+ models. Shows per-call cost, total generation cost, and per-phase breakdown (tool extraction, implementation, tests, docs). Detailed token breakdowns include cache read/write tokens and reasoning tokens from the AI SDK.\n- **Budget Limits** (`--budget <amount>`) - Set a maximum spend in USD. Generation aborts gracefully with `BudgetExceededError` if cumulative cost exceeds the budget.\n- **Provider Cost Comparison** (`--compare-costs`) - Before generation, estimates cost across all available providers and shows a sorted comparison table. No extra API calls needed — uses the static pricing table.\n- **Per-Phase Cost Breakdown** - CLI output and execution logs show which generation steps cost the most (tool extraction, implementation, resource extraction, prompt extraction, test generation, docs generation).\n- **OpenAI Reasoning Model Support** - Temperature parameter is automatically omitted for OpenAI o-series and gpt-5.x models that don't support it.\n\n### v0.2.0\n\n- **Streamable HTTP Transport** - Generated servers use `StreamableHTTPServerTransport` with native `http` module instead of Express/SSE (deprecated June 2025). Single `/mcp` POST endpoint with `/health` GET endpoint.\n- **MCP SDK v1.26.0** - Updated from `^1.0.0` to `^1.26.0`\n- **Resources & Prompts** - Full support for all three MCP primitives. Resources expose structured data (documents, DB records, file trees). Prompts provide reusable templates for guided LLM workflows. Agent automatically extracts resources and prompts from descriptions via LLM.\n- **GraphQL Input Source** - New `from-graphql` CLI command and `generate_from_graphql` MCP tool. Queries map to read tools, mutations map to write tools, and GraphQL types are converted to Zod schemas.\n- **Ontology Input Source** - New `from-ontology` CLI command and `generate_from_ontology` MCP tool. Supports RDF/OWL, JSON-LD, and custom YAML formats. OWL Classes map to Resources, ObjectProperties to Tools, DataProperties to tool parameters.\n- **LLM Response Caching** - Deduplicates identical LLM calls with configurable TTL. Bypass with `skipCache` option.\n- **Parallel Generation** - Tool implementations generated concurrently by default (`parallel: true`, `maxConcurrency: 5`). Significant speed improvement for multi-tool servers.\n- **InMemoryTransport Testing** - Generated tests use `InMemoryTransport.createLinkedPair()` instead of subprocess spawning. Servers export `createServer()` factory function for testability.\n- **Production Enhancements** - Rate limiting, structured logging, metrics, and duration tracking wired into tool handlers. Enhanced health check with version, uptime, memory, and transport info. Structured error codes: `INVALID_INPUT`, `NOT_FOUND`, `AUTH_ERROR`, `INTERNAL_ERROR`.\n\n### v0.1.0\n\n- Initial TypeScript release\n- Natural language generation with Claude, Claude Code, OpenAI, Google Gemini\n- OpenAPI 3.0+ specification import\n- Database CRUD generation (SQLite, PostgreSQL)\n- Production features (logging, metrics, rate limiting)\n- MCP Registry server.json generation\n- TypeScript syntax validation\n- Web search for API documentation\n- GitHub Actions CI/CD generation\n- MCP Server mode for on-the-fly generation with Claude\n\n## License\n\nMIT\n\n## Links\n\n- [GitHub Repository](https://github.com/HeshamFS/mcp-tool-factory-ts)\n- [npm Package](https://www.npmjs.com/package/@heshamfsalama/mcp-tool-factory)\n- [MCP Specification](https://spec.modelcontextprotocol.io/)\n- [MCP Registry](https://github.com/modelcontextprotocol/registry)\n- [Python Version](https://github.com/HeshamFS/mcp-tool-factory)\n",
  "bytes": 30501,
  "sha": "e87570f26f9d9c2238dc237c695a4123b984ca55372a2b852aed1e3d10d0cd41",
  "repo_slug": "heshamfs/mcp-tool-factory-ts",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_heshamfs_mcp_tool_factory_8610b7b2/readme"
}