MCP 服务器

callspec

Provides an MCP server that automatically exposes API routes as MCP tools with input validation and authentication, enabling AI agents to call the same handlers as HTTP RPC.

README

<h3 align="center">One spec ships API, docs UI, OpenAPI, MCP, and typed clients.</h3>

<br>

Define your API once and get an HTTP RPC server, white-label docs, OpenAPI 3.1, an MCP server, and a typed client. No duplicate schemas, no bolt-on doc stack, no hand-maintained tool manifests.

Every API and MCP call gets input validation at the boundary with clear error messages. TypeScript clients get compile-time type checking and LSP autocomplete from the same spec — with simple, clean, human-readable types.

Feature	Location
HTTP RPC API	`POST /v1/<methodName>`
Interactive UI docs	`/docs`
OpenAPI 3.1	`/openapi.json`
MCP tools	`/mcp`
Typed client	`client<API['searchRecent']>('searchRecent', input)`
Input validation	Runtime & compile-time (TypeScript)

Complete Example

import express from 'express';
import {defineSpec, defineRoute, mountSpec} from 'callspec';
import {predicates as p} from 'runtyp';

type AuthContext = {userId: string};

async function searchRecent(
    input: {query: string; max_results?: number},
    ctx: AuthContext,
) {
    return {
        results: [{id: '1', text: `Match for "${input.query}"`, authorId: ctx.userId}],
        count: 1,
    };
}

const api = defineSpec({
    searchRecent: defineRoute({
        input: p.object({
            query: p.string({description: 'Search query (supports from:, #hashtag, …)'}),
            max_results: p.optional(p.number({range: {min: 1, max: 100}})),
        }),
        meta: {
            summary: 'Search recent posts',
            tags: ['posts'],
        },
        access: 'private',
        mcp: true,
        handler: searchRecent,
    }),
});

const app = express();
const router = express.Router();

router.use(express.json());

mountSpec(router, api, {
    contextResolver: (req) => {
        if (req.headers.authorization?.startsWith('Bearer ')) {
            return {userId: 'user_123'};
        }
        return undefined;
    },
    docs: {
        openApi: {title: 'My API', version: '1.0.0'},
        ui: {
            branding: {name: 'My API'},
        },
    },
});

app.use('/v1', router);

const port = Number(process.env.PORT ?? 3000);

app.listen(port, () => {
    console.log(`RPC:      http://127.0.0.1:${port}/v1/searchRecent`);
    console.log(`Docs:     http://127.0.0.1:${port}/v1/docs`);
    console.log(`OpenAPI:  http://127.0.0.1:${port}/v1/openapi.json`);
    console.log(`MCP:      http://127.0.0.1:${port}/v1/mcp`);
    console.log('Auth:     Authorization: Bearer anything (demo token)');
});

Getting started

npm i callspec runtyp express
npm i -D tsx typescript @types/express

Requirements: Node.js 18+, TypeScript 5+, Express 4.x (peer).

Try the demo (in this repo):

npm run build && npm run dev:docs

Open http://127.0.0.1:3456/v1/docs — Chirp sample API. Use Authorization: Bearer demo for private routes and MCP tools.

🔌 Built-in MCP server

Set mcp: true on any defineRoute. When any route opts in, mountSpec mounts MCP at /mcp automatically (override with mcp: { path, serverInfo, instructions }, or mcp: false to disable).

Agents call the same handlers as HTTP RPC — same auth gate, same input validation. Public tools work without a token; private tools return 401 without one. Every tools/call runs through the same runtyp pipeline: field { description }, ranges, and enums flow into MCP inputSchema; invalid args return structured validation errors (not opaque 500s) that agents can read and retry.

📖 callspec UI

Minimal, fast docs UI baked right into the package. Browse routes, try RPCs, read OpenAPI, and connect MCP clients from the home page. Point docs.ui.branding at your product — display name, welcome copy, website link, and logo (light/dark, optional brandAssetsDir for static files at /docs/brand/). Run npm run dev:docs to see the Chirp sample — callspec UI white-labeled as a fictional API.

Env-gated in production; flip on with:

docs: {
    openApi: {title: 'Chirp API v2', version: '2.0.0'},
    exposeOpenApi: true,
    exposeUi: true,
    openApiPath: '/openapi.json',
    uiPath: '/docs',
    ui: {
        branding: {
            name: 'Chirp',
            intro: 'Read and write posts, timelines, lists, and direct messages.',
            websiteUrl: 'https://chirp.social',
            websiteLabel: 'chirp.social',
            logoUrl: './brand/mark.png',
            logoUrlDark: './brand/mark.png',
            logoSize: 80,
        },
        brandAssetsDir: '/path/to/your/logos',
        mcp: {authHint: 'Use Authorization: Bearer demo for private tools in this demo.'},
    },
}

Toggle each surface independently — OpenAPI only, UI only, MCP off (mcp: false), or neither (docs: false).

Light and dark lockups follow prefers-color-scheme in docs; the UI footer switches marks on data-theme the same way as Castellan.

🔐 Auth

access: 'public' — no credentials required (e.g. Chirp healthcheck, getTweet)
access: 'private' (default) — 401 without contextResolver result
App-specific auth stays in your contextResolver (e.g. map Authorization: Bearer … to {userId, username})

Private gate runs before validation so unauthenticated callers never see field-level errors.

🧩 runtyp + OpenAPI

Field { description } on runtyp preds flows to JSON Schema → OpenAPI → callspec UI → MCP inputSchema. Route-level meta (summary, tags) is callspec-only.

📦 Client

Fetch-only — works in the browser and in Node 18+ (global fetch). The callspec/client entry has no http, https, or Express imports, so it is safe in frontend bundles.

Browser or frontend bundler — import the client subpath so you do not pull server code:

import type {API} from './my-api';
import {client} from 'callspec/client';

const results = await client<API['searchRecent']>('searchRecent', {
    query: 'callspec',
    max_results: 10,
}, {
    endpoint: 'https://api.example.com/v1',
    fetchOptions: {headers: {Authorization: `Bearer ${token}`}},
});

Service package — export the API type once from your spec:

import type {InferSpec} from 'callspec';

export const api = defineSpec({
    getTweet: defineRoute({ /* … */ }),
    searchRecent: defineRoute({ /* … */ }),
    createTweet: defineRoute({ /* … */ }),
});
export type API = InferSpec<typeof api>;

Responses deserialize ISO date strings back to Date on read (deserializeResponse).

🛠 Development

npm run validate   # build server + callspec UI, lint, test (incl. integration)
npm run dev:docs   # Chirp demo API + callspec UI at :3456/v1/docs

Integration tests spin up Express in-process and verify OpenAPI, /docs, auth, MCP, and RPC end-to-end.

🤝 Help build the standard

callspec is early — and we're looking for maintainers and contributors who want to help define how typed APIs work in the age of agents.

The goal is simple: one spec → HTTP RPC, docs, OpenAPI, and MCP — no duplicate schemas, no bolt-on tool manifests, no duct-tape between surfaces.

If you join now, you're not polishing someone else's finished spec. You're shaping the defaults: callspec UI UX, MCP ergonomics, client DX, framework adapters, examples, and the docs people copy from. Early contributors tend to become the people others cite — show up in release notes, speak at the meetup, get asked "who built this?" when the pattern spreads.

Good first contributions: callspec UI polish, MCP client configs, docs and demos, runtyp/OpenAPI edge cases, Fastify/Hono mounts, issue triage, or a blog post about your integration.

Issues & ideas: github.com/logfoxai/callspec/issues
PRs welcome — npm run validate before you push; conventional commits (feat:, fix:, docs:, style:, etc.)

If you want maintainer access or a dedicated area to own (callspec UI, MCP, clients, docs), open an issue or PR and say hi. We'd rather have a small crew that cares than a huge drive-by.