@breadstone/archipel-mcp 0.0.17 → 0.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/data/guides/openapi-and-feature-discovery.md +20 -12
  2. package/data/packages/platform-caching/index.md +8 -5
  3. package/data/packages/platform-cryptography/index.md +6 -8
  4. package/data/packages/platform-logging/index.md +18 -46
  5. package/data/packages/platform-openapi/api/Function.Api.md +3 -14
  6. package/data/packages/platform-openapi/api/index.md +1 -1
  7. package/data/packages/platform-openapi/index.md +78 -43
  8. package/package.json +1 -1
package/data/guides/openapi-and-feature-discovery.md CHANGED
@@ -149,18 +149,26 @@ export class TipController {
149
149
 
150
150
  ### `@Api()` Options Reference
151
151
 
152
- | Option | Type | Description |
153
- | ------------ | --------------------------------------------- | ---------------------------------------------------- |
154
- | `auth` | `'bearer' \| 'basic' \| 'oauth2' \| 'cookie'` | Adds the corresponding auth decorator. |
155
- | `tags` | `string \| string[]` | OpenAPI tag(s) for the operation. |
156
- | `operation` | `ApiOperationOptions` | Summary, description, deprecation flag, etc. |
157
- | `responses` | `ApiResponseOptions \| ApiResponseOptions[]` | One or more response definitions. |
158
- | `headers` | `ApiHeaderOptions[]` | Expected request headers. |
159
- | `params` | `ApiParamOptions \| ApiParamOptions[]` | Path parameter definitions. |
160
- | `query` | `ApiQueryOptions \| ApiQueryOptions[]` | Query parameter definitions. |
161
- | `body` | `ApiBodyOptions` | Request body definition. |
162
- | `scopes` | `string[]` | OAuth2 scopes (only relevant when `auth: 'oauth2'`). |
163
- | `extensions` | `Record<string, string \| number \| boolean>` | Custom OpenAPI extension properties (`x-*`). |
152
+ | Option | Type | Description |
153
+ | ------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
154
+ | `auth` | `ApiAuthOption \| ApiAuthOption[]` | Auth scheme(s). Simple string (`'bearer'`) or named (`{ type: 'bearer', name: 'jwt' }`). Supports multiple simultaneous schemes. |
155
+ | `tags` | `string \| string[]` | OpenAPI tag(s) for the operation. |
156
+ | `operation` | `ApiOperationOptions` | Summary, description, operationId, deprecation flag, etc. |
157
+ | `summary` | `string` | Shorthand for `operation.summary`. Takes precedence when both are set. |
158
+ | `deprecated` | `boolean` | Shorthand to mark the endpoint as deprecated. Merged into `operation`. |
159
+ | `responses` | `ApiResponseOptions \| ApiResponseOptions[]` | One or more response definitions. |
160
+ | `headers` | `ApiHeaderOptions[]` | Expected request headers. |
161
+ | `params` | `ApiParamOptions \| ApiParamOptions[]` | Path parameter definitions. |
162
+ | `query` | `ApiQueryOptions \| ApiQueryOptions[]` | Query parameter definitions. |
163
+ | `body` | `ApiBodyOptions` | Request body definition. |
164
+ | `scopes` | `string[]` | OAuth2 scopes (only relevant when `auth` includes `'oauth2'`). |
165
+ | `extensions` | `Record<string, unknown>` | Custom OpenAPI extension properties (`x-*`). |
166
+ | `consumes` | `string \| string[]` | MIME type(s) the endpoint consumes (e.g. `'multipart/form-data'`). |
167
+ | `produces` | `string \| string[]` | MIME type(s) the endpoint produces (e.g. `'application/pdf'`). |
168
+ | `extraModels`| `Function \| Function[]` | Extra model classes for polymorphic / discriminated-union schemas. |
169
+ | `security` | `IApiSecurityOption \| IApiSecurityOption[]` | Generic security scheme(s) for custom API keys or non-standard auth. |
170
+ | `exclude` | `boolean` | Excludes this endpoint from the Swagger documentation when `true`. |
171
+ | `callbacks` | `ApiCallbacksOptions` | OpenAPI callback / webhook definitions. |
164
172
 
165
173
  ---
166
174
 
package/data/packages/platform-caching/index.md CHANGED
@@ -32,7 +32,9 @@ For Redis-backed caching:
32
32
  import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';
33
33
 
34
34
  const cache = new RedisLayeredCache<string, IProduct>(redisClient, async (key) => productRepository.findById(key), {
35
- ttlMs: 300_000,
35
+ url: 'redis://localhost:6379',
36
+ keyPrefix: 'products:',
37
+ ttlSeconds: 300,
36
38
  cacheName: 'products',
37
39
  });
38
40
  ```
@@ -72,12 +74,13 @@ Both implementations share this contract:
72
74
 
73
75
  | Property | Type | Default | Description |
74
76
  | ---------------------- | ----------------------- | ---------------- | ------------------------------------------------------- |
75
- | `ttlMs` | `number` | ∞ | Time-to-live in milliseconds. |
76
- | `staleWhileRevalidate` | `boolean` | `false` | Serve stale entries while refreshing in the background. |
77
- | `metricsRecorder` | `ICacheMetricsRecorder` | Noop | Pluggable metrics hook. |
78
- | `cacheName` | `string` | `'redis'` | Label used in metrics and logging. |
77
+ | `url` | `string` | — | Redis connection URL (e.g. `redis://localhost:6379`). |
78
+ | `keyPrefix` | `string` | — | Key prefix applied to all Redis keys. |
79
+ | `ttlSeconds` | `number` | ∞ | Time-to-live in seconds. |
79
80
  | `serialize` | `(value) => string` | `JSON.stringify` | Custom serializer for cache values. |
80
81
  | `deserialize` | `(raw) => value` | `JSON.parse` | Custom deserializer for cache entries. |
82
+ | `metricsRecorder` | `ICacheMetricsRecorder` | Noop | Pluggable metrics hook. |
83
+ | `cacheName` | `string` | `'redis'` | Label used in metrics and logging. |
81
84
 
82
85
  ---
83
86
 
package/data/packages/platform-cryptography/index.md CHANGED
@@ -15,12 +15,10 @@ Cryptographic building blocks for NestJS applications: bcrypt password hashing,
15
15
  ## Quick Start
16
16
 
17
17
  ```typescript
18
- import {
19
- BcryptService,
20
- CryptoService,
21
- OtpService,
22
- OTP_SERVICE_TOKEN,
23
- } from '@breadstone/archipel-platform-cryptography';
18
+ import { BcryptService, CryptoService } from '@breadstone/archipel-platform-cryptography';
19
+
20
+ // OTP is a tree-shakable sub-export
21
+ import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';
24
22
  ```
25
23
 
26
24
  ---
@@ -83,7 +81,7 @@ TOTP enrollment and verification backed by otplib v13, injected via the `OTP_SER
83
81
 
84
82
  ```typescript
85
83
  import { Module } from '@nestjs/common';
86
- import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography';
84
+ import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';
87
85
 
88
86
  @Module({
89
87
  providers: [{ provide: OTP_SERVICE_TOKEN, useClass: OtpService }],
@@ -96,7 +94,7 @@ export class SecurityModule {}
96
94
 
97
95
  ```typescript
98
96
  import { Inject, Injectable } from '@nestjs/common';
99
- import { OTP_SERVICE_TOKEN, IOtpService } from '@breadstone/archipel-platform-cryptography';
97
+ import { OTP_SERVICE_TOKEN, IOtpService } from '@breadstone/archipel-platform-cryptography/otp';
100
98
 
101
99
  @Injectable()
102
100
  export class MfaService {
package/data/packages/platform-logging/index.md CHANGED
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  title: platform-logging
3
- description: Sentry integration for error tracking and analytics.
3
+ description: Configurable logging module for NestJS with log-level management.
4
4
  order: 6
5
- tags: [logging, sentry, error-tracking, analytics]
5
+ tags: [logging, log-level, nestjs]
6
6
  package: '@breadstone/archipel-platform-logging'
7
7
  ---
8
8
 
9
9
  # platform-logging
10
10
 
11
- Sentry integration for centralized error tracking and analytics. Provides structured error reporting with context enrichment.
11
+ Configurable logging module for NestJS applications with application-wide log-level management. Wraps the built-in NestJS `Logger` and configures it via the central `ConfigModule`.
12
12
 
13
13
  **Package:** `@breadstone/archipel-platform-logging`
14
14
 
@@ -24,28 +24,24 @@ import { LoggerModule } from '@breadstone/archipel-platform-logging';
24
24
  export class AppModule {}
25
25
  ```
26
26
 
27
+ The module is `@Global()` — once imported, `Logger` is available for injection across the entire application.
28
+
27
29
  ---
28
30
 
29
- ## AnalyticsService
31
+ ## Using the Logger
30
32
 
31
- Central service for error and event reporting to Sentry.
33
+ Inject the standard NestJS `Logger` provided by `LoggerModule`:
32
34
 
33
35
  ```typescript
34
- import { AnalyticsService } from '@breadstone/archipel-platform-logging';
36
+ import { Injectable, Logger } from '@nestjs/common';
35
37
 
36
38
  @Injectable()
37
39
  export class PaymentService {
38
- constructor(private readonly _analytics: AnalyticsService) {}
40
+ constructor(private readonly _logger: Logger) {}
39
41
 
40
42
  public async processPayment(orderId: string): Promise<void> {
41
- try {
42
- // ... payment logic
43
- } catch (error) {
44
- this._analytics.captureException(error, {
45
- tags: { module: 'payments', orderId },
46
- });
47
- throw error;
48
- }
43
+ this._logger.log(`Processing payment for order ${orderId}`);
44
+ // ...
49
45
  }
50
46
  }
51
47
  ```
@@ -54,39 +50,15 @@ export class PaymentService {
54
50
 
55
51
  ## Environment Variables
56
52
 
57
- | Variable | Description | Required |
58
- | --------------------------- | ---------------------------------------------------- | -------- |
59
- | `SENTRY_DSN` | Sentry Data Source Name | Yes |
60
- | `SENTRY_ENVIRONMENT` | Environment label (e.g. `'production'`, `'staging'`) | No |
61
- | `SENTRY_TRACES_SAMPLE_RATE` | Sampling rate for performance traces (0.0–1.0) | No |
62
-
63
- ---
64
-
65
- ## Real-World Example: Global Error Filter
66
-
67
- ```typescript
68
- import { Catch, type ExceptionFilter, type ArgumentsHost } from '@nestjs/common';
69
- import { AnalyticsService } from '@breadstone/archipel-platform-logging';
70
-
71
- @Catch()
72
- export class GlobalExceptionFilter implements ExceptionFilter {
73
- constructor(private readonly _analytics: AnalyticsService) {}
74
-
75
- public catch(exception: unknown, host: ArgumentsHost): void {
76
- this._analytics.captureException(exception);
77
-
78
- const ctx = host.switchToHttp();
79
- const response = ctx.getResponse();
80
- response.status(500).json({ error: 'Internal Server Error' });
81
- }
82
- }
83
- ```
53
+ | Variable | Description | Required | Default |
54
+ | --------------- | -------------------------------------------------------------- | -------- | ------- |
55
+ | `APP_LOG_LEVEL` | Application log level (`'debug'`, `'info'`, `'warn'`, `'error'`) | No | `warn` |
84
56
 
85
57
  ---
86
58
 
87
59
  ## Exports Summary
88
60
 
89
- | Export | Type | Description |
90
- | ------------------ | ------------- | -------------------------------- |
91
- | `LoggerModule` | NestJS Module | Global Sentry integration |
92
- | `AnalyticsService` | Service | Error capture and event tracking |
61
+ | Export | Type | Description |
62
+ | -------------- | ------------- | -------------------------------------------- |
63
+ | `LoggerModule` | NestJS Module | Global logging module with log-level control |
64
+ | `Logger` | Provider | NestJS Logger configured with `APP_LOG_LEVEL`|
package/data/packages/platform-openapi/api/Function.Api.md CHANGED
@@ -9,26 +9,15 @@ editUrl: false
9
9
  function Api(options): ClassDecorator & MethodDecorator & PropertyDecorator;
10
10
  ```
11
11
 
12
- Defined in: [decorators/Api.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-openapi/src/decorators/Api.ts#L21)
12
+ Defined in: [decorators/Api.ts:141](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-openapi/src/decorators/Api.ts#L141)
13
13
 
14
- Custom Swagger Decorator
15
- This decorator wraps all necessary Swagger decorators into one.
14
+ Composite Swagger decorator that wraps all NestJS OpenAPI decorators into a single declaration.
16
15
 
17
16
  ## Parameters
18
17
 
19
18
  | Parameter | Type | Description |
20
19
  | ------ | ------ | ------ |
21
- | `options` | \{ `auth?`: `"bearer"` \| `"basic"` \| `"oauth2"` \| `"cookie"`; `body?`: `ApiBodyOptions`; `extensions?`: `Record`\<`string`, `string` \| `number` \| `boolean`\>; `headers?`: `ApiHeaderOptions`[]; `operation?`: `Partial`\<`OperationObject`\>; `params?`: `ApiParamOptions` \| `ApiParamOptions`[]; `query?`: `ApiQueryOptions` \| `ApiQueryOptions`[]; `responses?`: `ApiResponseOptions` \| `ApiResponseOptions`[]; `scopes?`: `string`[]; `tags?`: `string` \| `string`[]; \} | Configuration for the Swagger decorators. |
22
- | `options.auth?` | `"bearer"` \| `"basic"` \| `"oauth2"` \| `"cookie"` | - |
23
- | `options.body?` | `ApiBodyOptions` | Options for the ApiBody decorator. |
24
- | `options.extensions?` | `Record`\<`string`, `string` \| `number` \| `boolean`\> | - |
25
- | `options.headers?` | `ApiHeaderOptions`[] | Options for the ApiHeaders decorator. |
26
- | `options.operation?` | `Partial`\<`OperationObject`\> | Options for the ApiOperation decorator. |
27
- | `options.params?` | `ApiParamOptions` \| `ApiParamOptions`[] | Options for the ApiParam decorator. |
28
- | `options.query?` | `ApiQueryOptions` \| `ApiQueryOptions`[] | Options for the ApiQuery decorator (can be an array or single query). |
29
- | `options.responses?` | `ApiResponseOptions` \| `ApiResponseOptions`[] | - |
30
- | `options.scopes?` | `string`[] | - |
31
- | `options.tags?` | `string` \| `string`[] | Options for the ApiTags decorator (can be an array or single tag). |
20
+ | `options` | `IApiOptions` | Configuration for the Swagger decorators. |
32
21
 
33
22
  ## Returns
34
23
 
package/data/packages/platform-openapi/api/index.md CHANGED
@@ -36,7 +36,7 @@ editUrl: false
36
36
 
37
37
  | Function | Description |
38
38
  | ------ | ------ |
39
- | [Api](Function.Api) | Custom Swagger Decorator This decorator wraps all necessary Swagger decorators into one. |
39
+ | [Api](Function.Api) | Composite Swagger decorator that wraps all NestJS OpenAPI decorators into a single declaration. |
40
40
  | [getRegisteredSwaggerFeatures](Function.getRegisteredSwaggerFeatures) | Retrieves all Swagger features that have been registered through the decorator. |
41
41
  | [getSwaggerFeatureMetadata](Function.getSwaggerFeatureMetadata) | Get the Swagger feature metadata from a module class |
42
42
  | [SwaggerFeature](Function.SwaggerFeature) | Decorator to register a module as a Swagger feature. This allows the SwaggerMultiDocumentService to automatically discover and create documentation. |
package/data/packages/platform-openapi/index.md CHANGED
@@ -15,19 +15,27 @@ Multi-tenant Swagger/OpenAPI documentation system with feature-scoped discovery,
15
15
  ## Quick Start
16
16
 
17
17
  ```typescript
18
- import { Module } from '@nestjs/common';
18
+ import { Module, Controller, Get, Param } from '@nestjs/common';
19
19
  import { SwaggerFeature, Api } from '@breadstone/archipel-platform-openapi';
20
20
 
21
21
  @SwaggerFeature({
22
- name: 'User Management',
23
- description: 'User CRUD and profile operations',
24
- version: '1.0',
22
+ name: 'users',
23
+ title: 'My App API — Users',
24
+ description: 'User CRUD and profile operations.',
25
+ tag: 'Users',
26
+ tags: ['Users'],
25
27
  })
28
+ @Module({
29
+ controllers: [UserController],
30
+ })
31
+ export class UserModule {}
32
+
26
33
  @Controller('api/v1/users')
27
34
  export class UserController {
28
35
  @Api({
36
+ tags: 'Users',
29
37
  summary: 'Get user by ID',
30
- responses: { 200: { description: 'User found' } },
38
+ responses: [{ status: 200, description: 'User found', type: UserResponse }],
31
39
  })
32
40
  @Get(':id')
33
41
  public async getUser(@Param('id') id: string): Promise<UserResponse> {
@@ -44,21 +52,22 @@ The key concept is **per-feature Swagger documents** — each feature or module
44
52
 
45
53
  ### @SwaggerFeature Decorator
46
54
 
47
- Associates a controller with a named feature group:
55
+ Associates a module with a named feature group:
48
56
 
49
57
  ```typescript
50
58
  import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';
51
59
 
52
60
  @SwaggerFeature({
53
- name: 'Orders',
54
- description: 'Order management and fulfillment',
55
- version: '2.0',
56
- tags: ['orders', 'fulfillment'],
61
+ name: 'orders',
62
+ title: 'My App API — Orders',
63
+ description: 'Order management and fulfillment.',
64
+ tag: 'Orders',
65
+ tags: ['Orders'],
57
66
  })
58
- @Controller('api/v1/orders')
59
- export class OrderController {
60
- /* ... */
61
- }
67
+ @Module({
68
+ controllers: [OrderController],
69
+ })
70
+ export class OrderModule {}
62
71
  ```
63
72
 
64
73
  ### @Api Decorator
@@ -70,12 +79,12 @@ import { Api } from '@breadstone/archipel-platform-openapi';
70
79
 
71
80
  @Api({
72
81
  summary: 'Create a new order',
73
- description: 'Creates an order and initiates payment processing.',
74
- responses: {
75
- 201: { description: 'Order created successfully' },
76
- 400: { description: 'Invalid order data' },
77
- 402: { description: 'Payment required' },
78
- },
82
+ operation: { description: 'Creates an order and initiates payment processing.' },
83
+ responses: [
84
+ { status: 201, description: 'Order created successfully' },
85
+ { status: 400, description: 'Invalid order data' },
86
+ { status: 402, description: 'Payment required' },
87
+ ],
79
88
  })
80
89
  @Post()
81
90
  public async createOrder(@Body() body: CreateOrderDto): Promise<OrderResponse> { /* ... */ }
@@ -104,20 +113,37 @@ export class DocsController {
104
113
  ### Bootstrap Setup
105
114
 
106
115
  ```typescript
107
- import { SwaggerModule } from '@nestjs/swagger';
108
- import { SwaggerMultiDocumentService, SwaggerTheme } from '@breadstone/archipel-platform-openapi';
116
+ import {
117
+ SwaggerFeatureDiscovery,
118
+ SwaggerFeatureRegistry,
119
+ SwaggerMultiDocumentService,
120
+ } from '@breadstone/archipel-platform-openapi';
121
+ import { ConfigService, ContentTemplateEngine, HostService, ResourceManager } from '@breadstone/archipel-platform-core';
109
122
 
110
123
  async function bootstrap(): Promise<void> {
111
124
  const app = await NestFactory.create(AppModule);
112
- const docsService = app.get(SwaggerMultiDocumentService);
113
- const documents = docsService.generateAll();
114
-
115
- for (const [featureName, spec] of documents) {
116
- const path = `docs/${featureName.toLowerCase().replace(/\s+/g, '-')}`;
117
- SwaggerModule.setup(path, app, spec, {
118
- customCss: SwaggerTheme.getDefaultCss(),
119
- });
120
- }
125
+
126
+ const configService = app.get(ConfigService);
127
+ const hostService = app.get(HostService);
128
+ const resourceManager = app.get(ResourceManager);
129
+ const contentTemplateEngine = app.get(ContentTemplateEngine);
130
+
131
+ // 1. Discover features
132
+ const featureRegistry = new SwaggerFeatureRegistry();
133
+ const discovery = new SwaggerFeatureDiscovery();
134
+ discovery.registerDiscoveredFeatures(featureRegistry);
135
+ discovery.registerDefaultFeatures(featureRegistry);
136
+
137
+ // 2. Setup multi-document Swagger UI
138
+ const swaggerService = new SwaggerMultiDocumentService(
139
+ app,
140
+ configService,
141
+ hostService,
142
+ featureRegistry,
143
+ resourceManager,
144
+ contentTemplateEngine,
145
+ );
146
+ await swaggerService.setupMultipleSwaggerDocuments();
121
147
 
122
148
  await app.listen(3000);
123
149
  }
@@ -129,30 +155,39 @@ async function bootstrap(): Promise<void> {
129
155
 
130
156
  ### SwaggerFeatureDiscovery
131
157
 
132
- Auto-discovers all `@SwaggerFeature` decorated controllers at bootstrap:
158
+ Reads the global store populated by `@SwaggerFeature()` decorators and registers features into a `SwaggerFeatureRegistry`:
133
159
 
134
160
  ```typescript
135
- import { SwaggerFeatureDiscovery } from '@breadstone/archipel-platform-openapi';
161
+ import { SwaggerFeatureDiscovery, SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';
162
+
163
+ const featureRegistry = new SwaggerFeatureRegistry();
164
+ const discovery = new SwaggerFeatureDiscovery();
136
165
 
137
- const discovery = app.get(SwaggerFeatureDiscovery);
138
- const features = discovery.discoverAll();
139
- // → [{ name: 'User Management', controllers: [...] }, ...]
166
+ discovery
167
+ .registerDiscoveredFeatures(featureRegistry)
168
+ .registerDefaultFeatures(featureRegistry);
140
169
  ```
141
170
 
142
171
  ### SwaggerFeatureRegistry
143
172
 
144
- Programmatic registry for feature configurations:
173
+ Holds the finalized, immutable list of features. After all features are registered, call `finalize()`:
145
174
 
146
175
  ```typescript
147
176
  import { SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';
148
177
 
149
- const registry = app.get(SwaggerFeatureRegistry);
150
- registry.register({
151
- name: 'Admin',
152
- description: 'Admin-only endpoints',
153
- version: '1.0',
154
- controllers: [AdminController],
178
+ const registry = new SwaggerFeatureRegistry();
179
+
180
+ registry.registerFeature({
181
+ name: 'admin',
182
+ title: 'My App API — Admin',
183
+ description: 'Admin-only endpoints.',
184
+ tag: 'Admin',
185
+ tags: ['Admin'],
186
+ path: 'docs/admin',
155
187
  });
188
+
189
+ registry.finalize();
190
+ const features = registry.getFeatures(); // sorted, read-only copy
156
191
  ```
157
192
 
158
193
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@breadstone/archipel-mcp",
3
- "version": "0.0.17",
3
+ "version": "0.0.18",
4
4
  "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
5
5
  "type": "commonjs",
6
6
  "main": "./src/main.js",