@breadstone/archipel-mcp 0.0.10 → 0.0.13

package/data/guides/index.md

@@ -0,0 +1,62 @@
+---
+title: Guides
+description: Developer guides for integrating and working with Archipel platform libraries.
+---
+
+# Guides
+
+Practical guides for working with Archipel packages in your NestJS application.
+
+## Foundations
+
+| Guide                                      | What you'll learn                                                                      |
+| ------------------------------------------ | -------------------------------------------------------------------------------------- |
+| [Getting Started](./getting-started)       | Install packages, register your first module, implement ports, and run the app.        |
+| [Implementing Ports](./implementing-ports) | How the port/adapter pattern works, how to write adapters, and how to test them.       |
+| [Testing](./testing)                       | Unit testing services, testing port adapters, integration testing with real databases. |
+| [TSDoc Guidelines](./tsdoc-guidelines)     | Documentation standards for public APIs and generated reference pages.                 |
+
+## Security & Identity
+
+| Guide                                                                | What you'll learn                                                                    |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [Authentication & Authorization](./authentication-and-authorization) | JWT tokens, role-based access, custom scopes, MFA, sessions, and OAuth social login. |
+| [Cryptography & OTP](./cryptography-and-otp)                         | Bcrypt password hashing, prefixed UUIDs, and TOTP multi-factor authentication.       |
+
+## Data & Storage
+
+| Guide                                           | What you'll learn                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [Database Setup](./database-setup)              | PostgreSQL via Prisma, Accelerate, repositories, queries, transactions, and health.   |
+| [Blob Storage](./blob-storage)                  | Multi-provider file storage, uploads, signed URLs, and metadata tracking.             |
+| [Document Generation](./document-generation)    | Generate PDF and DOCX from templates with variable substitution and image processing. |
+| [E-Signing Integration](./esigning-integration) | Electronic signature workflows, provider setup, and webhook handling.                 |
+
+## Communication & Payments
+
+| Guide                                                      | What you'll learn                                                                 |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| [Email Delivery](./email-delivery)                         | Multi-provider email sending, template engines, and verification flows.           |
+| [Payments & Feature Gating](./payments-and-feature-gating) | Payment provider integration, webhook handling, and feature-based access control. |
+
+## Operations & Observability
+
+| Guide                                                        | What you'll learn                                                                     |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [Telemetry & Observability](./telemetry-and-observability)   | OpenTelemetry metrics, distributed tracing, and structured logging.                   |
+| [Analytics & Error Tracking](./analytics-and-error-tracking) | Capture errors and user context with Sentry, AppInsights, or Datadog.                 |
+| [Caching](./caching)                                         | In-memory LRU and Redis layered caches with TTL, stale-while-revalidate, and metrics. |
+
+## AI & Extensibility
+
+| Guide                                      | What you'll learn                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| [AI Text Generation](./ai-text-generation) | Multi-provider text completions, capability registry, and intent orchestration. |
+| [MCP Server](./mcp-server)                 | Build MCP servers with tools, resources, and prompts for AI agent integration.  |
+
+## Platform Internals
+
+| Guide                                                          | What you'll learn                                                                         |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [OpenAPI & Feature Discovery](./openapi-and-feature-discovery) | Multi-document Swagger UI, the @Api decorator, and automatic per-module doc discovery.    |
+| [Resource Management](./resource-management)                   | Load templates, assets, and files from disk, blob storage, or memory via ResourceManager. |

package/data/guides/mcp-server.md

@@ -0,0 +1,222 @@
+---
+title: MCP Server
+description: Build a Model Context Protocol (MCP) server with tools, resources, and prompts for AI agent integration.
+order: 13
+---
+
+# MCP Server
+
+This guide covers building an MCP server with `platform-mcp`: defining tools, resources, and prompts that AI agents can discover and invoke, selecting transports, and registering everything with auto-discovery.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-mcp
+```
+
+---
+
+## What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI agents to external tools and data sources. An MCP server exposes:
+
+- **Tools** — Functions the AI can call (e.g., search a database, create a record)
+- **Resources** — Data the AI can read (e.g., configuration, documentation)
+- **Prompts** — Pre-built prompt templates the AI can use
+
+`platform-mcp` provides decorators and a discovery service that auto-registers your tools, resources, and prompts.
+
+---
+
+## Module Registration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { McpModule } from '@breadstone/archipel-platform-mcp';
+
+@Module({
+  imports: [
+    McpModule.register({
+      name: 'my-api-mcp',
+      version: '1.0.0',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Or asynchronously with configuration:
+
+```typescript
+import { McpModule } from '@breadstone/archipel-platform-mcp';
+import { ConfigService } from '@breadstone/archipel-platform-core';
+
+McpModule.registerAsync({
+  useFactory: (configService: ConfigService) => ({
+    name: configService.get('MCP_SERVER_NAME'),
+    version: configService.get('MCP_SERVER_VERSION'),
+  }),
+  inject: [ConfigService],
+}),
+```
+
+---
+
+## Defining Tools
+
+Use `@McpTool()` to define callable functions:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { McpTool } from '@breadstone/archipel-platform-mcp';
+
+@Injectable()
+export class UserTools {
+  @McpTool({
+    name: 'search_users',
+    description: 'Search for users by name or email',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search term' },
+        limit: { type: 'number', description: 'Max results', default: 10 },
+      },
+      required: ['query'],
+    },
+  })
+  public async searchUsers(params: { query: string; limit?: number }): Promise<unknown> {
+    // Implementation: search your database and return results
+  }
+
+  @McpTool({
+    name: 'get_user',
+    description: 'Get a user by their ID',
+    parameters: {
+      type: 'object',
+      properties: {
+        userId: { type: 'string', description: 'The user ID' },
+      },
+      required: ['userId'],
+    },
+  })
+  public async getUser(params: { userId: string }): Promise<unknown> {
+    // Implementation: fetch a single user
+  }
+}
+```
+
+---
+
+## Defining Resources
+
+Use `@McpResource()` to expose data that AI agents can read:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { McpResource } from '@breadstone/archipel-platform-mcp';
+
+@Injectable()
+export class DocsResources {
+  @McpResource({
+    name: 'api_documentation',
+    description: 'API documentation and usage guidelines',
+    uri: 'docs://api/overview',
+  })
+  public async getApiDocs(): Promise<string> {
+    return `
+      # API Overview
+      Base URL: https://api.yourapp.com/v1
+      Authentication: Bearer token required
+      Rate limit: 1000 requests/hour
+    `;
+  }
+}
+```
+
+---
+
+## Defining Prompts
+
+Use `@McpPrompt()` to register reusable prompt templates:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { McpPrompt } from '@breadstone/archipel-platform-mcp';
+
+@Injectable()
+export class AnalysisPrompts {
+  @McpPrompt({
+    name: 'analyze_user_activity',
+    description: "Analyze a user's recent activity and provide insights",
+    parameters: {
+      type: 'object',
+      properties: {
+        userId: { type: 'string', description: 'The user to analyze' },
+        timeRange: { type: 'string', description: 'Time range (e.g., 7d, 30d)', default: '7d' },
+      },
+      required: ['userId'],
+    },
+  })
+  public getTemplate(params: { userId: string; timeRange?: string }): string {
+    return `Analyze the recent activity for user ${params.userId} over the last ${params.timeRange ?? '7d'}.
+    Provide insights on usage patterns, feature adoption, and potential issues.`;
+  }
+}
+```
+
+---
+
+## Auto-Discovery
+
+`McpDiscoveryService` automatically finds and registers all classes that use `@McpTool`, `@McpResource`, or `@McpPrompt` decorators. Just ensure the classes are registered as NestJS providers:
+
+```typescript
+@Module({
+  imports: [McpModule.register({ name: 'my-api-mcp', version: '1.0.0' })],
+  providers: [UserTools, DocsResources, AnalysisPrompts],
+})
+export class McpFeatureModule {}
+```
+
+---
+
+## Transport Options
+
+MCP supports multiple transport protocols:
+
+| Transport | When to use                                   |
+| --------- | --------------------------------------------- |
+| **SSE**   | Browser-based AI agents, streaming responses  |
+| **HTTP**  | Standard REST-based AI agent communication    |
+| **Stdio** | CLI tools, local development, piped processes |
+
+The `McpServerService` handles transport negotiation automatically.
+
+---
+
+## Connecting the Guides
+
+The MCP server can expose Archipel's guides as resources. This makes your documentation discoverable by AI agents:
+
+```typescript
+@Injectable()
+export class GuideResources {
+  @McpResource({
+    name: 'guide_authentication',
+    description: 'Guide for setting up authentication and authorization',
+    uri: 'docs://guides/authentication-and-authorization',
+  })
+  public async getAuthGuide(): Promise<string> {
+    // Read and return the guide content
+  }
+}
+```
+
+---
+
+## Next Steps
+
+- Browse the [platform-mcp API reference](/packages/platform-mcp/api/) for complete decorator options
+- See the [Getting Started](/guides/getting-started) guide for basic module setup

package/data/guides/openapi-and-feature-discovery.md

@@ -0,0 +1,266 @@
+---
+title: OpenAPI & Feature Discovery
+description: Set up multi-document Swagger UI, annotate controllers with the @Api decorator, and use @SwaggerFeature for automatic per-module documentation discovery.
+order: 16
+---
+
+# OpenAPI & Feature Discovery
+
+This guide covers the full lifecycle of API documentation with `platform-openapi`: installing the package, configuring environment variables, annotating controllers, registering feature modules, and bootstrapping the multi-document Swagger UI.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-openapi
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+All four variables are **required**:
+
+```env
+APP_VERSION=1.0.0
+SWAGGER_CONTACT_NAME=Your Team
+SWAGGER_CONTACT_URL=https://yourcompany.com
+SWAGGER_CONTACT_EMAIL=api@yourcompany.com
+```
+
+| Variable                | Purpose                                            |
+| ----------------------- | -------------------------------------------------- |
+| `APP_VERSION`           | Version shown in every generated OpenAPI document. |
+| `SWAGGER_CONTACT_NAME`  | Contact name in the info block.                    |
+| `SWAGGER_CONTACT_URL`   | Contact URL in the info block.                     |
+| `SWAGGER_CONTACT_EMAIL` | Contact email in the info block.                   |
+
+---
+
+## Overview: How It Works
+
+```
+  @SwaggerFeature()        SwaggerFeatureDiscovery       SwaggerFeatureRegistry       SwaggerMultiDocumentService
+  ──────────────────       ──────────────────────       ──────────────────────       ───────────────────────────
+  Decorator stores          Reads global store and       Holds finalized list of      Builds per-feature OpenAPI
+  metadata in global        registers features into      features. Sorted, locked,    documents, sets up Swagger
+  store at import time.     the registry.                immutable after finalize().  UI routes, and index page.
+```
+
+1. Each feature module is decorated with `@SwaggerFeature()` — metadata is stored globally when the module is imported.
+2. During bootstrap, `SwaggerFeatureDiscovery` reads all registered features and pushes them into `SwaggerFeatureRegistry`.
+3. `SwaggerMultiDocumentService` finalizes the registry, builds one OpenAPI document per feature (filtered by tag), and mounts Swagger UI + JSON endpoints.
+
+---
+
+## Step 1: Annotate Feature Modules
+
+Decorate each feature module with `@SwaggerFeature()`. This tells the discovery system which tag corresponds to which documentation section.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';
+import { TipController } from './TipController';
+import { TipService } from './TipService';
+
+@SwaggerFeature({
+  name: 'tip',
+  title: 'My App API — Tips',
+  description: 'API endpoints for tip management.',
+  tag: 'Tip',
+  tags: ['Tip'],
+})
+@Module({
+  controllers: [TipController],
+  providers: [TipService],
+  exports: [TipService],
+})
+export class TipModule {}
+```
+
+| Property      | Required | Description                                                                  |
+| ------------- | -------- | ---------------------------------------------------------------------------- |
+| `name`        | Yes      | Short identifier used for the URL path (e.g. `docs/tip`).                    |
+| `title`       | Yes      | Human-readable title shown in the Swagger UI header.                         |
+| `description` | Yes      | Description shown in the Swagger UI header and on the index page.            |
+| `tag`         | Yes      | Primary OpenAPI tag — operations with this tag are included in the document. |
+| `tags`        | Yes      | Array of all tags to include. Usually `[tag]`.                               |
+| `path`        | No       | Custom URL path. Defaults to `docs/{name}`.                                  |
+
+---
+
+## Step 2: Annotate Controllers with `@Api()`
+
+`@Api()` is a convenience decorator that combines multiple `@nestjs/swagger` decorators into one. Use it on methods or classes to keep controller annotations concise.
+
+```typescript
+import { Controller, Get, Post, Body, Param, HttpCode, HttpStatus } from '@nestjs/common';
+import { Api } from '@breadstone/archipel-platform-openapi';
+import { CreateTipRequest } from './dto/CreateTipRequest';
+import { TipResponse } from './dto/TipResponse';
+
+@Controller('api/v1/tips')
+export class TipController {
+  @Get()
+  @Api({
+    tags: 'Tip',
+    operation: { summary: 'List all tips' },
+    responses: [{ status: 200, description: 'Tips retrieved.', type: [TipResponse] }],
+  })
+  public listTips(): Promise<TipResponse[]> {
+    // ...
+  }
+
+  @Get(':tipId')
+  @Api({
+    tags: 'Tip',
+    auth: 'bearer',
+    operation: { summary: 'Get a tip by ID' },
+    params: { name: 'tipId', type: String },
+    responses: [
+      { status: 200, description: 'Tip found.', type: TipResponse },
+      { status: 404, description: 'Tip not found.' },
+    ],
+  })
+  public getTip(@Param('tipId') tipId: string): Promise<TipResponse> {
+    // ...
+  }
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  @Api({
+    tags: 'Tip',
+    auth: 'bearer',
+    operation: { summary: 'Create a new tip' },
+    body: { type: CreateTipRequest },
+    responses: [
+      { status: 201, description: 'Tip created.', type: TipResponse },
+      { status: 400, description: 'Validation failed.' },
+    ],
+  })
+  public createTip(@Body() body: CreateTipRequest): Promise<TipResponse> {
+    // ...
+  }
+}
+```
+
+### `@Api()` Options Reference
+
+| Option       | Type                                          | Description                                          |
+| ------------ | --------------------------------------------- | ---------------------------------------------------- |
+| `auth`       | `'bearer' \| 'basic' \| 'oauth2' \| 'cookie'` | Adds the corresponding auth decorator.               |
+| `tags`       | `string \| string[]`                          | OpenAPI tag(s) for the operation.                    |
+| `operation`  | `ApiOperationOptions`                         | Summary, description, deprecation flag, etc.         |
+| `responses`  | `ApiResponseOptions \| ApiResponseOptions[]`  | One or more response definitions.                    |
+| `headers`    | `ApiHeaderOptions[]`                          | Expected request headers.                            |
+| `params`     | `ApiParamOptions \| ApiParamOptions[]`        | Path parameter definitions.                          |
+| `query`      | `ApiQueryOptions \| ApiQueryOptions[]`        | Query parameter definitions.                         |
+| `body`       | `ApiBodyOptions`                              | Request body definition.                             |
+| `scopes`     | `string[]`                                    | OAuth2 scopes (only relevant when `auth: 'oauth2'`). |
+| `extensions` | `Record<string, string \| number \| boolean>` | Custom OpenAPI extension properties (`x-*`).         |
+
+---
+
+## Step 3: Bootstrap the Swagger UI
+
+In your application bootstrap (`main.ts`), wire up discovery and the multi-document service:
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import {
+  SwaggerFeatureDiscovery,
+  SwaggerFeatureRegistry,
+  SwaggerMultiDocumentService,
+} from '@breadstone/archipel-platform-openapi';
+import { ConfigService, ContentTemplateEngine, HostService, ResourceManager } from '@breadstone/archipel-platform-core';
+import { AppModule } from './AppModule';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Resolve services
+  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);
+}
+bootstrap();
+```
+
+After bootstrap the following routes are available:
+
+| Route              | What it serves                                      |
+| ------------------ | --------------------------------------------------- |
+| `/docs`            | Main index page with a searchable feature grid.     |
+| `/docs/{name}`     | Swagger UI for a single feature (e.g. `/docs/tip`). |
+| `/api/{name}.json` | Raw OpenAPI JSON for a single feature.              |
+| `/docs/all`        | Combined Swagger UI with every endpoint.            |
+| `/api/all.json`    | Combined OpenAPI JSON.                              |
+
+---
+
+## How Tag Filtering Works
+
+Each feature declares a `tag` (e.g. `'Tip'`). When the document is built:
+
+1. A full OpenAPI document is created from the entire application.
+2. All paths that do **not** have an operation tagged with the feature's tag are removed.
+3. Schema references used only by removed operations are pruned.
+4. The special tag `'*'` (used by the default `all` feature) skips filtering entirely.
+
+This means the `tag` value in `@SwaggerFeature()` must match the `tags` value you pass to `@Api()` on your controllers.
+
+---
+
+## Exporting OpenAPI Specs Programmatically
+
+If you need the generated OpenAPI documents outside of a running HTTP server (e.g. for CI contract checks or SDK generation), use `generateOpenApiDocuments()`:
+
+```typescript
+const documents = swaggerService.generateOpenApiDocuments();
+
+for (const { feature, document } of documents) {
+  const json = JSON.stringify(document, null, 2);
+  writeFileSync(`specs/${feature.name}.json`, json);
+}
+```
+
+---
+
+## Theme Customization
+
+`SwaggerTheme` loads `swagger.css` and `swagger.js` from the package assets via `ResourceManager`. These files customize the Swagger UI appearance (colors, dark theme, responsive layout). The theme is applied automatically — no additional configuration is needed.
+
+To override the theme, provide your own `swagger.css` / `swagger.js` files through a `FileResourceStrategy` with a higher-priority base path so that `ResourceManager` picks them up before the built-in assets.
+
+---
+
+## Checklist
+
+- [ ] All four environment variables set (`APP_VERSION`, `SWAGGER_CONTACT_*`)
+- [ ] Every feature module decorated with `@SwaggerFeature()`
+- [ ] Tags in `@SwaggerFeature({ tag })` match tags in `@Api({ tags })`
+- [ ] `SwaggerFeatureDiscovery` called before `setupMultipleSwaggerDocuments()`
+- [ ] `registerDefaultFeatures()` called for the combined `/docs/all` document