TypeMCP

Decorator-first MCP declarations for strict TypeScript.

Published package — @theorvane/type-mcp@0.2.2: provides standard decorators, definition validation, explicit instance resolution, MCP SDK compilation, stdio, @theorvane/type-mcp/http Streamable HTTP, and the tools-only @theorvane/type-mcp/langchain adapter.

Integration boundary: LangGraph ToolNode composition, graph topology, model choice, authorization, state, persistence, and deployment remain consumer responsibilities.

TypeMCP keeps MCP declarations beside TypeScript classes without coupling the core to a web framework. Install it when you need strict declarations, validation, MCP SDK compilation, stdio, or Streamable HTTP while keeping application policy explicit.

Fast path for developers and agents

1. Check the published capability table below and choose only the package entry point your application hosts and authorizes.
2. Install @theorvane/type-mcp with zod.
3. Use standard TypeScript decorators to declare a server surface.
4. Inspect the declaration through getMcpServerDefinition() at an application boundary.
5. Use createMcpServer(), startStdioServer(), or @theorvane/type-mcp/http only when the application owns the surrounding transport, authorization, and lifecycle policy.

Agents should start with the agent integration guide. It defines an evidence-first workflow and prevents unavailable runtime APIs from being mistaken for supported features.

Install

TypeMCP requires Node.js 20 or later and TypeScript with standard (Stage 3) decorator support.

npm install @theorvane/type-mcp zod

The package is ESM-first and also exposes a CommonJS root export. TypeScript projects should use Node-aware module resolution. This tsconfig.json baseline matches the package contract:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Decorators"],
    "strict": true,
    "verbatimModuleSyntax": true
  }
}

Do not enable TypeScript's legacy experimentalDecorators mode for these standard decorator examples. See configuration and compatibility for ESM, CommonJS, and decorator details.

Define and inspect a server declaration

Create src/catalog-server.ts:

import { z } from "zod";
import {
  getMcpServerDefinition,
  McpPrompt,
  McpResource,
  McpServer,
  McpTool,
} from "@theorvane/type-mcp";

@McpServer({ name: "catalog", version: "0.2.0" })
export class CatalogServer {
  @McpTool({
    description: "Look up a catalog item by SKU.",
    input: z.object({ sku: z.string().min(1) }),
  })
  findProduct({ sku }: { sku: string }) {
    return { sku, available: true };
  }

  @McpResource({
    uri: "config://catalog",
    mimeType: "application/json",
    description: "Static catalog configuration.",
  })
  readConfig() {
    return { region: "ap-northeast-2" };
  }

  @McpPrompt({ description: "Prepare a product summary request." })
  summarizeProduct() {
    return "Summarize the selected catalog product.";
  }
}

const definition = getMcpServerDefinition(CatalogServer);
console.log(definition?.name); // "catalog"
console.log(definition?.tools[0]?.name); // "findProduct"

getMcpServerDefinition() returns undefined for a class without @McpServer. For a decorated class, it returns a newly allocated frozen metadata container on every call. Zod schemas retain their original identity, so treat a schema passed to a decorator as immutable after declaration.

The methods above are ordinary application methods. In 0.2.2, use createMcpServer() to validate and compile this declaration through an explicit resolver; choose an adapter exported by the installed package only when the application owns its hosting, authorization, and lifecycle policy. Follow the getting-started guide for the complete version boundary.

Capability map

Surface	@theorvane/type-mcp@0.2.2	What it does
@McpServer	Available	Records server name and version metadata.
@McpTool	Available	Records a method name, optional public name/description, and Zod object schema.
@McpResource	Available	Records a static resource URI and optional metadata.
@McpPrompt	Available	Records a named prompt declaration.
getMcpServerDefinition()	Available	Reads a fresh frozen metadata copy; returns undefined for undecorated classes.
createMcpServer()	Available	Validates declarations and compiles the decorated server surface with an explicit resolver seam.
@theorvane/type-mcp/http / createMcpHandler()	Available	Fetch/Streamable HTTP adapter; TypeMCP owns in-process MCP session routing while applications own route hosting, durable session policy, and authorization.
Definition validation and TypeMcpDefinitionError	Available	Validates declarations and reports safe definition errors.
InstanceResolver<T> / resolveMcpServerInstance()	Available	Explicit application-owned instance construction contract.
@theorvane/type-mcp/langchain / createLangChainTools()	Available	Tools-only LangChain structured-tool adapter; LangGraph ToolNode composition remains consumer-owned.

Documentation map

• Getting started — install, declare, inspect, and compile a TypeMCP server.
• Choose a runtime boundary — select the released root, stdio, HTTP, or tools-only LangChain surface.
• Configuration and compatibility — Node, ESM/CommonJS, TypeScript decorators, schemas, and release boundaries.
• Agent integration guide — evidence-first coding-agent workflow and explicit runtime boundaries.
• HTTP framework integration — published Streamable HTTP example and Fetch/Next.js route shape.
• Standalone HTTP example — exact source and smoke-test commands for the repository implementation.
• LangChain and LangGraph integration — published tools-only adapter and consumer-owned ToolNode composition.
• LangGraph ToolNode example — exact in-memory source example and smoke-test command.
• Decorator API contract — published decorator, validation, compilation, and transport API contract.
• Architecture overview — published runtime and package boundaries.
• MVP scope — published MVP capabilities and explicitly deferred extensions.
• Contributing — contribution workflow and local verification.
• npm package — published releases and install metadata.

Develop locally

git clone https://github.com/Theorvane/type-mcp.git
cd type-mcp
npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run verify:package
npm run verify:publish

Repository changes follow Issue → issue-numbered branch → pull request → review and CI → squash merge. See CONTRIBUTING.md.

License

MIT