@breadstone/archipel-mcp 0.0.13 → 0.0.14

package/data/guides/index.md

@@ -1,62 +0,0 @@
----
-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

@@ -1,222 +0,0 @@
----
-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

@@ -1,266 +0,0 @@
----
-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