Documentation / Start

Core concepts

This page explains the published @theorvane/type-mcp@0.2.2 (opens in a new tab) model before you choose a runtime boundary.

Responsibility boundary: TypeMCP provides declaration metadata, validation, MCP SDK compilation, and selected adapters. Applications retain ownership of hosting, authorization, persistence, models, LangGraph composition, and deployment.

A declaration is not a deployment

Decorators describe an MCP-facing contract on ordinary application methods:

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

@McpServer({ name: "petstore", version: "1.0.0" })
export class PetstoreServer {
  @McpTool({
    name: "find-product",
    description: "Find a Petstore product by SKU.",
    input: z.object({ sku: z.string().min(1) }),
  })
  findProduct({ sku }: { readonly sku: string }) {
    return { sku, available: true };
  }
}

@McpServer records server identity. @McpTool records a public name, description, and Zod object input schema. Resource and prompt decorators work the same way for their supported static contracts. The decorators do not start a process, open a network listener, select a web framework, read credentials, or authorize a caller.

Read a definition at an application boundary

Use getMcpServerDefinition() when application code needs to inspect the contract before exposing it:

import { getMcpServerDefinition } from "@theorvane/type-mcp";
import { PetstoreServer } from "./petstore-server.js";

const definition = getMcpServerDefinition(PetstoreServer);
if (definition === undefined) {
  throw new Error("PetstoreServer is missing @McpServer metadata.");
}

console.log(definition.tools.map((tool) => tool.name));
// ["find-product"]

The returned definition container, component arrays, and component records are frozen snapshots. A tool's Zod schema retains its original identity because executable schemas cannot safely be cloned or frozen. Treat a schema supplied to a decorator as immutable.

Compile with an explicit instance resolver

createMcpServer() validates the decorated definition, resolves an instance, and produces an official MCP SDK server. The resolver is the boundary where the application can supply a service, repository, or API client:

import {
  createMcpServer,
  type InstanceResolver,
} from "@theorvane/type-mcp";
import { PetstoreServer } from "./petstore-server.js";

const resolver: InstanceResolver<PetstoreServer> = {
  resolve: () => new PetstoreServer(),
};

const server = await createMcpServer(PetstoreServer, resolver);

For a zero-argument class, the default resolver is available. For a dependency-requiring class, supply the explicit InstanceResolver; TypeMCP does not discover an application container or construct your dependencies.

Choose the smallest runtime boundary

Read Choose a runtime boundary for complete code at each boundary. The Petstore walkthrough uses the same declaration to make the choice concrete.

What to read next

• Petstore walkthrough — declaration, resolver, and three supported paths.
• Decorator API contract — all public options and exclusions.
• HTTP framework integration — Fetch/Next.js route shape.
• LangChain and LangGraph integration — tools-only adapter and consumer-owned graph composition.

View source at 9124c25519f3 (opens in a new tab)