mcp-gen

Turn your typed TypeScript functions into an MCP server. No schema library, no decorators, no boilerplate — the schema is inferred from your types.

mcp-genreads exported TypeScript functions and generatesModel Context Protocoltool, resource, and promptdefinitions from them — using the TypeScript type checker (viats-morph) to turn each parameter type into a JSON Schema and each JSDoc comment into a description. It can emit the schemas as JSON, serve a live MCP server, or open alive playgroundwhere you call your tools in a browser while you edit.

// tools.ts /  Greets a person by name and age.  @param name - The person's name  @param age - The person's age in years / export function greet(name: string, age: number): string { return Hello ${name}, age ${age}; } /  Echoes a message back after a tick.  @param msg - The message to echo back / export async function slowEcho(msg: string): Promise<string> { return echo: ${msg}; }

{ "tools": [ { "name": "greet", "description": "Greets a person by name and age.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "The person's name" }, "age": { "type": "number", "description": "The person's age in years" } }, "required": ["name", "age"] } } // ... slowEcho ] }

mcp-gen dev tools.ts # then open the printed http://127.0.0.1:4000/ URL

/  Read a user record by id.  @resource users://{id} — templated: {id} matches the id param  @param id - The user id / export function getUser(id: string): { id: string; name: string } { return { id, name: User ${id} }; } /  The current app configuration.  @resource config://app — static: no placeholders / export function appConfig() { return { theme: "dark", version: "1.1.0" }; } /  @resource info://build  @mime text/plain — override the content type / export function buildInfo(): string { return "mcp-gen build 1.1.0"; }

/  A code-review prompt.  @prompt  @param language - The programming language  @param code - The code to review / export function reviewPrompt(language: string, code: string): string { return Please review this ${language} code:\n\n${code}; }

mcp-gen <file.ts> [--debug] [--tsconfig <path>] Generate tool schemas as JSON (stdout) mcp-gen serve <file.ts> [--port N] [--host <addr>] [--api-key <key>]... [--tsconfig <path>] Start a live MCP server (default port 3000; binds 127.0.0.1; PORT/HOST env honored) mcp-gen dev <file.ts> [--port N] [--tsconfig <path>] Live playground UI, watches + reloads (default port 4000) mcp-gen check <file.ts> [--update] [--snapshot <path>] [--tsconfig <path>] Guard the tool surface against breaking changes (CI)

Generation writes machine-readable JSON tostdout(always includestools; includeserrors/warningswhen present); human-readable messages go tostderr. Exit codes:

To runserveas a network-reachable MCP server, bind a public interfaceandrequire a bearer token. Pass the keys through the environment (not--api-key) so the secret never lands in shell history or a process listing:

# one or more comma-separated keys; every caller must send Authorization: Bearer <key> MCP_GEN_API_KEYS="$(openssl rand -hex 32)" mcp-gen serve tools.ts --host 0.0.0.0

- Keys via env in prod, not the CLI.--api-keyis convenient for local testing, but a flag is visible to anyone who can list processes (ps);MCP_GEN_API_KEYSkeeps the secret out ofargv. Both sources are unioned, comma-split, and trimmed, and any non-empty key turns auth on.
- PORT/HOSTare honored.When you omit--port/--host,servefalls back to thePORTandHOSTenvironment variables before its defaults (3000/127.0.0.1) — so it drops straight into a platform that injectsPORT. An explicit--port/--hostflag always overrides the env var.
- Auth is fail-closed.With keys configured, a request to/mcpcarrying a missing, malformed, or non-matching token is rejected with401 {"error":"unauthorized"}beforethe MCP transport — so no tool, resource, or prompt code runs. Keys are compared in constant time.
- No keys = exposed and unauthenticated.Bind a non-loopback--host(orHOST) without any key configured andservekeeps printing the loud exposure warning. Configure a key to gate the endpoint (and silence the warning).

On a platform that injectsPORT(and optionallyHOST), you supply only the keys:

MCP_GEN_API_KEYS="key-a,key-b" mcp-gen serve tools.ts --host 0.0.0.0 # PORT taken from the environment

checkistscfor your tool surface: it snapshots the generated tools to a committed file and, on later runs, fails the build onbreakingchanges — so an agent-facing tool can't silently change shape under its callers.

mcp-gen check tools.ts --update # write the baseline (the jest -u of tool contracts) — commit it mcp-gen check tools.ts # in CI: fail if the surface broke

Breaking changes (exit1) are judged from the perspective of an existing caller: a tool removed or renamed, a property removed, anew requiredparameter, an optional param made required, a type change, an enum value removed, or any other narrowing of a nested sub-schema. Purely additive or loosening changes — a new tool, a newoptionalparam, a relaxed requirement, a new enum value — aresafeand never fail. Description and return-type changes are reported asnotices.

The snapshot is deterministically normalized (tools and keys sorted, stable formatting), so it stays byte-stable and reviews cleanly in a PR. Defaults to<file>.mcp-snapshot.json; override with--snapshot.

devis a type-aware playground for the server a file defines. It watches the file, regenerates the tool surface on every save, and serves a tinylocalhostweb UI:

mcp-gen dev tools.ts # then open the printed URL, e.g. http://127.0.0.1:4000/

Open the printed URL in a browser. For each tool it renders an input form from the inferred schema (string → text, number → number, boolean → checkbox, enum → dropdown, arrays/objects → a raw-JSON box), runs the tool on demand, and shows theresult, thegeneratedinputSchema, and theraw JSON-RPCrequest/response — the inspector view. Fail-loud excluded functions are listed greyed out with their reasons. Save the file and the page reloads itself, preserving what you'd typed.

Crucially, the playground runs each tool through theexact same pathasmcp-gen serve— the same module loader and the same named→positional dispatch — so what you see in the browser is what the served server does. It binds127.0.0.1only (it executes your local code on request, so it is never exposed off-machine), defaults to port4000, and follows the same exit-code discipline asserve.

Commit the*.mcp-snapshot.jsonfile— it's the baseline every latercheckcompares against, not build output. Don't add it to.gitignore; check it in alongside your code so a PR's diff shows exactly how the tool surface changed.

The package is scoped (@zodromon/mcp-gen), but the command you run is justmcp-gen:

git clone https://github.com/zodromon/mcp-gen && cd mcp-gen npm install npm run build # → dist/ node dist/generate-mcp-schemas.js tools.ts

During development you can run it directly without building:

Requires Node.js. Dependencies:@modelcontextprotocol/sdk,ts-morph,typescript,jiti.

Good for:quickly exposing existing typed functions as MCP tools — internal tools, prototypes, anything where you'd rather not hand-write tool schemas.

Not trying to bethe biggest MCP framework. It does one thing. If you want decorators, a plugin system, or a managed platform, other good tools fit better:

- FastMCP— mature and popular; you declare params via a schema library (Zod/ArkType/Valibot).
- simply-mcp-ts— decorator / functional / programmatic APIs.
- The official MCP SDK— maximal control, more boilerplate.

Run parallel, resumable, human-operable Antigravity CLI sessions from Codex, Claude Code, or any MCP-capable agent harness.