@breadstone/archipel-mcp 0.0.1

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

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

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

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

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

@@ -0,0 +1,123 @@
+---
+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
+
+### 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.
+
+## Functions
+
+### McpPrompt()
+
+```ts
+function McpPrompt(options): MethodDecorator;
+```
+
+Defined in: [decorators/McpPrompt.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/decorators/McpPrompt.ts#L15)
+
+Marks a method as an MCP prompt handler.
+
+The decorated method will be discovered at module initialization and registered
+with the MCP server. The method receives the parsed prompt arguments and
+should return an `MCP GetPromptResult`.
+
+#### Parameters
+
+| Parameter | Type                                                 | Description                   |
+| --------- | ---------------------------------------------------- | ----------------------------- |
+| `options` | [`IMcpPromptMetadata`](Interface.IMcpPromptMetadata) | Prompt registration metadata. |
+
+#### Returns
+
+`MethodDecorator`
+
+---
+
+### McpResource()
+
+```ts
+function McpResource(options): MethodDecorator;
+```
+
+Defined in: [decorators/McpResource.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/decorators/McpResource.ts#L15)
+
+Marks a method as an MCP resource handler.
+
+The decorated method will be discovered at module initialization and registered
+with the MCP server. The method receives the URI and parsed template parameters
+as arguments and should return an `MCP ReadResourceResult`.
+
+#### Parameters
+
+| Parameter | Type                                                     | Description                     |
+| --------- | -------------------------------------------------------- | ------------------------------- |
+| `options` | [`IMcpResourceMetadata`](Interface.IMcpResourceMetadata) | Resource registration metadata. |
+
+#### Returns
+
+`MethodDecorator`
+
+---
+
+### McpTool()
+
+```ts
+function McpTool(options): MethodDecorator;
+```
+
+Defined in: [decorators/McpTool.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mcp/src/decorators/McpTool.ts#L15)
+
+Marks a method as an MCP tool handler.
+
+The decorated method will be discovered at module initialization and registered
+with the MCP server. The method receives the parsed input as its first argument
+and should return an `MCP CallToolResult`.
+
+#### Parameters
+
+| Parameter | Type                                             | Description                 |
+| --------- | ------------------------------------------------ | --------------------------- |
+| `options` | [`IMcpToolMetadata`](Interface.IMcpToolMetadata) | Tool registration metadata. |
+
+#### Returns
+
+`MethodDecorator`

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.

package/data/packages/platform-openapi/api/Class.SwaggerFeatureDiscovery.md

@@ -0,0 +1,71 @@
+---
+title: 'Class: SwaggerFeatureDiscovery'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-openapi**](../)
+
+---
+
+# Class: SwaggerFeatureDiscovery
+
+Defined in: [discovery/SwaggerFeatureDiscovery.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-openapi/src/discovery/SwaggerFeatureDiscovery.ts#L13)
+
+Centralizes the discovery of Swagger features declared across backend modules.
+
+## Constructors
+
+### Constructor
+
+```ts
+new SwaggerFeatureDiscovery(): SwaggerFeatureDiscovery;
+```
+
+#### Returns
+
+`SwaggerFeatureDiscovery`
+
+## Methods
+
+### registerDefaultFeatures()
+
+```ts
+registerDefaultFeatures(featureRegistry): void;
+```
+
+Defined in: [discovery/SwaggerFeatureDiscovery.ts:40](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-openapi/src/discovery/SwaggerFeatureDiscovery.ts#L40)
+
+Registers the default composite Swagger documents that aggregate the complete API.
+
+#### Parameters
+
+| Parameter         | Type                                                     | Description                                             |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------------- |
+| `featureRegistry` | [`SwaggerFeatureRegistry`](Class.SwaggerFeatureRegistry) | The registry that collects Swagger feature information. |
+
+#### Returns
+
+`void`
+
+---
+
+### registerDiscoveredFeatures()
+
+```ts
+registerDiscoveredFeatures(featureRegistry): void;
+```
+
+Defined in: [discovery/SwaggerFeatureDiscovery.ts:22](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-openapi/src/discovery/SwaggerFeatureDiscovery.ts#L22)
+
+Registers all discovered feature modules in the provided Swagger registry.
+
+#### Parameters
+
+| Parameter         | Type                                                     | Description                                             |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------------- |
+| `featureRegistry` | [`SwaggerFeatureRegistry`](Class.SwaggerFeatureRegistry) | The registry that collects Swagger feature information. |
+
+#### Returns
+
+`void`