@breadstone/archipel-mcp 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# @breadstone/archipel-mcp
+
+MCP (Model Context Protocol) server that provides Archipel platform knowledge — documentation and query patterns — to AI development tools. The server acts as a structured knowledge provider: AI models combine this knowledge with the user's project context to generate framework-compliant code.
+
+## Usage
+
+### VS Code MCP Configuration
+
+Add to your `.vscode/mcp.json` (or global `settings.json`):
+
+```json
+{
+  "servers": {
+    "archipel": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@breadstone/archipel-mcp"]
+    }
+  }
+}
+```
+
+### Direct Execution
+
+```bash
+npx @breadstone/archipel-mcp
+```
+
+## Tools
+
+| Tool                | Description                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| `list-packages`     | Lists all Archipel platform packages with descriptions and tags.                             |
+| `get-package-doc`   | Returns the full documentation (overview + API reference) for a specific package.            |
+| `search-docs`       | Searches across all documentation by keyword or phrase.                                      |
+| `get-query-pattern` | Returns the v1 query pattern docs (interfaces, factories, rules). Optionally model-tailored. |
+
+### get-query-pattern
+
+Returns the complete Archipel v1 query pattern: `IRepositoryQuery` interface, `query()` factory, `QueryResultType`, transactional queries, rules, and usage examples. When a `modelName` and `fields` array are provided, it generates tailored `findFirst`, `findMany`, and `count` query examples for that model.
+
+```
+modelName?: string   — Prisma model name (e.g. "User")
+fields?: string[]    — Field names (e.g. ["id", "email", "name", "createdAt"])
+```
+
+## Architecture
+
+Plain Node.js MCP server using `@modelcontextprotocol/sdk`. No NestJS, no DI container.
+
+```
+main.ts                          ← CLI entry (stdio transport, tool registration)
+DocsLoader.ts                    ← Loads & indexes .docs/packages/ markdown files
+models/
+└── IPackageDoc.ts               ← Package documentation interface
+knowledge/
+└── queryPattern.ts              ← Query pattern knowledge content
+```
+
+### Documentation Resolution
+
+The server locates docs in this order:
+
+1. **Bundled data** — `<package>/data/packages/` (shipped with the npm package)
+2. **Workspace root** — `<cwd>/.docs/packages/` (monorepo development)
+3. **Relative fallback** — walks up from compiled source to find `.docs/packages/`
+
+## Development
+
+```bash
+# Build
+npx nx build mcp-server
+
+# Run locally (from workspace root)
+node dist/tools/mcp/src/main.js
+```
+
+## License
+
+See [LICENSE](../../LICENSE).

package/data/packages/index.md

@@ -0,0 +1,42 @@
+---
+title: Packages
+description: All Archipel platform packages with their primary capabilities.
+---
+
+# Packages
+
+Archipel is organized into 12 independent NestJS modules. Each package can be installed and used on its own — you only pull in what you need.
+
+Every package follows the same structure: a dynamic NestJS module with `register()` configuration, abstract ports for contracts you implement, and concrete services you consume.
+
+## Foundation
+
+| Package                                     | Description                                                                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| [`platform-core`](./platform-core/)         | Caching, configuration, cryptography, mapping, templates, and shared utilities. Every other package depends on this. |
+| [`platform-database`](./platform-database/) | Prisma + PostgreSQL integration with the repository/query pattern and transactional support.                         |
+
+## Identity & Access
+
+| Package                                                 | Description                                                                                                    |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [`platform-authentication`](./platform-authentication/) | JWT, OAuth (GitHub, Google, Microsoft, Apple), MFA, sessions, anonymous auth, and email verification.          |
+| [`platform-payments`](./platform-payments/)             | Multi-provider payment client (Stripe, LemonSqueezy, Paddle, Creem) with feature gating and quota enforcement. |
+
+## Infrastructure
+
+| Package                                             | Description                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`platform-blob-storage`](./platform-blob-storage/) | Provider-agnostic blob storage with metadata tracking and image variant support.                                   |
+| [`platform-mailing`](./platform-mailing/)           | Multi-strategy email delivery (SMTP, Postmark, Resend, Plunk, Log) with template rendering and verification flows. |
+| [`platform-documents`](./platform-documents/)       | Document generation with pluggable renderers for DOCX, PDF, and image processing.                                  |
+
+## Operations
+
+| Package                                       | Description                                                                                                  |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| [`platform-openapi`](./platform-openapi/)     | Feature-scoped Swagger/OpenAPI documentation with multi-document registry and discovery.                     |
+| [`platform-logging`](./platform-logging/)     | Sentry integration for structured error tracking and analytics.                                              |
+| [`platform-telemetry`](./platform-telemetry/) | OpenTelemetry tracing, metrics, a rule engine for conditional recording, and graceful noop fallback.         |
+| [`platform-reporting`](./platform-reporting/) | Contributor-based reporting engine with dataset registration and query execution.                            |
+| [`platform-mcp`](./platform-mcp/)             | Decorator-driven MCP (Model Context Protocol) server module with auto-discovery and multi-transport support. |

package/data/packages/platform-authentication/api/Class.AnonymousAuthGuard.md

@@ -0,0 +1,45 @@
+---
+title: 'Class: AnonymousAuthGuard'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: AnonymousAuthGuard
+
+Defined in: [libs/platform-authentication/src/guards/AnonymousAuthGuard.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/guards/AnonymousAuthGuard.ts#L14)
+
+The `AnonymousAuthGuard` protects routes using anonymous authentication.
+
+## Extends
+
+- `IAuthGuard`
+
+## Constructors
+
+### Constructor
+
+```ts
+new AnonymousAuthGuard(...args): AnonymousAuthGuard;
+```
+
+Defined in: node_modules/@nestjs/passport/dist/interfaces/type.interface.d.ts:2
+
+#### Parameters
+
+| Parameter | Type    |
+| --------- | ------- |
+| ...`args` | `any`[] |
+
+#### Returns
+
+`AnonymousAuthGuard`
+
+#### Inherited from
+
+```ts
+AuthGuard('anonymous').constructor;
+```

package/data/packages/platform-authentication/api/Class.AuthModule.md

@@ -0,0 +1,72 @@
+---
+title: 'Class: AuthModule'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: AuthModule
+
+Defined in: [libs/platform-authentication/src/AuthModule.ts:104](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/AuthModule.ts#L104)
+
+The `AuthModule` handles JWT-based authentication,
+including token creation and validation.
+
+## Constructors
+
+### Constructor
+
+```ts
+new AuthModule(): AuthModule;
+```
+
+#### Returns
+
+`AuthModule`
+
+## Methods
+
+### configure()
+
+```ts
+configure(consumer): void;
+```
+
+Defined in: [libs/platform-authentication/src/AuthModule.ts:208](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/AuthModule.ts#L208)
+
+#### Parameters
+
+| Parameter  | Type                 |
+| ---------- | -------------------- |
+| `consumer` | `MiddlewareConsumer` |
+
+#### Returns
+
+`void`
+
+---
+
+### register()
+
+```ts
+static register(options): DynamicModule;
+```
+
+Defined in: [libs/platform-authentication/src/AuthModule.ts:114](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/AuthModule.ts#L114)
+
+Registers the auth module with the provided port implementations.
+
+#### Parameters
+
+| Parameter | Type                                                 | Description                               |
+| --------- | ---------------------------------------------------- | ----------------------------------------- |
+| `options` | [`IAuthModuleOptions`](Interface.IAuthModuleOptions) | Port implementations for the auth module. |
+
+#### Returns
+
+`DynamicModule`
+
+The configured dynamic module.

package/data/packages/platform-authentication/api/Class.AuthSubjectPort.md

@@ -0,0 +1,100 @@
+---
+title: 'Abstract Class: AuthSubjectPort'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Abstract Class: AuthSubjectPort
+
+Defined in: [libs/platform-authentication/src/contracts/AuthSubjectPort.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/contracts/AuthSubjectPort.ts#L13)
+
+Abstract port for resolving authentication subjects by identity.
+Used by the JWT, Local, and Anonymous strategies.
+
+## Constructors
+
+### Constructor
+
+```ts
+new AuthSubjectPort(): AuthSubjectPort;
+```
+
+#### Returns
+
+`AuthSubjectPort`
+
+## Methods
+
+### findAnonymous()
+
+```ts
+abstract findAnonymous(userName): Promise<IAuthSubject | null>;
+```
+
+Defined in: [libs/platform-authentication/src/contracts/AuthSubjectPort.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/contracts/AuthSubjectPort.ts#L41)
+
+Find the anonymous / seed subject by user name.
+
+#### Parameters
+
+| Parameter  | Type     | Description              |
+| ---------- | -------- | ------------------------ |
+| `userName` | `string` | The anonymous user name. |
+
+#### Returns
+
+`Promise`\<[`IAuthSubject`](Interface.IAuthSubject) \| `null`\>
+
+The subject or `null`.
+
+---
+
+### findById()
+
+```ts
+abstract findById(id): Promise<IAuthSubject | null>;
+```
+
+Defined in: [libs/platform-authentication/src/contracts/AuthSubjectPort.ts:23](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/contracts/AuthSubjectPort.ts#L23)
+
+Find a subject by its unique identifier.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `id`      | `string` | The subject identifier. |
+
+#### Returns
+
+`Promise`\<[`IAuthSubject`](Interface.IAuthSubject) \| `null`\>
+
+The subject or `null`.
+
+---
+
+### findByLogin()
+
+```ts
+abstract findByLogin(login): Promise<IAuthSubject | null>;
+```
+
+Defined in: [libs/platform-authentication/src/contracts/AuthSubjectPort.ts:32](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/contracts/AuthSubjectPort.ts#L32)
+
+Find a subject by its login name (user name or email).
+
+#### Parameters
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `login`   | `string` | The login identifier. |
+
+#### Returns
+
+`Promise`\<[`IAuthSubject`](Interface.IAuthSubject) \| `null`\>
+
+The subject or `null`.

package/data/packages/platform-authentication/api/Class.AuthTokenService.md

@@ -0,0 +1,64 @@
+---
+title: 'Class: AuthTokenService'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: AuthTokenService
+
+Defined in: [libs/platform-authentication/src/services/AuthTokenService.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/AuthTokenService.ts#L18)
+
+Generic service responsible for creating JWT access tokens.
+Builds a base payload from [IAuthSubject](Interface.IAuthSubject) and optionally enriches it
+via the [TokenEnricherPort](Class.TokenEnricherPort) with product-specific claims.
+
+## Constructors
+
+### Constructor
+
+```ts
+new AuthTokenService(jwtService, tokenEnricher): AuthTokenService;
+```
+
+Defined in: [libs/platform-authentication/src/services/AuthTokenService.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/AuthTokenService.ts#L35)
+
+Constructs a new instance of the `AuthTokenService` class.
+
+#### Parameters
+
+| Parameter       | Type                                                     | Description                   |
+| --------------- | -------------------------------------------------------- | ----------------------------- |
+| `jwtService`    | `JwtService`                                             | The NestJS JWT service.       |
+| `tokenEnricher` | [`TokenEnricherPort`](Class.TokenEnricherPort) \| `null` | Optional token enricher port. |
+
+#### Returns
+
+`AuthTokenService`
+
+## Methods
+
+### createAccessToken()
+
+```ts
+createAccessToken(subject): Promise<string>;
+```
+
+Defined in: [libs/platform-authentication/src/services/AuthTokenService.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/AuthTokenService.ts#L51)
+
+Creates a signed JWT for the given subject.
+
+#### Parameters
+
+| Parameter | Type                                     | Description                |
+| --------- | ---------------------------------------- | -------------------------- |
+| `subject` | [`IAuthSubject`](Interface.IAuthSubject) | The authenticated subject. |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The signed JWT access token.

package/data/packages/platform-authentication/api/Class.ChallengeService.md

@@ -0,0 +1,136 @@
+---
+title: 'Class: ChallengeService'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: ChallengeService
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L29)
+
+Stores and validates MFA login challenges.
+
+## Constructors
+
+### Constructor
+
+```ts
+new ChallengeService(configService): ChallengeService;
+```
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:40](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L40)
+
+#### Parameters
+
+| Parameter       | Type            |
+| --------------- | --------------- |
+| `configService` | `ConfigService` |
+
+#### Returns
+
+`ChallengeService`
+
+## Methods
+
+### create()
+
+```ts
+create(
+   userId,
+   methods,
+   preferredMethod?,
+   ipAddress?,
+   userAgent?,
+   location?,
+clientName?): Promise<IMfaChallengeState>;
+```
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L53)
+
+Issues a new MFA challenge for a user.
+
+#### Parameters
+
+| Parameter          | Type       |
+| ------------------ | ---------- |
+| `userId`           | `string`   |
+| `methods`          | `string`[] |
+| `preferredMethod?` | `string`   |
+| `ipAddress?`       | `string`   |
+| `userAgent?`       | `string`   |
+| `location?`        | `string`   |
+| `clientName?`      | `string`   |
+
+#### Returns
+
+`Promise`\<[`IMfaChallengeState`](Interface.IMfaChallengeState)\>
+
+---
+
+### get()
+
+```ts
+get(challengeId): Promise<IMfaChallengeState>;
+```
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:85](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L85)
+
+Retrieves an active challenge, throwing if invalid or expired.
+
+#### Parameters
+
+| Parameter     | Type     |
+| ------------- | -------- |
+| `challengeId` | `string` |
+
+#### Returns
+
+`Promise`\<[`IMfaChallengeState`](Interface.IMfaChallengeState)\>
+
+---
+
+### incrementAttempts()
+
+```ts
+incrementAttempts(challengeId): Promise<IMfaChallengeState>;
+```
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:102](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L102)
+
+Increments failed attempts and optionally invalidates the challenge.
+
+#### Parameters
+
+| Parameter     | Type     |
+| ------------- | -------- |
+| `challengeId` | `string` |
+
+#### Returns
+
+`Promise`\<[`IMfaChallengeState`](Interface.IMfaChallengeState)\>
+
+---
+
+### invalidate()
+
+```ts
+invalidate(challengeId): Promise<void>;
+```
+
+Defined in: [libs/platform-authentication/src/services/ChallengeService.ts:123](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/services/ChallengeService.ts#L123)
+
+Invalidates a challenge after successful verification.
+
+#### Parameters
+
+| Parameter     | Type     |
+| ------------- | -------- |
+| `challengeId` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>

package/data/packages/platform-authentication/api/Class.GithubAuthGuard.md

@@ -0,0 +1,45 @@
+---
+title: 'Class: GithubAuthGuard'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: GithubAuthGuard
+
+Defined in: [libs/platform-authentication/src/guards/GithubAuthGuard.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/guards/GithubAuthGuard.ts#L14)
+
+The `GithubAuthGuard` protects routes using GitHub authentication.
+
+## Extends
+
+- `IAuthGuard`
+
+## Constructors
+
+### Constructor
+
+```ts
+new GithubAuthGuard(...args): GithubAuthGuard;
+```
+
+Defined in: node_modules/@nestjs/passport/dist/interfaces/type.interface.d.ts:2
+
+#### Parameters
+
+| Parameter | Type    |
+| --------- | ------- |
+| ...`args` | `any`[] |
+
+#### Returns
+
+`GithubAuthGuard`
+
+#### Inherited from
+
+```ts
+AuthGuard('github').constructor;
+```

package/data/packages/platform-authentication/api/Class.JwtAuthGuard.md

@@ -0,0 +1,45 @@
+---
+title: 'Class: JwtAuthGuard'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# Class: JwtAuthGuard
+
+Defined in: [libs/platform-authentication/src/guards/JwtAuthGuard.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/guards/JwtAuthGuard.ts#L14)
+
+The `JwtAuthGuard` protects routes using JWT-based authentication.
+
+## Extends
+
+- `IAuthGuard`
+
+## Constructors
+
+### Constructor
+
+```ts
+new JwtAuthGuard(...args): JwtAuthGuard;
+```
+
+Defined in: node_modules/@nestjs/passport/dist/interfaces/type.interface.d.ts:2
+
+#### Parameters
+
+| Parameter | Type    |
+| --------- | ------- |
+| ...`args` | `any`[] |
+
+#### Returns
+
+`JwtAuthGuard`
+
+#### Inherited from
+
+```ts
+AuthGuard('jwt').constructor;
+```