# SpecBridge MCP

Translations: [한국어](README.ko-KR.md)

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

```text
.
├── 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

```bash
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:

```bash
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:

```json
[
  {
    "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

```bash
pnpm mcp
# or
./mcp-server.sh
```

### HTTP mode

```bash
pnpm mcp:http
```

Stateless HTTP mode:

```bash
pnpm mcp:http:stateless
```

## MCP host setup

### Command-based stdio configuration

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

### Codex `config.toml` example

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

### HTTP URL

Start the server:

```bash
./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`:

```json
[
  {
    "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:

```text
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

```bash
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.