@breadstone/archipel-mcp 0.0.54 → 0.0.56

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

@@ -1,335 +0,0 @@
----
-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, health]
-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`
-
-<InstallTabs />
-
-## 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.
-
----
-
-## Health Check
-
-The `McpHealthIndicator` verifies that the `McpRegistryService` is injected. If no MCP registry is available, it reports `disabled: true`. Import it from the `/health` subpath:
-
-```typescript
-import { McpHealthIndicator } from '@breadstone/archipel-platform-mcp/health';
-import { HealthModule } from '@breadstone/archipel-platform-health';
-
-@Module({
-  imports: [
-    McpModule.register({ /* ... */ }),
-    HealthModule.withIndicators([McpHealthIndicator]),
-  ],
-})
-export class AppModule {}
-```
-
-| Key | Check | Dependencies |
-| --- | ----- | ------------ |
-| `mcp` | `up` if `McpRegistryService` injected, else `disabled` | `@Optional() McpRegistryService` |
-
----
-
-## Resource Limits & Shutdown
-
-| Limit                | Value      | Description                                                              |
-| -------------------- | ---------- | ------------------------------------------------------------------------ |
-| **Max transports**   | 1,000      | `McpServerService` tracks up to 1,000 active transports                  |
-| **Shutdown timeout** | 5 seconds  | Each transport and the server are closed with a 5-second timeout guard   |
-
-When the module is destroyed, `McpServerService.onModuleDestroy()` iterates all active transports, closes each with a 5-second timeout, and then closes the MCP server itself.

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

@@ -1,207 +0,0 @@
----
-title: platform-openapi
-description: Multi-tenant Swagger/OpenAPI documentation with feature-scoped discovery.
-order: 8
-tags: [openapi, swagger, documentation, api, multi-tenant]
-package: '@breadstone/archipel-platform-openapi'
----
-
-# platform-openapi
-
-Multi-tenant Swagger/OpenAPI documentation system with feature-scoped discovery, customizable themes, and automatic endpoint registration.
-
-**Package:** `@breadstone/archipel-platform-openapi`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module, Controller, Get, Param } from '@nestjs/common';
-import { SwaggerFeature, Api } from '@breadstone/archipel-platform-openapi';
-
-@SwaggerFeature({
-  name: 'users',
-  title: 'My App API — Users',
-  description: 'User CRUD and profile operations.',
-  tag: 'Users',
-  tags: ['Users'],
-})
-@Module({
-  controllers: [UserController],
-})
-export class UserModule {}
-
-@Controller('api/v1/users')
-export class UserController {
-  @Api({
-    tags: 'Users',
-    summary: 'Get user by ID',
-    responses: [{ status: 200, description: 'User found', type: UserResponse }],
-  })
-  @Get(':id')
-  public async getUser(@Param('id') id: string): Promise<UserResponse> {
-    // ...
-  }
-}
-```
-
----
-
-## Feature-Scoped Documentation
-
-The key concept is **per-feature Swagger documents** — each feature or module gets its own Swagger UI page, so teams can work independently without cluttering a single monolithic spec.
-
-### @SwaggerFeature Decorator
-
-Associates a module with a named feature group:
-
-```typescript
-import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';
-
-@SwaggerFeature({
-  name: 'orders',
-  title: 'My App API — Orders',
-  description: 'Order management and fulfillment.',
-  tag: 'Orders',
-  tags: ['Orders'],
-})
-@Module({
-  controllers: [OrderController],
-})
-export class OrderModule {}
-```
-
-### @Api Decorator
-
-Enriches individual endpoints with OpenAPI metadata:
-
-```typescript
-import { Api } from '@breadstone/archipel-platform-openapi';
-
-@Api({
-    summary: 'Create a new order',
-    operation: { description: 'Creates an order and initiates payment processing.' },
-    responses: [
-        { status: 201, description: 'Order created successfully' },
-        { status: 400, description: 'Invalid order data' },
-        { status: 402, description: 'Payment required' },
-    ],
-})
-@Post()
-public async createOrder(@Body() body: CreateOrderDto): Promise<OrderResponse> { /* ... */ }
-```
-
----
-
-## Multi-Document Service
-
-Generate separate Swagger documents per feature:
-
-```typescript
-import { SwaggerMultiDocumentService } from '@breadstone/archipel-platform-openapi';
-
-@Injectable()
-export class DocsController {
-  constructor(private readonly _swaggerDocs: SwaggerMultiDocumentService) {}
-
-  public generateAll(): Map<string, OpenAPIObject> {
-    return this._swaggerDocs.generateAll();
-    // Returns a map: 'User Management' → OpenAPI spec, 'Orders' → OpenAPI spec, ...
-  }
-}
-```
-
-### Bootstrap Setup
-
-```typescript
-import {
-  SwaggerFeatureDiscovery,
-  SwaggerFeatureRegistry,
-  SwaggerMultiDocumentService,
-} from '@breadstone/archipel-platform-openapi';
-import { ConfigService, ContentTemplateEngine, HostService, ResourceManager } from '@breadstone/archipel-platform-core';
-
-async function bootstrap(): Promise<void> {
-  const app = await NestFactory.create(AppModule);
-
-  const configService = app.get(ConfigService);
-  const hostService = app.get(HostService);
-  const resourceManager = app.get(ResourceManager);
-  const contentTemplateEngine = app.get(ContentTemplateEngine);
-
-  // 1. Discover features
-  const featureRegistry = new SwaggerFeatureRegistry();
-  const discovery = new SwaggerFeatureDiscovery();
-  discovery.registerDiscoveredFeatures(featureRegistry);
-  discovery.registerDefaultFeatures(featureRegistry);
-
-  // 2. Setup multi-document Swagger UI
-  const swaggerService = new SwaggerMultiDocumentService(
-    app,
-    configService,
-    hostService,
-    featureRegistry,
-    resourceManager,
-    contentTemplateEngine,
-  );
-  await swaggerService.setupMultipleSwaggerDocuments();
-
-  await app.listen(3000);
-}
-```
-
----
-
-## Discovery & Registry
-
-### SwaggerFeatureDiscovery
-
-Reads the global store populated by `@SwaggerFeature()` decorators and registers features into a `SwaggerFeatureRegistry`:
-
-```typescript
-import { SwaggerFeatureDiscovery, SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';
-
-const featureRegistry = new SwaggerFeatureRegistry();
-const discovery = new SwaggerFeatureDiscovery();
-
-discovery
-  .registerDiscoveredFeatures(featureRegistry)
-  .registerDefaultFeatures(featureRegistry);
-```
-
-### SwaggerFeatureRegistry
-
-Holds the finalized, immutable list of features. After all features are registered, call `finalize()`:
-
-```typescript
-import { SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';
-
-const registry = new SwaggerFeatureRegistry();
-
-registry.registerFeature({
-  name: 'admin',
-  title: 'My App API — Admin',
-  description: 'Admin-only endpoints.',
-  tag: 'Admin',
-  tags: ['Admin'],
-  path: 'docs/admin',
-});
-
-registry.finalize();
-const features = registry.getFeatures(); // sorted, read-only copy
-```
-
----
-
-## Exports Summary
-
-| Export                        | Type      | Description                     |
-| ----------------------------- | --------- | ------------------------------- |
-| `Api`                         | Decorator | OpenAPI endpoint metadata       |
-| `SwaggerFeature`              | Decorator | Feature-scoped Swagger grouping |
-| `SwaggerFeatureDiscovery`     | Service   | Auto-discover features          |
-| `SwaggerFeatureRegistry`      | Service   | Manage feature configs          |
-| `SwaggerMultiDocumentService` | Service   | Generate per-feature specs      |
-| `SwaggerTheme`                | Utility   | Theme customization (CSS/JS cached after first load) |
-| `IFeatureSwaggerConfig`       | Interface | Feature config shape            |