SpecBridge

Translations: 한국어

SpecBridge MCP is a clone-and-own MCP starter for exposing API contract intelligence to AI agents. It works with OpenAPI documents directly and with Huma services through the OpenAPI documents Huma emits, turning those contracts into deterministic endpoint metadata, schemas, validation facts, referenced DTOs, and TypeScript declarations that agents can use before changing frontend or client code.

This project is intentionally repository-first rather than npm-published: clone it, adapt the backend registry to your private or public specs, and register the local MCP server with your agent host. The implementation keeps the core unopinionated by avoiding downstream file mutation, using a neutral public demo backend, supporting multiple injected backends, and treating inferred helpers as best-effort rather than guarantees.

Status: experimental. The tool surface is useful for local automation, but the repository is meant to be owned and adapted by each team.

Brief history

SpecBridge MCP started as a personal internal tool at SesameLab to improve the development cycle around backend API contracts, including Huma-backed services. In practice, giving AI agents structured contract data through MCP reduced hallucinations compared with asking them to read API documentation pages directly.

Huma support status

Huma is supported through the OpenAPI-compatible documents that Huma services expose. That path has been smoke-tested with Huma-generated specs, JSON/YAML loading, and Unicode descriptions, but it is not yet a broad Huma conformance suite across many real services. Treat Huma support as intentionally supported and actively maturing rather than exhaustively proven.

What it provides

• Configurable backend registry for one or many API contract specs
• Huma-compatible support through Huma-generated OpenAPI JSON/YAML documents
• Zero-config demo backend using a real public Swagger/OpenAPI URL
• Spec loading and refresh with JSON/YAML support
• Endpoint listing and filtering
• Endpoint contract bundles with deterministic facts:
  • operation metadata
  • parameters
  • request and response schemas
  • referenced component schemas
  • endpoint-scoped TypeScript DTO declarations
  • validation facts such as required, nullable, enum, format, arrays, maps, and composition
• TypeScript DTO declaration generation from component schemas
• Best-effort proposal helpers that are explicitly secondary to deterministic spec facts

Project structure

.
├── README.md                         # User-facing setup, configuration, tool, and extension docs
├── README.ko-KR.md                   # Korean translation of README.md
├── AGENTS.md                         # Agent-facing project guide for future coding agents
├── package.json                      # pnpm scripts, runtime dependencies, and package metadata
├── tsconfig.json                     # Strict TypeScript build config; emits compiled JS into build/
├── biome.json                        # Biome formatter/linter config; excludes local-only backend config
├── mcp-server.sh                     # Thin shell wrapper that builds when needed and starts the MCP server
├── openapi.backends.example.json     # Committed working demo backend registry to copy for local use
├── openapi.backends.json             # Ignored local backend registry; create from the example when needed
├── src/
│   ├── index.ts                      # CLI entrypoint plus stdio/stateful HTTP/stateless HTTP transports
│   ├── mcp/register-tools.ts         # MCP tool registration and tool-level orchestration
│   └── openapi/
│       ├── config.ts                 # Backend registry loading, env precedence, defaults, and cache settings
│       ├── spec.ts                   # Spec fetching, parsing, endpoint lookup, schema facts, and DTO emission
│       └── types.ts                  # Shared OpenAPI/Huma-compatible contract types
├── tests/
│   ├── schema-dto.test.mjs           # Unit coverage for registry behavior, parsing, DTOs, and contract facts
│   ├── privacy.test.mjs              # Guardrail to keep publishable files free of internal/private tokens
│   └── e2e/mcp-stdio.test.mjs        # MCP stdio smoke test for representative tool calls
└── build/                            # Generated output from pnpm build; do not edit directly

The src/openapi directory name refers to the contract wire format. Huma support flows through the OpenAPI-compatible JSON/YAML documents generated by Huma services.

Non-goals

• Publishing this project to npm for v1
• Providing a generic installable CLI abstraction
• Mutating downstream frontend/client repositories
• Becoming a framework-specific client or SDK generator
• Hosting specs or storing team API data remotely

Requirements

• Node.js 18+
• pnpm 10+

Install

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

Configure backends

SpecBridge includes a built-in public demo backend, so the tools work even when no local backend registry exists. Huma services are supported by pointing specUrl at the OpenAPI JSON/YAML document exposed by Huma, such as /openapi.json, /openapi.yaml, or your service-specific docs route.

Local backend definitions live in openapi.backends.json. This file is intentionally ignored by Git because it may contain private, local, or environment-specific API URLs.

The committed openapi.backends.example.json file contains a working Swagger Petstore demo backend. To create your local backend registry after cloning the repository:

cp openapi.backends.example.json openapi.backends.json

You can keep the copied demo backend to verify the MCP tools, replace it with an empty array ([]), or add your own backend definitions as needed:

[
  {
    "id": "local-service",
    "name": "Local Huma Service",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local Huma/OpenAPI contract",
    "domainHints": ["/users", "/orders"]
  }
]

Alternatively, point OPENAPI_BACKENDS_FILE at another JSON file or set OPENAPI_BACKENDS directly.

Naming note: Huma vs OpenAPI

Huma emits OpenAPI-compatible contract documents, so some repository internals, tool names, and environment variables still use openapi in their names. Treat those names as references to the contract wire format, not as a limitation to non-Huma APIs. The MCP tools are intended for both plain OpenAPI specs and Huma-generated specs, with the Huma path still described as maturing until it has broader fixture coverage.

Configuration precedence

For a tool call, an explicit specUrl override is tried first for that call.

Backend registry sources are merged in this order, with later sources overriding earlier ones by id:

1. Built-in public demo backend
2. Repository-local openapi.backends.json, when present
3. OPENAPI_BACKENDS_FILE, when set
4. OPENAPI_BACKENDS, when set

DEFAULT_BACKEND_ID selects the default backend. If unset, SpecBridge uses swagger-petstore.

Environment variables

• MCP_TRANSPORT: stdio or http
• MCP_HTTP_HOST: HTTP bind host
• MCP_HTTP_PORT: HTTP port
• MCP_HTTP_PATH: MCP endpoint path, such as /mcp
• MCP_HTTP_STATELESS: set to true for stateless HTTP mode
• DEFAULT_BACKEND_ID: default backend ID
• OPENAPI_BACKENDS: JSON array of backend configs
• OPENAPI_BACKENDS_FILE: path to a backend config JSON file
• OPENAPI_FETCH_TIMEOUT_MS: fetch timeout for spec loading
• OPENAPI_CACHE_TTL_MS: in-memory spec cache TTL
• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: opt in to strict JSON object extraction from static Swagger UI scripts; fetched JavaScript is never executed

Run

stdio mode

pnpm mcp
# or
./mcp-server.sh

HTTP mode

pnpm mcp:http

Stateless HTTP mode:

pnpm mcp:http:stateless

MCP host setup

Command-based stdio configuration

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Codex config.toml example

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP URL

Start the server:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

Then connect your host to:

• http://127.0.0.1:3000/mcp

If your host has trouble with session state, retry with --stateless.

Example prompts for AI agents

After this MCP server is connected to an agent host, human users can ask their AI agents contract-aware questions or implementation requests in natural language. The agent should use SpecBridge MCP tools as the source of contract data instead of guessing from memory or scraping documentation pages directly.

Examples:

• "What backend services are available, and which backendId should I use for the school API?"
• "List the endpoints related to student attendance, then show the request and response contract for the endpoint I should call."
• "Using SpecBridge MCP, add the missing API model types and endpoint wrappers for the new student attendance endpoints in this codebase."
• "Check whether the API contract has changed since this client code was written. If it has, update the affected DTOs, endpoint functions, and tests."

For implementation requests like these, SpecBridge provides the contract facts; the AI agent still decides how to modify the current codebase and should verify the resulting code with that project's tests.

Useful agent instructions:

• "Use SpecBridge MCP only for API contract facts."
• "Call list_backends first, then use the returned backendId for later calls."
• "Do not directly visit private spec URLs; read contract data through the MCP tools."
• "Treat propose_new_endpoint output as a proposal, not as source-of-truth contract data."

Tools

Recommended flow:

1. list_backends
2. load_openapi_spec
3. list_api_endpoints
4. get_endpoint_contract
5. generate_typescript_dto

list_backends

Lists configured backend targets, the default backend ID, and optional domain hints.

load_openapi_spec

Loads or refreshes an OpenAPI-compatible contract document for a backend, including Huma-generated OpenAPI specs. Supports direct specUrl overrides.

list_api_endpoints

Lists endpoints from a loaded spec with optional tag, method, path substring, and limit filters.

get_endpoint_contract

Returns a deterministic endpoint contract bundle: operation metadata, parameters, request body, responses, referenced schemas, endpoint-scoped TypeScript DTO declarations, validation facts, and best-effort hints.

generate_typescript_dto

Generates TypeScript DTO declarations from a component schema name and includes referenced nested DTO types.

propose_new_endpoint

Returns a best-effort endpoint and DTO proposal aligned with patterns found in the current contract spec. Treat this as an agent aid, not a deterministic guarantee.

Extending with additional service layers

SpecBridge is intentionally small, so the safest extension pattern is to add one focused layer at a time and keep MCP tools thin.

Add another backend service from configuration only

If the service already exposes an OpenAPI or Huma-generated OpenAPI document, no code changes are required. Add it to your ignored local openapi.backends.json, or provide it through OPENAPI_BACKENDS_FILE/OPENAPI_BACKENDS:

[
  {
    "id": "billing-service",
    "name": "Billing Service",
    "specUrl": "https://billing.example.com/openapi.json",
    "fallbackSpecUrls": ["https://billing.example.com/openapi.yaml"],
    "description": "Billing API contract",
    "domainHints": ["/invoices", "/payments"]
  }
]

Use stable, lowercase id values because agents pass backendId back into every tool call. Add domainHints when multiple services may contain similarly named resources; they power endpoint-not-found suggestions.

Add code for a new service layer

Use this path when a service needs custom discovery, auth, post-processing, or tools that are not generic OpenAPI/Huma contract operations.

1. Keep transport concerns in src/index.ts; do not add service-specific behavior there.
2. Put shared service types in a focused types.ts file near that service layer.
3. Put configuration and environment parsing in a focused config.ts file. Keep precedence explicit and test it.
4. Put deterministic contract or service logic in a pure module. Avoid mutating downstream repositories from this MCP server.
5. Register MCP-facing operations in src/mcp/register-tools.ts, or split registration into a service-specific register-*.ts module if the file becomes too large.
6. Return both content and structuredContent from tools so agents can read human-friendly text and machine-friendly JSON.
7. Add tests before relying on the layer: unit tests for parsing/edge cases, and an MCP smoke test when a new tool is exposed.

Good extension boundaries look like this:

src/
├── mcp/
│   ├── register-tools.ts             # calls registerOpenApiTools + any new registerXTools helpers
│   └── register-billing-tools.ts     # optional if a new service exposes distinct MCP tools
└── billing/
    ├── config.ts                     # billing-specific env/config loading
    ├── contract.ts                   # deterministic billing contract helpers
    └── types.ts                      # billing-specific DTO/helper types

Prefer deterministic facts over inference. When adding best-effort helpers, label them clearly in the output, keep them secondary to spec-derived facts, and include tests that lock the distinction.

Development

pnpm install
pnpm check
pnpm build
pnpm test

Useful scripts:

• pnpm check: Biome check
• pnpm format: apply Biome formatting
• pnpm lint: Biome lint only
• pnpm build: clean TypeScript build
• pnpm test: build and run all tests
• pnpm test:e2e: build and run MCP smoke tests

Clone-and-own guidance

SpecBridge is intentionally repository-first. Keep the core small, adapt backend configuration locally, and let downstream agents decide how to edit your client code. If your team needs custom auth, internal naming rules, or additional contract facts, add them in your clone rather than fighting a global package abstraction.