MCP服务器生成工具

MCPForge

Generate MCP servers from OpenAPI specs or docs pages, then verify generated request compatibility before you publish or install them.

Demo

Why It Exists

Most OpenAPI-to-MCP generators stop at endpoint wrappers. That gets you a server, but not necessarily a toolset an LLM can use well. You often end up with hundreds of low-signal tools, weak descriptions, and no clear path from "API surface area" to "jobs a user wants done."

MCPForge does two extra things:

• Curates endpoint tools with AI so the public surface stays small and usable.
• Plans task-oriented workflow tools that wrap useful jobs like find_customers, create_payment_link, or refund_payment.

The result is closer to "brief the model on the jobs it can do" than "dump the entire REST spec into MCP."

Quick Start

Fastest path from the registry:

npx mcpforge add stripe

From an OpenAPI spec:

npx mcpforge init --optimize --workflows https://api.example.com/openapi.json

From a docs page when you do not have a spec:

npx mcpforge init --from-url --workflows https://docs.stripe.com/api

Preview without writing files:

npx mcpforge init --dry-run --optimize --workflows https://api.example.com/openapi.json

Registry

Browse and install community-curated MCP servers:

mcpforge search                     # browse all servers
mcpforge search payments            # search by keyword or tag
mcpforge add stripe                 # generate Stripe MCP server instantly
mcpforge add stripe --pick          # generate and customize tools

Publish your optimized server:

mcpforge auth login                 # one-time GitHub login
mcpforge publish                    # publish from current project dir
mcpforge publish --slug my-api --tags payments,billing

What MCPForge Does

• Parses OpenAPI 3.0, 3.1, and Swagger 2.0 specs from local files or URLs
• Scrapes docs pages and infers an API shape with Claude when no spec exists
• Curates raw endpoints into a smaller endpoint toolset with --optimize
• Plans task-oriented workflow tools with --workflows
• Generates a complete TypeScript MCP server with auth scaffolding and docs
• Preserves OpenAPI success-response schemas as MCP outputSchema and structuredContent
• Generates OAuth token handling for client credentials and refresh-token renewal
• Detects upstream spec drift and reports risk-scored breaking changes
• Verifies generated request compatibility over stdio with mcpforge test

Feature Overview

• Workflow planning - Generates first-class workflow tools with deterministic step execution. Workflow tools depend on real upstream operations, so drift can be tracked during diff and update.
• AI endpoint curation (--optimize) - Uses Claude to cap noisy APIs to a smaller, better-described public surface. Strict mode defaults to <=25 tools. Standard mode allows broader coverage up to 80.
• Docs URL inference (--from-url) - Scrapes API docs pages and infers endpoints when there is no public OpenAPI spec.
• Interactive selection (--pick) - Lets you choose the exact public tools to expose after planning and optimization.
• Breaking change detection (diff) - Compares stored source IR against the latest upstream spec and reports high, medium, and low-risk changes.
• Workflow-aware update flow (update) - Rechecks upstream APIs, reports workflow impact, and regenerates in place.
• Generated-server verification (test) - Installs dependencies, builds the generated project, validates listTools, and verifies request construction against a local mock upstream before optional live calls.
• Structured tool outputs - Carries documented success-response schemas into MCP tool registration and returns machine-readable structuredContent alongside the text fallback. Generated workflows inherit the output contract when they return a complete endpoint result.
• OAuth token lifecycle support - OAuth-backed generated servers can use a static ACCESS_TOKEN, fetch client-credentials tokens, or renew access tokens from OAUTH_REFRESH_TOKEN.
• Operation-specific security - Preserves public overrides, alternative auth methods, combined schemes, and operation OAuth scopes instead of flattening security across the API.
• Repo-level CI and tests - The repo now includes Vitest coverage for workflow planning, generation, diffing, and selection logic, plus a GitHub Actions workflow.
• Verification-aware publishing (publish) - Public registry publishing now requires a successful verification run by default, and registry entries expose verification metadata to installers.

Commands

Workflow Mode

--workflows adds a planning layer on top of the parsed API:

• MCPForge starts from the parsed endpoint IR.
• If --optimize is enabled, it first curates which endpoints matter most.
• It then plans workflow tools around useful jobs and can keep a few curated endpoint fallbacks when needed.
• Each workflow stores which upstream operations it depends on, so future diff and update runs can report impact when those operations change.

Current workflow execution is intentionally deterministic:

• Linear steps only
• No arbitrary code generation
• Input mapping from workflow inputs and prior step results
• Output selection from saved step results

AI Optimization

Use --optimize with init or generate to run Claude-based endpoint curation.

npx mcpforge init --optimize https://api.example.com/openapi.json

The optimizer:

• Curates to <=25 endpoint tools by default in strict mode
• Rewrites descriptions to be shorter and more LLM-friendly
• Removes admin, health, docs, and other low-value routes
• Prioritizes the endpoints most likely to matter for common user tasks

Use --standard for broader coverage or --max-tools <n> for a custom cap.

Requires ANTHROPIC_API_KEY. If it is missing, optimization is skipped and generation continues.

Configuration

Generated projects include mcpforge.config.json. It stores:

• Spec source and source type
• Output directory
• Optimization settings
• Whether workflow planning is enabled
• Saved public tool selections
• Source IR, optimized IR, planned workflow IR, and final generated IR

That file is what makes generate, diff, and update work without repeating the original setup step.

Testing Generated Servers

Run from inside a generated project:

npx mcpforge test

Or point at a generated project explicitly:

npx mcpforge test --dir ./mcp-server-my-api

By default, mcpforge test:

• runs npm install and npm run build
• starts the generated server over stdio
• verifies listTools matches mcpforge.config.json
• verifies registered input and output schemas match the generated IR
• starts a local mock upstream server and points API_BASE_URL at it
• calls each public tool with generated compatibility inputs
• verifies path, query, header, auth, OAuth token acquisition, and request-body construction for the supported matrix
• writes verification metadata back to mcpforge.config.json

Use --live only when the generated project's .env is configured and you want real upstream API calls.

Successful verification is what enables mcpforge publish by default.

Compatibility Matrix

Current verified request compatibility covers:

• Auth: header API keys, query API keys, cookie API keys, bearer tokens, basic auth, OAuth client credentials, and OAuth refresh-token renewal
• Request bodies: application/json, application/x-www-form-urlencoded, multipart/form-data, text payloads, and binary-compatible payloads
• Responses: OpenAPI 3.x media-type schemas and Swagger 2.0 response schemas exposed as structured MCP output
• Verification path: local mock-upstream validation via mcpforge test

OAuth notes:

• Browser-based authorization-code login is not generated.
• For OAuth APIs, generated servers can use a ready-to-use ACCESS_TOKEN, client credentials via OAUTH_TOKEN_URL, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET, or refresh-token renewal via OAUTH_REFRESH_TOKEN.
• mcpforge test supplies a local mock OAuth token endpoint so generated request verification does not need live provider credentials.

Tested Compatibility

MCPForge has been exercised against real-world specs across different formats and edge cases.

Spec compatibility and runtime verification are separate concerns:

• Spec compatibility: parse, inspect, generate, and compile against varied OpenAPI/Swagger inputs.
• Runtime verification: validate generated request construction against the supported auth/body matrix.

The registry is also the fastest place to find tested, optimized servers that were already run through MCPForge and published for reuse.

Supports OpenAPI 3.0, 3.1, Swagger 2.0, JSON and YAML, circular $refs, and specs with missing operation IDs. The broader compatibility report is in examples/compatibility-report.md.

An example verification output is in examples/verification-report.md.

Contributing

Contributions are welcome. Open an issue for bugs or ideas, or submit a focused PR. Registry contribution rules live in registry/CONTRIBUTING.md.

License

MIT