Theorvane · sjungwon03 · Aug 3, 2026 · Jul 30, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@
   [![License](https://img.shields.io/badge/license-MIT-111827?style=flat-square)](LICENSE)
 </div>
 
-> **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.
+> **Published package — `@theorvane/type-mcp@0.3.0`:** 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.
 
@@ -50,7 +50,7 @@ The package is ESM-first and also exposes a CommonJS root export. TypeScript pro
 }
 ```
 
-Do not enable TypeScript's legacy `experimentalDecorators` mode for these standard decorator examples. See [configuration and compatibility](docs/guides/configuration.md) for ESM, CommonJS, and decorator details.
+Do not enable TypeScript's legacy `experimentalDecorators` mode for these standard decorator examples. For a CommonJS legacy-decorator consumer, use the separate `@theorvane/type-mcp/legacy` entrypoint with Node16 module resolution; its supported surface and constraints are documented in the [Decorator API contract](docs/api/decorator-api.md#legacy-cjs-decorators). See [configuration and compatibility](docs/guides/configuration.md) for ESM, CommonJS, and decorator details.
 
 ## Define and inspect a server declaration
 
@@ -98,11 +98,11 @@ 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](docs/guides/getting-started.md) for the complete version boundary.
+The methods above are ordinary application methods. In `0.3.0`, 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](docs/guides/getting-started.md) for the complete version boundary.
 
 ## Capability map
 
-| Surface | `@theorvane/type-mcp@0.2.2` | What it does |
+| Surface | `@theorvane/type-mcp@0.3.0` | 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. |

diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,6 @@
 # TypeMCP documentation
 
-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.2.2`](https://www.npmjs.com/package/@theorvane/type-mcp).
+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`](https://www.npmjs.com/package/@theorvane/type-mcp).
 
 > **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**.
 

diff --git a/docs/api/decorator-api.md b/docs/api/decorator-api.md
@@ -1,6 +1,6 @@
 # Decorator API contract
 
-**Public package:** [`@theorvane/type-mcp@0.2.2`](https://www.npmjs.com/package/@theorvane/type-mcp) provides decorator declarations, definition validation, MCP SDK compilation for tools/static resources/prompts, a Node stdio helper, and a Fetch Streamable HTTP adapter. LangChain interoperability is isolated at `@theorvane/type-mcp/langchain`.
+**Public package:** [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) provides decorator declarations, definition validation, MCP SDK compilation for tools/static resources/prompts, a Node stdio helper, and a Fetch Streamable HTTP adapter. LangChain interoperability is isolated at `@theorvane/type-mcp/langchain`.
 
 ## Server declaration
 
@@ -117,6 +117,33 @@ export { handler as GET, handler as POST, handler as DELETE };
 
 `getMcpServerDefinition()` returns a newly allocated, frozen server definition, component arrays, and component records on every read. Tool `input` schemas retain the caller-supplied Zod object-schema identity: schemas are executable mutable objects and are not cloned or frozen by TypeMCP. Consumers should treat a schema supplied to a decorator as immutable after declaration.
 
+## Legacy CJS decorators
+
+`@theorvane/type-mcp/legacy` is the compatibility entrypoint for TypeScript's
+legacy `experimentalDecorators` emit in CommonJS applications.
+It exposes `McpServer`, `McpTool`, `McpResource`, and `McpPrompt` with the same
+options and definition-reader/compiler contracts as the root Stage 3 API.
+
+```ts
+import { z } from "zod";
+import { McpServer, McpTool } from "@theorvane/type-mcp/legacy";
+
+@McpServer({ name: "catalog", version: "1.0.0" })
+class CatalogServer {
+  @McpTool({ input: z.object({ sku: z.string() }) })
+  findProduct({ sku }: { readonly sku: string }) {
+    return { sku };
+  }
+}
+```
+
+Use `"module": "Node16"`, `"moduleResolution": "Node16"`, and
+`"experimentalDecorators": true` for a CommonJS consumer so TypeScript selects
+the package's CJS declaration condition. The legacy entrypoint supports public
+instance methods with string names only; parameter, accessor, field, private,
+and symbol-named decorators are excluded. Do not mix Stage 3 and legacy
+decorators in one TypeScript compilation unit.
+
 ## Compatibility policy
 
 Public decorator option names, exported definitions, `InstanceResolver`, compiler and transport entry points, and handler signatures are semver-governed. Any breaking change requires an ADR, migration note, and a major release decision.
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -1,6 +1,6 @@
 # Architecture overview
 
-> **Public release:** [`@theorvane/type-mcp@0.2.2`](https://www.npmjs.com/package/@theorvane/type-mcp) implements the metadata, validation, resolver, compiler, stdio, HTTP, and LangChain adapter surfaces described here. Applications remain responsible for hosting and lifecycle policy.
+> **Public release:** [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) implements the metadata, validation, resolver, compiler, stdio, HTTP, and LangChain adapter surfaces described here. Applications remain responsible for hosting and lifecycle policy.
 
 ## Package surface
 

diff --git a/docs/guides/agent-integration.md b/docs/guides/agent-integration.md
@@ -1,6 +1,6 @@
 # Agent integration guide
 
-This guide gives coding agents a deterministic procedure for adding TypeMCP declarations without inventing application-owned policy. It applies to the published `@theorvane/type-mcp@0.2.2` package.
+This guide gives coding agents a deterministic procedure for adding TypeMCP declarations without inventing application-owned policy. It applies to the published `@theorvane/type-mcp@0.3.0` package.
 
 ## Capability contract agents must honor
 

diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md
@@ -1,13 +1,13 @@
 # Configuration and compatibility
 
-`@theorvane/type-mcp@0.2.2` is the published TypeScript declaration and runtime package. Configuration determines whether TypeScript emits standard decorators and whether the runtime can resolve the package's ESM/CJS exports; applications configure their own hosting and transport lifecycle around installed MCP adapters.
+`@theorvane/type-mcp@0.3.0` is the published TypeScript declaration and runtime package. Configuration determines whether TypeScript emits standard decorators and whether the runtime can resolve the package's ESM/CJS exports; applications configure their own hosting and transport lifecycle around installed MCP adapters.
 
 ## Runtime and package manager
 
-Use Node.js 20 or later. After `npm view @theorvane/type-mcp@0.2.2 version` succeeds, install TypeMCP and Zod as application dependencies:
+Use Node.js 20 or later. After `npm view @theorvane/type-mcp@0.3.0 version` succeeds, install TypeMCP and Zod as application dependencies:
 
 ```bash
-npm install @theorvane/type-mcp@0.2.2 zod
+npm install @theorvane/type-mcp@0.3.0 zod
 ```
 
 The package name and import are scoped to Theorvane:
@@ -16,7 +16,7 @@ The package name and import are scoped to Theorvane:
 import { McpServer, McpTool } from "@theorvane/type-mcp";
 ```
 
-The public `@theorvane/type-mcp@0.2.2` package exports `@theorvane/type-mcp/http`. Add it where the application owns Fetch route hosting, durable session policy, and authorization; the adapter owns in-process MCP session routing around the SDK transport.
+The public `@theorvane/type-mcp@0.3.0` package exports `@theorvane/type-mcp/http`. Add it where the application owns Fetch route hosting, durable session policy, and authorization; the adapter owns in-process MCP session routing around the SDK transport.
 
 ## TypeScript decorators
 
@@ -67,10 +67,10 @@ find({ id }: z.infer<typeof findInput>) {
 }
 ```
 
-A missing component `name` defaults to the method name. `0.2.2` validates the decorated definition before compilation; application tests should still protect domain naming conventions.
+A missing component `name` defaults to the method name. `0.3.0` validates the decorated definition before compilation; application tests should still protect domain naming conventions.
 
 ## Registry release versus repository development
 
-The published `@theorvane/type-mcp@0.2.2` root exports `McpServer`, `McpTool`, `McpResource`, `McpPrompt`, `getMcpServerDefinition`, `readMcpServerDefinition`, `TypeMcpDefinitionError`, `InstanceResolver`, `resolveMcpServerInstance`, `createMcpServer`, and `startStdioServer`. The `@theorvane/type-mcp/http` and `@theorvane/type-mcp/langchain` subpaths expose their respective adapters.
+The published `@theorvane/type-mcp@0.3.0` root exports `McpServer`, `McpTool`, `McpResource`, `McpPrompt`, `getMcpServerDefinition`, `readMcpServerDefinition`, `TypeMcpDefinitionError`, `InstanceResolver`, `resolveMcpServerInstance`, `createMcpServer`, and `startStdioServer`. The `@theorvane/type-mcp/http` and `@theorvane/type-mcp/langchain` subpaths expose their respective adapters.
 
 Before upgrading, read the release notes and inspect the package's generated type declarations. Treat a feature as available only when a released version documents it and the installed package exports it.
diff --git a/docs/guides/core-concepts.md b/docs/guides/core-concepts.md
@@ -1,6 +1,6 @@
 # Core concepts
 
-This page explains the published [`@theorvane/type-mcp@0.2.2`](https://www.npmjs.com/package/@theorvane/type-mcp) model before you choose a runtime boundary.
+This page explains the published [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) 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**.
 

diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
@@ -1,13 +1,13 @@
-# Getting started with `@theorvane/type-mcp@0.2.2`
+# Getting started with `@theorvane/type-mcp@0.3.0`
 
-This guide creates and inspects an MCP **declaration** using the published `@theorvane/type-mcp@0.2.2` package. It also validates and compiles decorated definitions through `createMcpServer()`; the [HTTP guide](http-and-nextjs.md) and [LangChain guide](langchain-langgraph.md) cover their focused adapter boundaries.
+This guide creates and inspects an MCP **declaration** using the published `@theorvane/type-mcp@0.3.0` package. It also validates and compiles decorated definitions through `createMcpServer()`; the [HTTP guide](http-and-nextjs.md) and [LangChain guide](langchain-langgraph.md) cover their focused adapter boundaries.
 
 ## Install the package and configure TypeScript
 
 Install the package and import Zod directly in the application that owns its schemas:
 
 ```bash
-npm install @theorvane/type-mcp@0.2.2 zod
+npm install @theorvane/type-mcp@0.3.0 zod
 ```
 
 Run on Node.js 20 or later. Use standard TypeScript decorators with Node-aware ESM settings. A minimal `tsconfig.json` is:
@@ -71,7 +71,7 @@ export class NotesServer {
 }
 ```
 
-The public component name defaults to the method name when `name` is omitted. TypeMCP records these options as metadata and `0.2.2` validates the decorated definition before compilation; use application tests for domain-specific naming conventions.
+The public component name defaults to the method name when `name` is omitted. TypeMCP records these options as metadata and `0.3.0` validates the decorated definition before compilation; use application tests for domain-specific naming conventions.
 
 ## Inspect metadata at an application boundary
 
@@ -100,6 +100,6 @@ The function returns `undefined` for a class without `@McpServer`. For a decorat
 
 ## Continue through the runtime boundary
 
-The published `@theorvane/type-mcp@0.2.2` package contains `createMcpServer()`, `startStdioServer()`, `@theorvane/type-mcp/http`, and `@theorvane/type-mcp/langchain`. TypeMCP validates and compiles decorated definitions through an explicit `InstanceResolver`; it does not choose a web host, authorization model, session store, LangGraph topology, model, or persistence policy for the application.
+The published `@theorvane/type-mcp@0.3.0` package contains `createMcpServer()`, `startStdioServer()`, `@theorvane/type-mcp/http`, and `@theorvane/type-mcp/langchain`. TypeMCP validates and compiles decorated definitions through an explicit `InstanceResolver`; it does not choose a web host, authorization model, session store, LangGraph topology, model, or persistence policy for the application.
 
 The declaration created above remains useful for application-owned inspection. Read [core concepts](core-concepts.md) for the definition/compiler model, then follow the [Petstore walkthrough](petstore-walkthrough.md) to select stdio, HTTP, or LangChain reuse. Consult the [configuration guide](configuration.md), [HTTP guide](http-and-nextjs.md), [LangChain guide](langchain-langgraph.md), and [agent guide](agent-integration.md) before automating a change.
diff --git a/docs/guides/http-and-nextjs.md b/docs/guides/http-and-nextjs.md
@@ -35,4 +35,4 @@ This is a route integration shape, not a full Next.js scaffold. It intentionally
 
 ## Published package boundary
 
-The published `@theorvane/type-mcp@0.2.2` package includes `createMcpServer()` and `@theorvane/type-mcp/http`. This guide demonstrates the package API, while hosting, authentication, persistence, and authorization remain application-owned responsibilities.
+The published `@theorvane/type-mcp@0.3.0` package includes `createMcpServer()` and `@theorvane/type-mcp/http`. This guide demonstrates the package API, while hosting, authentication, persistence, and authorization remain application-owned responsibilities.
diff --git a/docs/guides/langchain-langgraph.md b/docs/guides/langchain-langgraph.md
@@ -1,6 +1,6 @@
 # LangChain and LangGraph integration
 
-> **Published boundary:** `@theorvane/type-mcp/langchain` is part of the published `@theorvane/type-mcp@0.2.2` package. It is tools-only; LangGraph remains a consumer-owned composition choice.
+> **Published boundary:** `@theorvane/type-mcp/langchain` is part of the published `@theorvane/type-mcp@0.3.0` package. It is tools-only; LangGraph remains a consumer-owned composition choice.
 
 ## Scope
 
@@ -16,7 +16,7 @@ The core package and `@theorvane/type-mcp/http` remain independent of agent fram
 The adapter has an optional peer dependency on `@langchain/core`. A consumer that imports the adapter must install a compatible peer:
 
 ```bash
-npm install @theorvane/type-mcp@0.2.2 @langchain/core zod
+npm install @theorvane/type-mcp@0.3.0 @langchain/core zod
 ```
 
 LangGraph is a consumer choice, not an adapter dependency. Install it only when using a graph:

diff --git a/docs/guides/petstore-project-setup.md b/docs/guides/petstore-project-setup.md
@@ -2,7 +2,7 @@
 
 This is the first chapter of the TypeMCP Petstore curriculum. It creates a small local project that can compile a decorated server before the application selects a runtime boundary.
 
-> **Published version:** The examples target [`@theorvane/type-mcp@0.2.2`](https://www.npmjs.com/package/@theorvane/type-mcp). They use standard TypeScript decorators, not legacy `experimentalDecorators`.
+> **Published version:** The examples target [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp). They use standard TypeScript decorators, not legacy `experimentalDecorators`.
 
 ## Before you start
 
@@ -33,7 +33,7 @@ mkdir petstore-workspace
 cd petstore-workspace
 npm init -y
 npm pkg set type=module
-npm install @theorvane/type-mcp@0.2.2 zod
+npm install @theorvane/type-mcp@0.3.0 zod
 npm install --save-dev typescript tsx @types/node
 npm pkg set scripts.check="tsc --noEmit"
 ```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -35,4 +35,4 @@ This is a route integration shape, not a full Next.js scaffold. It intentionally

		## Published package boundary

		The published `@theorvane/type-mcp@0.2.2` package includes `createMcpServer()` and `@theorvane/type-mcp/http`. This guide demonstrates the package API, while hosting, authentication, persistence, and authorization remain application-owned responsibilities.
		The published `@theorvane/type-mcp@0.3.0` package includes `createMcpServer()` and `@theorvane/type-mcp/http`. This guide demonstrates the package API, while hosting, authentication, persistence, and authorization remain application-owned responsibilities.