@breadstone/archipel-mcp 0.0.10 → 0.0.11

package/data/guides/implementing-ports.md

@@ -0,0 +1,317 @@
+---
+title: Implementing Ports
+description: How the port/adapter pattern works in Archipel and how to implement adapters for each package.
+order: 2
+---
+
+# Implementing Ports
+
+Archipel libraries don't hardcode how you store data, send emails, or check permissions. Instead, they define **ports** — abstract classes describing what the library needs — and your application provides **adapters** — concrete classes that implement those methods with your specific database, API, or logic.
+
+This guide covers why ports are abstract classes, which ports exist across all packages, how to write and register adapters, and what happens when optional ports are omitted.
+
+## Why Abstract Classes?
+
+NestJS uses a token-based dependency injection system. Every injectable needs a token for resolution. Archipel uses abstract classes as ports because they serve two purposes simultaneously:
+
+1. **Type contract** — They define the method signatures your adapter must implement. TypeScript enforces this at compile time.
+2. **DI token** — NestJS can use the class reference directly as an injection token, so there's no need for separate `Symbol()` tokens or string identifiers.
+
+```typescript
+// Inside the platform library — you don't write this, it's already there
+@Injectable()
+export class SessionService {
+  constructor(
+    private readonly _sessionPersistence: SessionPersistencePort,
+    // The abstract class IS the DI token
+  ) {}
+}
+```
+
+When you pass `{ sessionPersistence: PrismaSessionAdapter }` to `register()`, the library binds your concrete class to the abstract class token. NestJS resolves it automatically wherever the port is injected.
+
+---
+
+## All Ports Reference
+
+Every port across all Archipel packages:
+
+| Package                   | Port                         | Purpose                                        | Required |
+| ------------------------- | ---------------------------- | ---------------------------------------------- | -------- |
+| `platform-authentication` | `AuthSubjectPort`            | User lookup for authentication strategies      | Yes      |
+| `platform-authentication` | `MfaSubjectPort`             | MFA state persistence (enable/disable, verify) | Yes      |
+| `platform-authentication` | `SessionPersistencePort`     | Session storage, querying, and cleanup         | Yes      |
+| `platform-authentication` | `VerificationSubjectPort`    | Email/PIN verification persistence             | Yes      |
+| `platform-authentication` | `SocialAuthPort`             | OAuth user creation and account linking        | No       |
+| `platform-authentication` | `TokenEnricherPort`          | Add custom claims to JWTs                      | No       |
+| `platform-blob-storage`   | `BlobObjectPersistencePort`  | Track blob metadata after upload/delete        | No       |
+| `platform-blob-storage`   | `BlobVariantPersistencePort` | Track image variant metadata                   | No       |
+| `platform-payments`       | `FeatureAccessPort`          | Feature quota checks and usage recording       | No       |
+
+Packages not listed here (`platform-core`, `platform-database`, `platform-logging`, `platform-telemetry`, `platform-openapi`, `platform-reporting`, `platform-documents`, `platform-mailing`, `platform-mcp`) have no ports — they work out of the box with configuration only.
+
+---
+
+## Writing an Adapter
+
+### Step 1: Create the Adapter File
+
+Create one file per adapter in an `adapters/` directory in your application:
+
+```
+src/
+  adapters/
+    PrismaAuthSubjectAdapter.ts
+    PrismaMfaSubjectAdapter.ts
+    PrismaSessionAdapter.ts
+    PrismaVerificationAdapter.ts
+```
+
+### Step 2: Extend the Port
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { AuthSubjectPort, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
+import { PrismaService } from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class PrismaAuthSubjectAdapter extends AuthSubjectPort {
+  private readonly _prisma: PrismaService;
+
+  constructor(prisma: PrismaService) {
+    super();
+    this._prisma = prisma;
+  }
+
+  public async findById(id: string): Promise<IAuthSubject | null> {
+    const user = await this._prisma.user.findUnique({
+      where: { id },
+      select: {
+        id: true,
+        userName: true,
+        email: true,
+        password: true,
+        isVerified: true,
+        isAnonymous: true,
+        roles: true,
+        mfaEnabled: true,
+      },
+    });
+
+    return user ?? null;
+  }
+
+  public async findByLogin(login: string): Promise<IAuthSubject | null> {
+    const user = await this._prisma.user.findFirst({
+      where: { OR: [{ userName: login }, { email: login }] },
+      select: {
+        id: true,
+        userName: true,
+        email: true,
+        password: true,
+        isVerified: true,
+        isAnonymous: true,
+        roles: true,
+        mfaEnabled: true,
+      },
+    });
+
+    return user ?? null;
+  }
+
+  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
+    const user = await this._prisma.user.findFirst({
+      where: { userName, isAnonymous: true },
+      select: {
+        id: true,
+        userName: true,
+        email: true,
+        password: true,
+        isVerified: true,
+        isAnonymous: true,
+        roles: true,
+        mfaEnabled: true,
+      },
+    });
+
+    return user ?? null;
+  }
+}
+```
+
+**Key rules:**
+
+- Always annotate with `@Injectable()` — the adapter is a NestJS provider and participates in DI.
+- Always call `super()` in the constructor — the abstract class may have a constructor that sets up internal state.
+- Return the port's interface type (`IAuthSubject`, `ISessionRecord`, etc.), not your raw Prisma model. The port defines the contract.
+- Inject your own dependencies via constructor — the adapter has full access to NestJS DI, so it can use your `PrismaService`, `HttpService`, or anything else.
+- One adapter per port — don't combine multiple ports in one class. NestJS resolves each port token independently.
+
+### Step 3: Register
+
+Pass the adapter class (not an instance) to the module's `register()` method:
+
+```typescript
+AuthModule.register({
+  authSubject: PrismaAuthSubjectAdapter,
+  mfaSubject: PrismaMfaSubjectAdapter,
+  sessionPersistence: PrismaSessionAdapter,
+  verificationSubject: PrismaVerificationAdapter,
+});
+```
+
+NestJS handles instantiation and dependency resolution. You pass the class reference, the framework does the rest.
+
+---
+
+## Schema Mapping
+
+Your database schema won't always match the port interface field-for-field. The adapter is where you handle the translation. This is one of the main reasons adapters exist — they decouple the library's expectations from your specific data model.
+
+```typescript
+public async findById(id: string): Promise<IAuthSubject | null> {
+  const user = await this._prisma.user.findUnique({
+    where: { id },
+    include: { userRoles: { include: { role: true } } },
+  });
+
+  if (!user) return null;
+
+  return {
+    id: user.id,
+    userName: user.username,              // different casing
+    email: user.emailAddress,             // different field name
+    password: user.passwordHash,          // different field name
+    isVerified: user.emailVerified,       // different field name
+    isAnonymous: user.type === 'anonymous', // derived from enum
+    roles: user.userRoles.map((ur) => ur.role.name), // flattened relation
+    mfaEnabled: user.twoFactorEnabled,    // different field name
+  };
+}
+```
+
+As long as the returned object satisfies the port's interface, the platform library doesn't care what your underlying schema looks like.
+
+---
+
+## Adapters for External APIs
+
+Ports aren't limited to database adapters. You can implement an adapter that calls an external API, talks to a microservice, or reads from a cache — anything that fulfills the contract.
+
+```typescript
+@Injectable()
+export class Auth0AuthSubjectAdapter extends AuthSubjectPort {
+  private readonly _http: HttpService;
+
+  constructor(http: HttpService) {
+    super();
+    this._http = http;
+  }
+
+  public async findById(id: string): Promise<IAuthSubject | null> {
+    const { data } = await firstValueFrom(this._http.get(`https://my-tenant.auth0.com/api/v2/users/${id}`));
+
+    return {
+      id: data.user_id,
+      userName: data.nickname,
+      email: data.email,
+      password: '',
+      isVerified: data.email_verified,
+      isAnonymous: false,
+      roles: data.app_metadata?.roles ?? [],
+      mfaEnabled: data.multifactor?.length > 0,
+    };
+  }
+
+  public async findByLogin(login: string): Promise<IAuthSubject | null> {
+    const { data } = await firstValueFrom(
+      this._http.get('https://my-tenant.auth0.com/api/v2/users', {
+        params: { q: `email:"${login}" OR nickname:"${login}"` },
+      }),
+    );
+
+    return data[0] ? this.mapToAuthSubject(data[0]) : null;
+  }
+
+  // ...
+}
+```
+
+The library has no idea it's talking to Auth0. It calls `findById()` and gets back an `IAuthSubject` — that's the entire contract.
+
+---
+
+## In-Memory Adapters for Testing
+
+For integration tests where you need a working port without a real database, create in-memory implementations:
+
+```typescript
+@Injectable()
+export class InMemoryAuthSubjectAdapter extends AuthSubjectPort {
+  private readonly _subjects = new Map<string, IAuthSubject>();
+
+  public seed(subjects: IAuthSubject[]): void {
+    subjects.forEach((s) => this._subjects.set(s.id, s));
+  }
+
+  public async findById(id: string): Promise<IAuthSubject | null> {
+    return this._subjects.get(id) ?? null;
+  }
+
+  public async findByLogin(login: string): Promise<IAuthSubject | null> {
+    return [...this._subjects.values()].find((s) => s.userName === login || s.email === login) ?? null;
+  }
+
+  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
+    return [...this._subjects.values()].find((s) => s.userName === userName && s.isAnonymous) ?? null;
+  }
+}
+```
+
+This pattern works for any port. Seed with test data, inject into the module under test, and your tests run fast and deterministically without database fixtures. See the [Testing](/guides/testing) guide for full integration test examples.
+
+---
+
+## Optional Ports
+
+Some ports are optional. When not provided, the library gracefully degrades — the feature that depends on that port simply isn't available. The library's internal services use `@Optional()` on the injection, so they receive `undefined` and skip the corresponding logic.
+
+### TokenEnricherPort (Authentication)
+
+When omitted, JWTs contain only the base claims (`id`, `email`, `roles`). When provided, `AuthTokenService` calls your adapter's `enrichClaims()` method and merges the result into every token.
+
+```typescript
+@Injectable()
+export class AppTokenEnricherAdapter extends TokenEnricherPort {
+  public async enrichClaims(subject: IAuthSubject): Promise<Record<string, unknown>> {
+    return {
+      subscriptionTier: 'pro',
+      organizationId: 'org-123',
+    };
+  }
+}
+```
+
+### SocialAuthPort (Authentication)
+
+When omitted, OAuth strategies (GitHub, Google, Microsoft, Apple) are not registered — the routes don't exist. When provided, all configured strategies become active and the library handles the OAuth callback flow.
+
+### BlobObjectPersistencePort / BlobVariantPersistencePort (Blob Storage)
+
+When omitted, blob uploads and deletes work normally, but metadata isn't tracked in your database. When provided, `BlobService` calls the persistence port after each operation so you can maintain your own blob inventory.
+
+### FeatureAccessPort (Payments)
+
+When omitted, `FeatureGuard` and `FeatureUsageInterceptor` have no access port and will deny or skip feature checks. When provided, they delegate quota enforcement and usage recording to your adapter.
+
+---
+
+## Common Mistakes
+
+**Not calling `super()`** — If you forget `super()` in the constructor, JavaScript throws a runtime error. Abstract classes are still real classes with constructors.
+
+**Returning raw Prisma objects** — If your Prisma model includes extra fields beyond what the port interface expects, don't return it raw. Always map to the exact interface shape. Extra fields won't cause type errors but may leak internal data.
+
+**Sharing adapters across ports** — Don't make one class implement two different ports. Each port has its own DI token, and NestJS resolves them independently. One class, one port, one responsibility.
+
+**Registering instances instead of classes** — `register()` expects the class reference (`PrismaAuthSubjectAdapter`), not `new PrismaAuthSubjectAdapter()`. NestJS creates the instance and injects its dependencies automatically.

package/data/guides/index.md

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