TypeMCP is a decorator-first TypeScript package for describing an MCP server and compiling that description at an explicit application boundary. The published package is @theorvane/type-mcp@0.3.0.
Published boundary: TypeMCP provides declaration metadata, definition validation, MCP SDK compilation, an explicit resolver seam, a stdio helper, a Fetch Streamable HTTP adapter, and a tools-only LangChain adapter. Applications retain ownership of hosting, authorization, persistence, models, LangGraph composition, and deployment.
| Goal | Read this | Published surface |
|---|---|---|
| Inspect a declaration before exposing it | Core concepts | Root decorators and getMcpServerDefinition() |
| Run over stdio for an MCP-capable local client | Choose a runtime boundary | startStdioServer() |
| Serve Streamable HTTP from a Fetch or Next.js route | HTTP framework integration | @theorvane/type-mcp/http |
| Reuse tools with LangChain or an application-owned LangGraph graph | LangChain and LangGraph | @theorvane/type-mcp/langchain |
| Start a strict Petstore project | Petstore project setup | ESM, Stage 3 decorators, and application client seam |
| Compile and run the first local server | Petstore TypeMCP foundation | Explicit resolver plus startStdioServer() |
| Follow one small end-to-end example | Petstore walkthrough | Root compiler plus a selected boundary |
| Inspect exact decorators and resolver contracts | Decorator API contract | Semver-governed package API |
- Declarations —
@McpServer,@McpTool,@McpResource, and@McpPromptdescribe an MCP surface next to application methods. - Definitions —
getMcpServerDefinition()reads a frozen declaration snapshot for application inspection. - Compilation —
createMcpServer()validates the definition, resolves one application instance, and compiles the supported surface into the official MCP SDK server. - Runtime boundary — select stdio, Fetch Streamable HTTP, or tools-only LangChain reuse only when the application needs that boundary.
Read core concepts before selecting a transport, then use the Petstore walkthrough to see the same declaration progress through a real choice.
- Petstore project setup — a new strict TypeScript workspace and application-owned client seam.
- Petstore TypeMCP foundation — inspect, compile through an explicit resolver, and run stdio locally.
- Getting started — install, configure standard decorators, declare, and inspect a server.
- Core concepts — definitions, validation/compiler, resolver, and responsibility boundaries.
- Petstore walkthrough — a compact catalog server from declaration to selected integration.
- Choose a runtime boundary — root, stdio, HTTP, or tools-only LangChain selection.
- HTTP framework integration — Fetch and Next.js route shape.
- LangChain and LangGraph integration — structured tools and consumer-owned graph composition.
- Configuration and compatibility — Node, ESM/CommonJS, and TypeScript configuration.
- Agent integration guide — evidence-first workflow for coding agents.
- Decorator API contract — public declarations, compiler, resolver, and transport contracts.
- Architecture overview — published component flow.
- MVP scope — published, deferred, and excluded capabilities.
- Standalone HTTP example — compile, initialize, list, and call a
find-producttool in memory through Fetch-compatible Streamable HTTP. - LangGraph ToolNode example — convert a decorated tool to a LangChain tool and pass it to an application-owned
ToolNode.
- Implemented: present in merged code and verified by tests.
- Planned: approved interface or behavior not yet merged.
- Deferred: explicitly outside the current published scope.
Planning, release, and product-history documents remain available under docs/planning/, docs/product/, and docs/architecture/. They are not installation or API references; check the published boundary above before treating any claim as installed behavior.