@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/packages/platform-mcp/api/Interface.IMcpToolMetadata.md

@@ -0,0 +1,94 @@
+---
+title: 'Interface: IMcpToolMetadata'
+generated: true
+editUrl: false
+---
+# Interface: IMcpToolMetadata
+
+Defined in: [interfaces/IMcpToolMetadata.ts:6](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L6)
+
+Metadata describing an MCP tool registration.
+
+## Properties
+
+### annotations?
+
+```ts
+readonly optional annotations?: Record<string, unknown>;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:23](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L23)
+
+Annotations for the tool (e.g. readOnlyHint, destructiveHint).
+
+***
+
+### description?
+
+```ts
+readonly optional description?: string;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L14)
+
+Description of what the tool does.
+
+***
+
+### inputSchema?
+
+```ts
+readonly optional inputSchema?: Record<string, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L17)
+
+Zod schema defining the tool's input parameters.
+
+***
+
+### name
+
+```ts
+readonly name: string;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:8](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L8)
+
+Unique name of the tool.
+
+***
+
+### outputSchema?
+
+```ts
+readonly optional outputSchema?: Record<string, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L20)
+
+Zod schema defining the tool's structured output.
+
+***
+
+### requiredScopes?
+
+```ts
+readonly optional requiredScopes?: readonly string[];
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L26)
+
+Required scopes for tool execution. If set, the caller must provide matching scopes via `extra.scopes`.
+
+***
+
+### title?
+
+```ts
+readonly optional title?: string;
+```
+
+Defined in: [interfaces/IMcpToolMetadata.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/interfaces/IMcpToolMetadata.ts#L11)
+
+Human-readable title of the tool.

package/data/packages/platform-mcp/api/Interface.IRegisteredPrompt.md

@@ -0,0 +1,40 @@
+---
+title: 'Interface: IRegisteredPrompt'
+generated: true
+editUrl: false
+---
+# Interface: IRegisteredPrompt
+
+Defined in: [services/McpRegistryService.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L25)
+
+Entry for a registered prompt handler.
+
+## Properties
+
+### handler
+
+```ts
+readonly handler: (...args) => unknown;
+```
+
+Defined in: [services/McpRegistryService.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L27)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`args` | `unknown`[] |
+
+#### Returns
+
+`unknown`
+
+***
+
+### metadata
+
+```ts
+readonly metadata: IMcpPromptMetadata;
+```
+
+Defined in: [services/McpRegistryService.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L26)

package/data/packages/platform-mcp/api/Interface.IRegisteredResource.md

@@ -0,0 +1,40 @@
+---
+title: 'Interface: IRegisteredResource'
+generated: true
+editUrl: false
+---
+# Interface: IRegisteredResource
+
+Defined in: [services/McpRegistryService.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L17)
+
+Entry for a registered resource handler.
+
+## Properties
+
+### handler
+
+```ts
+readonly handler: (...args) => unknown;
+```
+
+Defined in: [services/McpRegistryService.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L19)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`args` | `unknown`[] |
+
+#### Returns
+
+`unknown`
+
+***
+
+### metadata
+
+```ts
+readonly metadata: IMcpResourceMetadata;
+```
+
+Defined in: [services/McpRegistryService.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L18)

package/data/packages/platform-mcp/api/Interface.IRegisteredTool.md

@@ -0,0 +1,40 @@
+---
+title: 'Interface: IRegisteredTool'
+generated: true
+editUrl: false
+---
+# Interface: IRegisteredTool
+
+Defined in: [services/McpRegistryService.ts:9](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L9)
+
+Entry for a registered tool handler.
+
+## Properties
+
+### handler
+
+```ts
+readonly handler: (...args) => unknown;
+```
+
+Defined in: [services/McpRegistryService.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L11)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`args` | `unknown`[] |
+
+#### Returns
+
+`unknown`
+
+***
+
+### metadata
+
+```ts
+readonly metadata: IMcpToolMetadata;
+```
+
+Defined in: [services/McpRegistryService.ts:10](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpRegistryService.ts#L10)

package/data/packages/platform-mcp/api/Interface.ISseTransportOptions.md

@@ -0,0 +1,22 @@
+---
+title: 'Interface: ISseTransportOptions'
+generated: true
+editUrl: false
+---
+# Interface: ISseTransportOptions
+
+Defined in: [services/McpServerService.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpServerService.ts#L28)
+
+Options for creating an SSE transport.
+
+## Properties
+
+### endpoint
+
+```ts
+readonly endpoint: string;
+```
+
+Defined in: [services/McpServerService.ts:30](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpServerService.ts#L30)
+
+The URL path where the SSE endpoint is served.

package/data/packages/platform-mcp/api/Interface.IStreamableHttpTransportOptions.md

@@ -0,0 +1,38 @@
+---
+title: 'Interface: IStreamableHttpTransportOptions'
+generated: true
+editUrl: false
+---
+# Interface: IStreamableHttpTransportOptions
+
+Defined in: [services/McpServerService.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpServerService.ts#L17)
+
+Options for creating a Streamable HTTP transport.
+
+## Properties
+
+### enableJsonResponse?
+
+```ts
+readonly optional enableJsonResponse?: boolean;
+```
+
+Defined in: [services/McpServerService.ts:22](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpServerService.ts#L22)
+
+Whether to enable JSON-only response mode (no SSE).
+
+***
+
+### sessionIdGenerator?
+
+```ts
+readonly optional sessionIdGenerator?: () => string;
+```
+
+Defined in: [services/McpServerService.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/services/McpServerService.ts#L19)
+
+Function to generate session IDs. Defaults to crypto.randomUUID.
+
+#### Returns
+
+`string`

package/data/packages/platform-mcp/api/Variable.MCP_MODULE_OPTIONS.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: MCP\_MODULE\_OPTIONS'
+generated: true
+editUrl: false
+---
+# Variable: MCP\_MODULE\_OPTIONS
+
+```ts
+const MCP_MODULE_OPTIONS: typeof MCP_MODULE_OPTIONS;
+```
+
+Defined in: [constants/McpTokens.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/constants/McpTokens.ts#L4)
+
+Injection tokens used by the MCP module.

package/data/packages/platform-mcp/api/index.md

@@ -0,0 +1,46 @@
+---
+title: '@breadstone/archipel-platform-mcp'
+generated: true
+editUrl: false
+---
+# @breadstone/archipel-platform-mcp
+
+## Classes
+
+| Class | Description |
+| ------ | ------ |
+| [McpDiscoveryService](Class.McpDiscoveryService) | Discovers all NestJS providers that have methods decorated with `@McpTool`, `@McpResource`, or `@McpPrompt` and registers them in the [McpRegistryService](Class.McpRegistryService). |
+| [McpModule](Class.McpModule) | NestJS dynamic module that bootstraps an MCP server. |
+| [McpRegistryService](Class.McpRegistryService) | Central registry that stores all MCP tool, resource, and prompt handlers discovered from NestJS providers. |
+| [McpServerService](Class.McpServerService) | Manages the MCP server lifecycle. Creates the `McpServer` instance, registers all discovered handlers from the registry, and provides methods to connect various transports. |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [IMcpHandlerMetadata](Interface.IMcpHandlerMetadata) | Internal metadata stored for each decorated handler method. |
+| [IMcpModuleAsyncOptions](Interface.IMcpModuleAsyncOptions) | Async options for configuring the MCP module via a factory. |
+| [IMcpModuleOptions](Interface.IMcpModuleOptions) | Options for configuring the MCP module. |
+| [IMcpModuleOptionsFactory](Interface.IMcpModuleOptionsFactory) | Factory interface for creating MCP module options. |
+| [IMcpPromptMetadata](Interface.IMcpPromptMetadata) | Metadata describing an MCP prompt registration. |
+| [IMcpResourceMetadata](Interface.IMcpResourceMetadata) | Metadata describing an MCP resource registration. |
+| [IMcpToolMetadata](Interface.IMcpToolMetadata) | Metadata describing an MCP tool registration. |
+| [IRegisteredPrompt](Interface.IRegisteredPrompt) | Entry for a registered prompt handler. |
+| [IRegisteredResource](Interface.IRegisteredResource) | Entry for a registered resource handler. |
+| [IRegisteredTool](Interface.IRegisteredTool) | Entry for a registered tool handler. |
+| [ISseTransportOptions](Interface.ISseTransportOptions) | Options for creating an SSE transport. |
+| [IStreamableHttpTransportOptions](Interface.IStreamableHttpTransportOptions) | Options for creating a Streamable HTTP transport. |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [MCP\_MODULE\_OPTIONS](Variable.MCP_MODULE_OPTIONS) | Injection tokens used by the MCP module. |
+
+## Functions
+
+| Function | Description |
+| ------ | ------ |
+| [McpPrompt](Function.McpPrompt) | Marks a method as an MCP prompt handler. |
+| [McpResource](Function.McpResource) | Marks a method as an MCP resource handler. |
+| [McpTool](Function.McpTool) | Marks a method as an MCP tool handler. |

package/data/packages/platform-mcp/index.md

@@ -0,0 +1,299 @@
+---
+title: platform-mcp
+description: Reusable NestJS module for building Model Context Protocol (MCP) servers with decorator-driven handler registration and multi-transport support.
+order: 13
+tags: [mcp, model-context-protocol, tools, resources, prompts, transports]
+package: '@breadstone/archipel-platform-mcp'
+---
+
+# platform-mcp
+
+A reusable NestJS module for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers. Provides decorators, automatic handler discovery, and transport management — all wired through NestJS dependency injection.
+
+**Package:** `@breadstone/archipel-platform-mcp`
+
+## Installation
+
+```typescript
+import {
+  McpModule,
+  McpTool,
+  McpResource,
+  McpPrompt,
+  McpServerService,
+  McpRegistryService,
+} from '@breadstone/archipel-platform-mcp';
+```
+
+### Peer Dependencies
+
+The host application must provide `@nestjs/common`, `@nestjs/core`, `@modelcontextprotocol/sdk`, `zod`, `reflect-metadata`, and `rxjs`.
+
+---
+
+## Features
+
+| Feature            | Description                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| Decorator-driven   | Annotate methods with `@McpTool`, `@McpResource`, or `@McpPrompt` to register MCP handlers. |
+| Auto-discovery     | Handlers are discovered at module init via NestJS `DiscoveryService`.                       |
+| Dynamic Module     | Configure via `McpModule.register()` (sync) or `McpModule.registerAsync()` (factory/class). |
+| Transport-agnostic | Built-in Stdio, Streamable HTTP, and SSE transports. Plug in any custom `Transport`.        |
+| Zod schemas        | Define input/output schemas for tools and argument schemas for prompts using Zod.           |
+| NPM-publishable    | Standalone library for reuse across multiple NestJS projects.                               |
+
+---
+
+## Module Configuration
+
+### Synchronous
+
+```typescript
+import { Module } from '@nestjs/common';
+import { McpModule } from '@breadstone/archipel-platform-mcp';
+
+@Module({
+  imports: [
+    McpModule.register({
+      name: 'my-mcp-server',
+      version: '1.0.0',
+      capabilities: {
+        tools: { listChanged: true },
+        resources: { subscribe: false, listChanged: true },
+        prompts: { listChanged: true },
+      },
+      instructions: 'Optional instructions for MCP clients.',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Asynchronous (factory)
+
+```typescript
+McpModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    name: config.get('MCP_SERVER_NAME'),
+    version: config.get('MCP_SERVER_VERSION'),
+  }),
+});
+```
+
+### Asynchronous (class / existing)
+
+```typescript
+// useExisting — reuse an already-registered provider
+McpModule.registerAsync({ useExisting: McpConfigService });
+
+// useClass — instantiate a new provider
+McpModule.registerAsync({ useClass: McpConfigService });
+```
+
+The provider must implement `IMcpModuleOptionsFactory`.
+
+---
+
+## Decorators
+
+All decorators are placed on **methods** of NestJS `@Injectable()` providers.
+
+### @McpTool
+
+```typescript
+import { McpTool } from '@breadstone/archipel-platform-mcp';
+import { z } from 'zod';
+
+@Injectable()
+class CalculatorTools {
+  @McpTool({
+    name: 'add',
+    description: 'Adds two numbers',
+    inputSchema: { a: z.number(), b: z.number() },
+    annotations: { readOnlyHint: true },
+  })
+  public add(input: { a: number; b: number }) {
+    return {
+      content: [{ type: 'text' as const, text: String(input.a + input.b) }],
+    };
+  }
+}
+```
+
+| Option         | Type                      | Required | Description                           |
+| -------------- | ------------------------- | -------- | ------------------------------------- |
+| `name`         | `string`                  | Yes      | Unique tool name                      |
+| `title`        | `string`                  | No       | Human-readable title                  |
+| `description`  | `string`                  | No       | What the tool does                    |
+| `inputSchema`  | `ZodRawShape`             | No       | Zod schema for input parameters       |
+| `outputSchema` | `ZodRawShape`             | No       | Zod schema for structured output      |
+| `annotations`  | `Record<string, unknown>` | No       | Hints (readOnlyHint, destructiveHint) |
+
+### @McpResource
+
+Supports both static URIs and URI templates (containing `{…}` placeholders).
+
+```typescript
+@Injectable()
+class ConfigResources {
+  @McpResource({
+    name: 'app-config',
+    uri: 'config://application',
+    mimeType: 'application/json',
+  })
+  public getAppConfig() {
+    return {
+      contents: [{ uri: 'config://application', text: '{"debug": false}' }],
+    };
+  }
+
+  @McpResource({
+    name: 'user-profile',
+    uri: 'users://{userId}/profile',
+    mimeType: 'application/json',
+  })
+  public getUserProfile(uri: URL, params: { userId: string }) {
+    return {
+      contents: [{ uri: uri.href, text: JSON.stringify({ userId: params.userId }) }],
+    };
+  }
+}
+```
+
+| Option        | Type     | Required | Description              |
+| ------------- | -------- | -------- | ------------------------ |
+| `name`        | `string` | Yes      | Unique resource name     |
+| `uri`         | `string` | Yes      | Static URI or template   |
+| `title`       | `string` | No       | Human-readable title     |
+| `description` | `string` | No       | Resource description     |
+| `mimeType`    | `string` | No       | MIME type of the content |
+
+### @McpPrompt
+
+```typescript
+@Injectable()
+class PromptProviders {
+  @McpPrompt({
+    name: 'code-review',
+    description: 'Generates a code review prompt.',
+    argsSchema: { code: z.string(), language: z.string().optional() },
+  })
+  public codeReview(args: { code: string; language?: string }) {
+    return {
+      messages: [
+        {
+          role: 'user' as const,
+          content: { type: 'text' as const, text: `Review:\n${args.code}` },
+        },
+      ],
+    };
+  }
+}
+```
+
+| Option        | Type          | Required | Description                |
+| ------------- | ------------- | -------- | -------------------------- |
+| `name`        | `string`      | Yes      | Unique prompt name         |
+| `title`       | `string`      | No       | Human-readable title       |
+| `description` | `string`      | No       | Prompt description         |
+| `argsSchema`  | `ZodRawShape` | No       | Zod schema for prompt args |
+
+---
+
+## Transports
+
+### Stdio
+
+Best for CLI tools and process-spawned integrations.
+
+```typescript
+const app = await NestFactory.createApplicationContext(AppModule);
+const mcpServer = app.get(McpServerService);
+await mcpServer.connectStdio();
+```
+
+### Streamable HTTP
+
+Recommended for HTTP-based deployments.
+
+```typescript
+const transport = await mcpServer.createStreamableHttpTransport({
+  sessionIdGenerator: () => crypto.randomUUID(),
+});
+
+const httpApp = express();
+httpApp.post('/mcp', (req, res) => transport.handleRequest(req, res));
+httpApp.get('/mcp', (req, res) => transport.handleRequest(req, res));
+httpApp.delete('/mcp', (req, res) => transport.handleRequest(req, res));
+httpApp.listen(3000);
+```
+
+### Server-Sent Events (SSE)
+
+Legacy transport for older clients.
+
+```typescript
+httpApp.get('/sse', async (req, res) => {
+  await mcpServer.createSseTransport({ endpoint: '/messages' }, res);
+});
+```
+
+### Custom Transport
+
+```typescript
+await mcpServer.connectTransport(myCustomTransport);
+```
+
+---
+
+## Services
+
+### McpServerService
+
+Main entry point for controlling the MCP server at runtime.
+
+| Method                                    | Description                                    |
+| ----------------------------------------- | ---------------------------------------------- |
+| `server: McpServer`                       | The underlying `McpServer` instance (readonly) |
+| `connectStdio()`                          | Connects a stdio transport                     |
+| `createStreamableHttpTransport(options?)` | Creates Streamable HTTP transport              |
+| `createSseTransport(options, response)`   | Creates SSE transport                          |
+| `connectTransport(transport)`             | Connects any custom `Transport`                |
+
+### McpRegistryService
+
+Central registry for all discovered handlers. Also supports manual registration.
+
+| Property / Method                 | Description                  |
+| --------------------------------- | ---------------------------- |
+| `tools: Map<string, …>`           | All registered tools         |
+| `resources: Map<string, …>`       | All registered resources     |
+| `prompts: Map<string, …>`         | All registered prompts       |
+| `registerTool(metadata, handler)` | Manually register a tool     |
+| `registerResource(…)`             | Manually register a resource |
+| `registerPrompt(…)`               | Manually register a prompt   |
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    Module["McpModule.register(options)"]
+    Registry["McpRegistryService<br/><i>Stores handlers (tools / resources / prompts)</i>"]
+    Discovery["McpDiscoveryService<br/><i>Scans providers for @McpTool / @McpResource / @McpPrompt</i>"]
+    Server["McpServerService<br/><i>Creates McpServer, registers handlers, manages transports</i>"]
+
+    Module --> Registry
+    Module --> Discovery
+    Module --> Server
+    Discovery -->|populates| Registry
+    Server -->|reads from| Registry
+```
+
+1. **McpModule** bootstraps the module with sync or async configuration.
+2. **McpDiscoveryService** runs `onModuleInit`, iterates all providers, reads decorator metadata, and populates the registry.
+3. **McpServerService** runs `onModuleInit`, creates the `McpServer` instance, and registers all handlers from the registry.
+4. The application connects a transport (stdio, HTTP, SSE, or custom) to start serving MCP requests.