diff --git a/README.md b/README.md index b86d649..8ebe6b8 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,7 @@ [![License](https://img.shields.io/badge/license-MIT-111827?style=flat-square)](LICENSE) -> **Published package — `@theorvane/type-mcp@0.3.2`:** provides standard decorators, a separate `@theorvane/type-mcp/legacy` entrypoint for CommonJS legacy 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. -> -> **Current `dev` source:** additionally includes SDK v2 protocol negotiation, modern component metadata, tool output schemas, explicit prompt arguments, resource URI templates, completion, invocation context, protocol-backed testing, image/audio helpers, and component visibility. The examples and capability map below target current source unless they explicitly say “published package.” +> **Release `@theorvane/type-mcp@0.4.0`:** adds MCP SDK v2 protocol serving, modern component metadata and instructions, structured outputs, prompt arguments, resource templates and completion, invocation context, protocol-backed testing, media helpers, and component visibility while retaining the standard, legacy, HTTP, LangChain, and stdio boundaries. > > **Integration boundary:** LangGraph `ToolNode` composition, graph topology, model choice, authorization, state, persistence, and deployment remain consumer responsibilities. @@ -37,7 +35,7 @@ TypeMCP requires **Node.js 20 or later** and TypeScript with standard (Stage 3) npm install @theorvane/type-mcp zod ``` -The install command currently resolves to published `0.3.2`. Modern server/component metadata, initialization instructions, and tool `outputSchema` shown below are implemented on `dev` but are not part of that published version yet. +Version `0.4.0` includes the modern server/component metadata, initialization instructions, tool `outputSchema`, and additional capabilities documented below. The package has ESM and CommonJS runtime and TypeScript declaration conditions for its root, HTTP, LangChain, and legacy entrypoints. The verified decorator modes are standard decorators in an ESM/NodeNext consumer and legacy `experimentalDecorators` in a CommonJS/Node16 consumer. This standard-decorator `tsconfig.json` baseline matches the package contract: @@ -120,11 +118,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 current source, 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.4.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 | Current source | What it does | +| Surface | `@theorvane/type-mcp@0.4.0` | What it does | | --- | --- | --- | | `@McpServer` | Available | Records standard implementation identity and optional client initialization instructions. | | `@McpTool` | Available | Records input/output Zod schemas and metadata; object returns emit text plus structured content. | @@ -147,7 +145,7 @@ The methods above are ordinary application methods. In current source, use `crea - [Getting started](docs/guides/getting-started.md) — install, declare, inspect, and compile a TypeMCP server. - [Choose a runtime boundary](docs/guides/runtime-selection.md) — select the released root, stdio, HTTP, or tools-only LangChain surface. -- [Dynamic prompts and resources](docs/guides/dynamic-declarations.md) — explicit prompt arguments, URI templates, and completion in current source. +- [Dynamic prompts and resources](docs/guides/dynamic-declarations.md) — explicit prompt arguments, URI templates, and completion in 0.4.0. - [Invocation context](docs/guides/invocation-context.md) — request identity, cancellation, progress, and streaming constraints. - [Testing and media helpers](docs/guides/testing-media.md) — in-memory protocol sessions and image/audio byte results. - [Component visibility](docs/guides/component-visibility.md) — static state, runtime filters, allowlists, and security boundaries. diff --git a/docs/README.md b/docs/README.md index 4fae21e..041ee23 100644 --- 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.3.0`](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.4.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 index ac56f8a..2156db9 100644 --- a/docs/api/decorator-api.md +++ b/docs/api/decorator-api.md @@ -1,6 +1,6 @@ # Decorator API contract -**Published baseline:** [`@theorvane/type-mcp@0.3.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. The contract below describes current `dev` source, including SDK v2 serving, server identity/instructions, modern component metadata, tool `outputSchema`, explicit prompt arguments, resource URI templates, completion, and invocation context. LangChain interoperability is isolated at `@theorvane/type-mcp/langchain`. +**Release contract:** [`@theorvane/type-mcp@0.4.0`](https://www.npmjs.com/package/@theorvane/type-mcp) provides SDK v2 serving, modern server/component metadata, structured tool output, prompt arguments, resource templates and completion, invocation context, testing/media helpers, component visibility, stdio, Fetch Streamable HTTP, and tools-only LangChain interoperability. ## Server declaration diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index bdc76c8..93581e6 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,6 +1,6 @@ # Architecture overview -> **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. +> **Public release:** [`@theorvane/type-mcp@0.4.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 index 77369df..3b82dcb 100644 --- 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.3.0` 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.4.0` package. ## Capability contract agents must honor diff --git a/docs/guides/component-visibility.md b/docs/guides/component-visibility.md index 1b7669e..0408158 100644 --- a/docs/guides/component-visibility.md +++ b/docs/guides/component-visibility.md @@ -1,6 +1,6 @@ # Component visibility -**Availability:** current `dev` source; not included in published `0.3.2`. +**Availability:** included in `@theorvane/type-mcp@0.4.0`. Tools, resources/templates, and prompts accept `enabled` and `tags`. Components are enabled by default. diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index f610f53..115a877 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -1,13 +1,13 @@ # Configuration and compatibility -`@theorvane/type-mcp@0.3.2` is the published TypeScript declaration and runtime package, verified against the npm registry after its reviewed `main` promotion. 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.4.0` is the published TypeScript declaration and runtime package, verified against the npm registry after its reviewed `main` promotion. 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.3.0 version` succeeds, install TypeMCP and Zod as application dependencies: +Use Node.js 20 or later. After `npm view @theorvane/type-mcp@0.4.0 version` succeeds, install TypeMCP and Zod as application dependencies: ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.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.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. +The public `@theorvane/type-mcp@0.4.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 @@ -69,10 +69,10 @@ find({ id }: z.infer) { } ``` -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. +A missing component `name` defaults to the method name. `0.4.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.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. +The published `@theorvane/type-mcp@0.4.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 index 43c3c62..79cfa7d 100644 --- 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.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) model before you choose a runtime boundary. +This page explains the published [`@theorvane/type-mcp@0.4.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/dynamic-declarations.md b/docs/guides/dynamic-declarations.md index 1cb5708..ce075e1 100644 --- a/docs/guides/dynamic-declarations.md +++ b/docs/guides/dynamic-declarations.md @@ -1,6 +1,6 @@ # Dynamic prompts and resources -Current `dev` source adds explicit prompt arguments and resource URI templates. These APIs are unreleased until the next reviewed package promotion. +TypeMCP 0.4.0 adds explicit prompt arguments, resource URI templates, and completion. ## Prompt arguments and completion diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 9b5e465..88cd9ab 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -1,13 +1,13 @@ -# Getting started with `@theorvane/type-mcp@0.3.0` +# Getting started with `@theorvane/type-mcp@0.4.0` -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. +This guide creates and inspects an MCP **declaration** using the published `@theorvane/type-mcp@0.4.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.3.0 zod +npm install @theorvane/type-mcp@0.4.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.3.0` 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.4.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.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 published `@theorvane/type-mcp@0.4.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 index cb541e5..138948d 100644 --- 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.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. +The published `@theorvane/type-mcp@0.4.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/invocation-context.md b/docs/guides/invocation-context.md index 5287d35..292b609 100644 --- a/docs/guides/invocation-context.md +++ b/docs/guides/invocation-context.md @@ -1,6 +1,6 @@ # Invocation context, cancellation, and progress -**Availability:** current `dev` source; not included in published `0.3.2`. +**Availability:** included in `@theorvane/type-mcp@0.4.0`. Every decorated tool, resource, and prompt handler may opt into a final `McpInvocationContext` argument. Existing handlers remain valid because JavaScript ignores arguments they do not declare. diff --git a/docs/guides/langchain-langgraph.md b/docs/guides/langchain-langgraph.md index 022fc4d..3fa2d7b 100644 --- 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.3.0` 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.4.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.3.0 @langchain/core zod +npm install @theorvane/type-mcp@0.4.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/mcp-sdk-v2-migration.md b/docs/guides/mcp-sdk-v2-migration.md index b657491..1ae8809 100644 --- a/docs/guides/mcp-sdk-v2-migration.md +++ b/docs/guides/mcp-sdk-v2-migration.md @@ -1,6 +1,6 @@ # MCP TypeScript SDK v2 migration -The current `dev` source uses the split stable MCP TypeScript SDK v2 packages. Runtime code depends on `@modelcontextprotocol/server@2.0.0`; protocol integration tests use `@modelcontextprotocol/client@2.0.0`. The monolithic `@modelcontextprotocol/sdk` v1 package is no longer installed. +TypeMCP 0.4.0 uses the split stable MCP TypeScript SDK v2 packages. Runtime code depends on `@modelcontextprotocol/server@2.0.0`; protocol integration tests use `@modelcontextprotocol/client@2.0.0`. The monolithic `@modelcontextprotocol/sdk` v1 package is no longer installed. ## HTTP applications diff --git a/docs/guides/petstore-project-setup.md b/docs/guides/petstore-project-setup.md index 26c2619..9d79b14 100644 --- 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.3.0`](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.4.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.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod npm install --save-dev typescript tsx @types/node npm pkg set scripts.check="tsc --noEmit" ``` diff --git a/docs/guides/petstore-typemcp-foundation.md b/docs/guides/petstore-typemcp-foundation.md index b86b713..cc12d0f 100644 --- a/docs/guides/petstore-typemcp-foundation.md +++ b/docs/guides/petstore-typemcp-foundation.md @@ -5,7 +5,7 @@ This chapter continues the [Petstore project setup](petstore-project-setup.md). ## Before you start - Complete [Petstore project setup](petstore-project-setup.md), including strict NodeNext TypeScript configuration. -- Node.js 20 or later and the released `@theorvane/type-mcp@0.3.0` and `zod` dependencies. +- Node.js 20 or later and the released `@theorvane/type-mcp@0.4.0` and `zod` dependencies. - An MCP-capable local client only if you plan to connect to the stdio process after verifying the project locally. ## Workspace checkpoint @@ -29,7 +29,7 @@ The local script connects a compiled server to stdio. It does not register the p Confirm the project contains the released package and local commands: ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod npm install --save-dev typescript tsx @types/node npm pkg set scripts.check="tsc --noEmit" npm pkg set scripts.inspect-server="tsx src/inspect-server.ts" @@ -70,7 +70,7 @@ export class PetstoreServer { } ``` -The decorated class deliberately has no constructor parameters because that is the published `@McpServer` decorator contract in `0.3.0`. The explicit resolver returns an application-owned configured instance before compilation; replace `configure()` with your own composition-root wiring while preserving a zero-argument decorated constructor. +The decorated class deliberately has no constructor parameters because that is the published `@McpServer` decorator contract in `0.4.0`. The explicit resolver returns an application-owned configured instance before compilation; replace `configure()` with your own composition-root wiring while preserving a zero-argument decorated constructor. ## Inspect the declaration @@ -175,7 +175,7 @@ The last command intentionally remains running while its stdio transport waits f - **`PetstoreServer is missing @McpServer metadata`:** confirm the class is decorated and imported from the `.js` ESM path in the inspecting file. - **A TypeScript error around decorators:** use the NodeNext/`ESNext.Decorators` configuration from [project setup](petstore-project-setup.md); do not enable `experimentalDecorators`. -- **A TypeScript error says the decorated constructor is incompatible:** keep the `@McpServer` class zero-argument and configure application dependencies in the explicit resolver. The published 0.3.0 decorator contract does not accept a constructor-parameter class. +- **A TypeScript error says the decorated constructor is incompatible:** keep the `@McpServer` class zero-argument and configure application dependencies in the explicit resolver. The published 0.4.0 decorator contract does not accept a constructor-parameter class. - **The process exits immediately:** inspect application startup errors and the real client/dependency configuration. `startStdioServer()` connects an already compiled server; it does not validate your environment or provision a client. - **A local MCP client cannot discover the tool:** verify that the client launches the documented executable from the project directory and that its own process/access policy permits it. TypeMCP does not register desktop client configuration. diff --git a/docs/guides/petstore-walkthrough.md b/docs/guides/petstore-walkthrough.md index 0e60ee8..9d233bf 100644 --- a/docs/guides/petstore-walkthrough.md +++ b/docs/guides/petstore-walkthrough.md @@ -1,6 +1,6 @@ # Petstore walkthrough: from declaration to a selected runtime -This walkthrough uses one read-only Petstore catalog tool to show the published [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) flow: declare a server, inspect or compile it, then select the smallest supported runtime boundary. +This walkthrough uses one read-only Petstore catalog tool to show the published [`@theorvane/type-mcp@0.4.0`](https://www.npmjs.com/package/@theorvane/type-mcp) flow: declare a server, inspect or compile it, then select the smallest supported runtime boundary. > **What this does not do:** TypeMCP does not choose hosting, authorization, persistence, models, LangGraph composition, or deployment. Those decisions remain in the application. @@ -19,7 +19,7 @@ For a project-starting route, complete [Petstore project setup](petstore-project Install the package and Zod: ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod ``` Use a Node-aware TypeScript configuration: @@ -58,7 +58,7 @@ export class PetstoreServer { } ``` -The decorated class must keep a zero-argument constructor under the published `0.3.0` `@McpServer` contract. Configure a real catalog service through the explicit resolver before it creates `PetstoreServer`; TypeMCP does not construct or authorize that dependency for you. +The decorated class must keep a zero-argument constructor under the published `0.4.0` `@McpServer` contract. Configure a real catalog service through the explicit resolver before it creates `PetstoreServer`; TypeMCP does not construct or authorize that dependency for you. ## 2. Inspect, then compile through an explicit resolver @@ -122,7 +122,7 @@ A Fetch host can call `handler(request)`. In a Next.js route, re-export it for ` Install the optional peer only when you select this path: ```bash -npm install @theorvane/type-mcp@0.3.0 @langchain/core zod +npm install @theorvane/type-mcp@0.4.0 @langchain/core zod ``` Create `src/langchain-tools.ts`: diff --git a/docs/guides/runtime-selection.md b/docs/guides/runtime-selection.md index bc0ea6f..a42f27d 100644 --- a/docs/guides/runtime-selection.md +++ b/docs/guides/runtime-selection.md @@ -1,6 +1,6 @@ # Choose a TypeMCP runtime boundary -> **Release status:** This guide documents the published `@theorvane/type-mcp@0.3.0` package. Version `0.3.0` adds the explicit `@theorvane/type-mcp/legacy` compatibility entrypoint for TypeScript `experimentalDecorators` and CommonJS consumers; the standard decorator/runtime boundaries below remain the released `0.3.x` surface. +> **Release status:** This guide documents the published `@theorvane/type-mcp@0.4.0` package. The explicit `@theorvane/type-mcp/legacy` compatibility entrypoint supports TypeScript `experimentalDecorators` and CommonJS consumers; the standard decorator/runtime boundaries below remain available in 0.4.0. A TypeMCP class is a declaration plus ordinary application methods. Choose the package entry point from the way the application needs to expose that declaration, then keep hosting and policy at the application boundary. @@ -9,7 +9,7 @@ A TypeMCP class is a declaration plus ordinary application methods. Choose the p Install the root package and Zod when the application declares MCP tools, resources, or prompts: ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod ``` The root entry point provides decorators, definition inspection, compilation through `createMcpServer()`, an explicit `InstanceResolver`, and `startStdioServer()`. It does not select a web framework, model, authorization scheme, session store, persistence layer, or deployment target. @@ -107,7 +107,7 @@ The adapter preserves stateful Streamable HTTP sessions for 2025 clients and use Install the optional LangChain peer only when importing the tools-only adapter: ```bash -npm install @theorvane/type-mcp@0.3.0 @langchain/core zod +npm install @theorvane/type-mcp@0.4.0 @langchain/core zod ``` ```ts diff --git a/docs/guides/testing-media.md b/docs/guides/testing-media.md index 53c5f35..9c3a21c 100644 --- a/docs/guides/testing-media.md +++ b/docs/guides/testing-media.md @@ -1,6 +1,6 @@ # Testing and media helpers -**Availability:** current `dev` source; not included in published `0.3.2`. +**Availability:** included in `@theorvane/type-mcp@0.4.0`. ## In-memory protocol tests diff --git a/docs/ko/guides/core-concepts.md b/docs/ko/guides/core-concepts.md index f923823..bd27dce 100644 --- a/docs/ko/guides/core-concepts.md +++ b/docs/ko/guides/core-concepts.md @@ -1,6 +1,6 @@ # 핵심 개념 -이 문서는 런타임 경계를 고르기 전에 배포된 [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp) 모델을 설명합니다. +이 문서는 런타임 경계를 고르기 전에 배포된 [`@theorvane/type-mcp@0.4.0`](https://www.npmjs.com/package/@theorvane/type-mcp) 모델을 설명합니다. > **책임 경계:** TypeMCP는 선언 메타데이터, 검증, MCP SDK 컴파일, 그리고 선별된 어댑터를 제공합니다. **호스팅, 인가, 영속화, 모델, LangGraph 구성, 배포**의 소유권은 애플리케이션에 남습니다. diff --git a/docs/ko/guides/getting-started.md b/docs/ko/guides/getting-started.md index 871c01f..39efad0 100644 --- a/docs/ko/guides/getting-started.md +++ b/docs/ko/guides/getting-started.md @@ -1,13 +1,13 @@ -# `@theorvane/type-mcp@0.3.0` 시작하기 +# `@theorvane/type-mcp@0.4.0` 시작하기 -이 가이드는 배포된 `@theorvane/type-mcp@0.3.0` 패키지로 MCP **선언(declaration)** 을 만들고 확인합니다. 또한 `createMcpServer()`를 통해 데코레이터로 선언된 정의를 검증하고 컴파일합니다. 각 어댑터 경계는 [HTTP 가이드](../../guides/http-and-nextjs.md)와 [LangChain 가이드](../../guides/langchain-langgraph.md)에서 따로 다룹니다. +이 가이드는 배포된 `@theorvane/type-mcp@0.4.0` 패키지로 MCP **선언(declaration)** 을 만들고 확인합니다. 또한 `createMcpServer()`를 통해 데코레이터로 선언된 정의를 검증하고 컴파일합니다. 각 어댑터 경계는 [HTTP 가이드](../../guides/http-and-nextjs.md)와 [LangChain 가이드](../../guides/langchain-langgraph.md)에서 따로 다룹니다. ## 패키지 설치와 TypeScript 설정 패키지를 설치하고, 스키마를 소유하는 애플리케이션에서 Zod를 직접 임포트합니다. ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod ``` Node.js 20 이상에서 실행합니다. 표준 TypeScript 데코레이터와 Node를 인식하는 ESM 설정을 사용하세요. 최소 `tsconfig.json`은 다음과 같습니다. @@ -71,7 +71,7 @@ export class NotesServer { } ``` -`name`을 생략하면 공개 컴포넌트 이름은 메서드 이름을 기본값으로 씁니다. TypeMCP는 이 옵션들을 메타데이터로 기록하고, `0.3.0`는 컴파일 전에 선언된 정의를 검증합니다. 도메인에 특화된 이름 규칙은 애플리케이션 테스트로 확인하세요. +`name`을 생략하면 공개 컴포넌트 이름은 메서드 이름을 기본값으로 씁니다. TypeMCP는 이 옵션들을 메타데이터로 기록하고, `0.4.0`는 컴파일 전에 선언된 정의를 검증합니다. 도메인에 특화된 이름 규칙은 애플리케이션 테스트로 확인하세요. ## 애플리케이션 경계에서 메타데이터 확인하기 @@ -100,6 +100,6 @@ console.log({ ## 런타임 경계로 이어가기 -배포된 `@theorvane/type-mcp@0.3.0` 패키지에는 `createMcpServer()`, `startStdioServer()`, `@theorvane/type-mcp/http`, `@theorvane/type-mcp/langchain`이 들어 있습니다. TypeMCP는 명시적인 `InstanceResolver`를 통해 선언된 정의를 검증하고 컴파일합니다. 웹 호스트, 인가 모델, 세션 저장소, LangGraph 토폴로지, 모델, 영속화 정책을 애플리케이션 대신 고르지는 않습니다. +배포된 `@theorvane/type-mcp@0.4.0` 패키지에는 `createMcpServer()`, `startStdioServer()`, `@theorvane/type-mcp/http`, `@theorvane/type-mcp/langchain`이 들어 있습니다. TypeMCP는 명시적인 `InstanceResolver`를 통해 선언된 정의를 검증하고 컴파일합니다. 웹 호스트, 인가 모델, 세션 저장소, LangGraph 토폴로지, 모델, 영속화 정책을 애플리케이션 대신 고르지는 않습니다. 위에서 만든 선언은 애플리케이션이 소유하는 확인 작업에 계속 유용합니다. 정의/컴파일러 모델은 [핵심 개념](core-concepts.md)에서 읽고, 그다음 [Petstore 워크스루](petstore-walkthrough.md)를 따라 stdio·HTTP·LangChain 중 무엇을 재사용할지 고르세요. 변경을 자동화하기 전에 [설정 가이드](../../guides/configuration.md), [HTTP 가이드](../../guides/http-and-nextjs.md), [LangChain 가이드](../../guides/langchain-langgraph.md), [에이전트 가이드](../../guides/agent-integration.md)를 확인하세요. diff --git a/docs/ko/guides/petstore-project-setup.md b/docs/ko/guides/petstore-project-setup.md index ac65859..4fc4358 100644 --- a/docs/ko/guides/petstore-project-setup.md +++ b/docs/ko/guides/petstore-project-setup.md @@ -2,7 +2,7 @@ TypeMCP Petstore 커리큘럼의 첫 장입니다. 애플리케이션이 런타임 경계를 고르기 전에, 데코레이터가 적용된 서버를 컴파일할 수 있는 작은 로컬 프로젝트를 만듭니다. -> **배포 버전:** 예제는 [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp)를 대상으로 합니다. 레거시 `experimentalDecorators`가 아니라 표준 TypeScript 데코레이터를 사용합니다. +> **배포 버전:** 예제는 [`@theorvane/type-mcp@0.4.0`](https://www.npmjs.com/package/@theorvane/type-mcp)를 대상으로 합니다. 레거시 `experimentalDecorators`가 아니라 표준 TypeScript 데코레이터를 사용합니다. ## 시작하기 전에 @@ -33,7 +33,7 @@ mkdir petstore-workspace cd petstore-workspace npm init -y npm pkg set type=module -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod npm install --save-dev typescript tsx @types/node npm pkg set scripts.check="tsc --noEmit" ``` diff --git a/docs/ko/guides/petstore-typemcp-foundation.md b/docs/ko/guides/petstore-typemcp-foundation.md index 95aad74..0702713 100644 --- a/docs/ko/guides/petstore-typemcp-foundation.md +++ b/docs/ko/guides/petstore-typemcp-foundation.md @@ -5,7 +5,7 @@ ## 시작하기 전에 - 엄격한 NodeNext TypeScript 설정을 포함해 [Petstore 프로젝트 설정](petstore-project-setup.md)을 마치세요. -- Node.js 20 이상, 그리고 릴리스된 `@theorvane/type-mcp@0.3.0`와 `zod` 의존성. +- Node.js 20 이상, 그리고 릴리스된 `@theorvane/type-mcp@0.4.0`와 `zod` 의존성. - 프로젝트를 로컬에서 확인한 뒤 stdio 프로세스에 연결할 계획이라면, 그때만 MCP를 지원하는 로컬 클라이언트가 필요합니다. ## 워크스페이스 체크포인트 @@ -29,7 +29,7 @@ petstore-workspace/ 프로젝트에 릴리스된 패키지와 로컬 명령이 있는지 확인합니다. ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod npm install --save-dev typescript tsx @types/node npm pkg set scripts.check="tsc --noEmit" npm pkg set scripts.inspect-server="tsx src/inspect-server.ts" @@ -70,7 +70,7 @@ export class PetstoreServer { } ``` -데코레이터가 적용된 클래스에 생성자 매개변수가 없는 것은 의도된 것입니다. `0.3.0`에 배포된 `@McpServer` 데코레이터 계약이 그렇게 정의되어 있습니다. 명시적 리졸버가 컴파일 전에 애플리케이션이 소유한, 구성이 끝난 인스턴스를 반환합니다. `configure()`는 여러분의 컴포지션 루트 배선으로 바꾸되, 데코레이터가 적용된 생성자는 인자 없는 형태로 유지하세요. +데코레이터가 적용된 클래스에 생성자 매개변수가 없는 것은 의도된 것입니다. `0.4.0`에 배포된 `@McpServer` 데코레이터 계약이 그렇게 정의되어 있습니다. 명시적 리졸버가 컴파일 전에 애플리케이션이 소유한, 구성이 끝난 인스턴스를 반환합니다. `configure()`는 여러분의 컴포지션 루트 배선으로 바꾸되, 데코레이터가 적용된 생성자는 인자 없는 형태로 유지하세요. ## 선언 확인 @@ -175,7 +175,7 @@ npm run stdio - **`PetstoreServer is missing @McpServer metadata`:** 클래스에 데코레이터가 적용되어 있는지, 확인 파일에서 `.js` ESM 경로로 임포트했는지 확인하세요. - **데코레이터 관련 TypeScript 오류:** [프로젝트 설정](petstore-project-setup.md)의 NodeNext/`ESNext.Decorators` 설정을 사용하고, `experimentalDecorators`는 켜지 마세요. -- **데코레이터가 적용된 생성자가 호환되지 않는다는 TypeScript 오류:** `@McpServer` 클래스를 인자 없는 형태로 유지하고, 애플리케이션 의존성은 명시적 리졸버에서 구성하세요. 배포된 0.3.0 데코레이터 계약은 생성자 매개변수를 받는 클래스를 허용하지 않습니다. +- **데코레이터가 적용된 생성자가 호환되지 않는다는 TypeScript 오류:** `@McpServer` 클래스를 인자 없는 형태로 유지하고, 애플리케이션 의존성은 명시적 리졸버에서 구성하세요. 배포된 0.4.0 데코레이터 계약은 생성자 매개변수를 받는 클래스를 허용하지 않습니다. - **프로세스가 즉시 종료됨:** 애플리케이션 시작 오류와 실제 클라이언트/의존성 설정을 확인하세요. `startStdioServer()`는 이미 컴파일된 서버를 연결할 뿐, 환경을 검증하거나 클라이언트를 준비해 주지는 않습니다. - **로컬 MCP 클라이언트가 도구를 발견하지 못함:** 클라이언트가 프로젝트 디렉터리에서 문서화된 실행 파일을 실행하는지, 그리고 클라이언트 자신의 프로세스/접근 정책이 이를 허용하는지 확인하세요. TypeMCP는 데스크톱 클라이언트 설정을 등록하지 않습니다. diff --git a/docs/ko/guides/petstore-walkthrough.md b/docs/ko/guides/petstore-walkthrough.md index 2e1d727..4d1d7a2 100644 --- a/docs/ko/guides/petstore-walkthrough.md +++ b/docs/ko/guides/petstore-walkthrough.md @@ -1,6 +1,6 @@ # Petstore 워크스루: 선언에서 선택된 런타임까지 -이 워크스루는 읽기 전용 Petstore 카탈로그 도구 하나로 배포된 [`@theorvane/type-mcp@0.3.0`](https://www.npmjs.com/package/@theorvane/type-mcp)의 흐름을 보여 줍니다. 서버를 선언하고, 확인하거나 컴파일한 뒤, 지원되는 가장 작은 런타임 경계를 고릅니다. +이 워크스루는 읽기 전용 Petstore 카탈로그 도구 하나로 배포된 [`@theorvane/type-mcp@0.4.0`](https://www.npmjs.com/package/@theorvane/type-mcp)의 흐름을 보여 줍니다. 서버를 선언하고, 확인하거나 컴파일한 뒤, 지원되는 가장 작은 런타임 경계를 고릅니다. > **이것이 하지 않는 일:** TypeMCP는 호스팅, 인가, 영속화, 모델, LangGraph 구성, 배포를 고르지 않습니다. 그 결정은 애플리케이션에 남습니다. @@ -19,7 +19,7 @@ 패키지와 Zod를 설치합니다. ```bash -npm install @theorvane/type-mcp@0.3.0 zod +npm install @theorvane/type-mcp@0.4.0 zod ``` Node를 인식하는 TypeScript 설정을 사용합니다. @@ -58,7 +58,7 @@ export class PetstoreServer { } ``` -배포된 `0.3.0`의 `@McpServer` 계약에서는 데코레이터가 적용된 클래스가 인자 없는 생성자를 유지해야 합니다. 실제 카탈로그 서비스는 리졸버가 `PetstoreServer`를 생성하기 전에 명시적 리졸버를 통해 구성하세요. TypeMCP는 그 의존성을 대신 생성하거나 인가하지 않습니다. +배포된 `0.4.0`의 `@McpServer` 계약에서는 데코레이터가 적용된 클래스가 인자 없는 생성자를 유지해야 합니다. 실제 카탈로그 서비스는 리졸버가 `PetstoreServer`를 생성하기 전에 명시적 리졸버를 통해 구성하세요. TypeMCP는 그 의존성을 대신 생성하거나 인가하지 않습니다. ## 2. 확인한 뒤 명시적 리졸버로 컴파일 @@ -122,7 +122,7 @@ Fetch 호스트는 `handler(request)`를 호출할 수 있습니다. Next.js 라 이 경로를 고를 때에만 선택적 피어 의존성을 설치합니다. ```bash -npm install @theorvane/type-mcp@0.3.0 @langchain/core zod +npm install @theorvane/type-mcp@0.4.0 @langchain/core zod ``` `src/langchain-tools.ts`를 만듭니다. diff --git a/docs/product/mvp-scope.md b/docs/product/mvp-scope.md index e692934..0b9b3ca 100644 --- a/docs/product/mvp-scope.md +++ b/docs/product/mvp-scope.md @@ -1,22 +1,22 @@ # MVP scope -> **Published package:** `@theorvane/type-mcp@0.3.2` includes the MVP baseline. Current `dev` additionally carries SDK v2 serving, modern server/component metadata, initialization instructions, tool structured output, dynamic prompts/resources, invocation context, testing/media helpers, and component visibility. Start with the [README](../../README.md) and [getting-started guide](../guides/getting-started.md) for exact exports and boundaries. +> **Release package:** `@theorvane/type-mcp@0.4.0` includes the MVP baseline plus SDK v2 serving, modern metadata, instructions, structured output, dynamic prompts/resources, invocation context, testing/media helpers, and component visibility. -**Status:** The baseline is published in `@theorvane/type-mcp@0.3.2`; rows explicitly marked current `dev` are implemented but unreleased. +**Status:** Included capabilities below are part of the `@theorvane/type-mcp@0.4.0` release contract. ## Included | Capability | MVP boundary | | --- | --- | -| Server declaration | Published baseline: `name` and `version`; current `dev`: optional standard implementation identity and client instructions | +| Server declaration | `name`, `version`, optional standard implementation identity, and client instructions | | Tools | `@McpTool()` with name/description and Zod object input schema | -| Resources | Published baseline: explicit static URIs; current `dev`: validated URI templates and variable completion | -| Prompts | Published baseline: named zero-argument handlers; current `dev`: explicit validated arguments and completion | +| Resources | explicit static URIs, validated URI templates, and variable completion | +| Prompts | named zero-argument handlers, explicit validated arguments, and completion | | Compilation | Decorator metadata compiled to the stable split `@modelcontextprotocol/server` v2 `McpServer` | -| Invocation context | Current `dev`: request/session identity, SDK cancellation signal, and progress reporting | -| Testing | Current `dev`: official SDK v2 in-memory client/server session with explicit cleanup | -| Media | Current `dev`: byte-only image/audio helpers with explicit MIME validation | -| Component visibility | Current `dev`: static enabled state and server-level key/name/tag/kind filtering | +| Invocation context | request/session identity, SDK cancellation signal, and progress reporting | +| Testing | official SDK v2 in-memory client/server session with explicit cleanup | +| Media | byte-only image/audio helpers with explicit MIME validation | +| Component visibility | static enabled state and server-level key/name/tag/kind filtering | | Instance construction | Direct constructor default plus async-capable `InstanceResolver` interface | | Local transport | stdio helper | | Web transport | Fetch-standard Streamable HTTP handler | @@ -35,7 +35,7 @@ ## Constraints -- Public distribution: `@theorvane/type-mcp@0.3.2` on npm; the repository is `Theorvane/type-mcp`. +- Public distribution: `@theorvane/type-mcp@0.4.0` on npm; the repository is `Theorvane/type-mcp`. - Runtime protocol behavior comes from the official MCP SDK. - Core and HTTP have no agent-framework runtime or peer dependency; `@theorvane/type-mcp/langchain` has an isolated optional LangChain peer. - Public types are strict and runtime input is validated before handler invocation. diff --git a/package-lock.json b/package-lock.json index 7442f21..d41a7b4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@theorvane/type-mcp", - "version": "0.3.2", + "version": "0.4.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@theorvane/type-mcp", - "version": "0.3.2", + "version": "0.4.0", "license": "MIT", "dependencies": { "@hono/node-server": "2.1.1", diff --git a/package.json b/package.json index a128f17..ecc5e3e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@theorvane/type-mcp", - "version": "0.3.2", + "version": "0.4.0", "description": "Decorator-first TypeScript framework for Model Context Protocol servers", "repository": { "type": "git", diff --git a/test/compatibility-consumer-contract.test.ts b/test/compatibility-consumer-contract.test.ts index 2559fa4..2fbfd20 100644 --- a/test/compatibility-consumer-contract.test.ts +++ b/test/compatibility-consumer-contract.test.ts @@ -9,17 +9,17 @@ interface PackageManifest { } describe("packed consumer compatibility contract", () => { - it("declares the 0.3.2 compatibility release version", async () => { + it("declares the 0.4.0 compatibility release version", async () => { const manifest = JSON.parse( await readFile(new URL("../package.json", import.meta.url), "utf8"), ) as PackageManifest; - expect(manifest.version).toBe("0.3.2"); + expect(manifest.version).toBe("0.4.0"); }); it("accepts npm 11 array and npm 12 package-keyed pack JSON", () => { const tarball = { - filename: "theorvane-type-mcp-0.3.2.tgz", + filename: "theorvane-type-mcp-0.4.0.tgz", name: "@theorvane/type-mcp", }; diff --git a/test/langchain-documentation-contract.test.ts b/test/langchain-documentation-contract.test.ts index 6f8e5c9..76bd2c0 100644 --- a/test/langchain-documentation-contract.test.ts +++ b/test/langchain-documentation-contract.test.ts @@ -76,7 +76,7 @@ describe("LangChain current-facing documentation contract", () => { .flat() .join("\n"); - expect(combined).toContain("@theorvane/type-mcp@0.3.0"); + expect(combined).toContain("@theorvane/type-mcp@0.4.0"); expect(combined).toContain( "strict declarations, validation, MCP SDK compilation, stdio, or Streamable HTTP", ); diff --git a/test/reference-documentation-contract.test.ts b/test/reference-documentation-contract.test.ts index 51a854d..f6010b0 100644 --- a/test/reference-documentation-contract.test.ts +++ b/test/reference-documentation-contract.test.ts @@ -14,7 +14,7 @@ describe("reference-first TypeMCP documentation", () => { await Promise.all(documents.map((path) => readFile(path, "utf8"))) ).join("\n"); - expect(content).toContain("@theorvane/type-mcp@0.3.0"); + expect(content).toContain("@theorvane/type-mcp@0.4.0"); expect(content).toContain("Inspect a declaration"); expect(content).toContain("Run over stdio"); expect(content).toContain("Serve Streamable HTTP"); @@ -59,7 +59,7 @@ describe("reference-first TypeMCP documentation", () => { expect(content, path).toMatch(/## Next steps/); } - expect(allContent).toContain("@theorvane/type-mcp@0.3.0"); + expect(allContent).toContain("@theorvane/type-mcp@0.4.0"); expect(allContent).not.toMatch(/npm install @theorvane\/type-mcp(?:\s|$)/); expect(allContent).toContain("npm run stdio"); expect(consumerScript).toContain(