@breadstone/archipel-mcp 0.0.11 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.11",
+  "version": "0.0.14",
   "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",

package/src/DocsLoader.js

@@ -11,11 +11,8 @@ const path = tslib_1.__importStar(require("node:path"));
  * (published npm package).
  */
 class DocsLoader {
-    constructor() {
-        // #region Fields
-        this._packages = new Map();
-        // #endregion
-    }
+    // #region Fields
+    _packages = new Map();
     // #endregion
     // #region Properties
     get packages() {

package/src/GuidesLoader.js

@@ -11,11 +11,8 @@ const path = tslib_1.__importStar(require("node:path"));
  * (published npm package).
  */
 class GuidesLoader {
-    constructor() {
-        // #region Fields
-        this._guides = new Map();
-        // #endregion
-    }
+    // #region Fields
+    _guides = new Map();
     // #endregion
     // #region Properties
     get guides() {

package/data/guides/ai-text-generation.md

@@ -1,361 +0,0 @@
----
-title: AI Text Generation
-description: Generate text completions with multi-provider support for OpenAI, Anthropic, Google Gemini, and Grok using a unified configuration layer.
-order: 15
----
-
-# AI Text Generation
-
-This guide covers text generation with `platform-intelligence`: choosing an AI provider, configuring the module, generating completions, registering custom capabilities, and building intent-based orchestration.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-intelligence
-```
-
-Install the AI SDK provider package for the model you want to use:
-
-| Provider       | Package             |
-| -------------- | ------------------- |
-| **OpenAI**     | `@ai-sdk/openai`    |
-| **Anthropic**  | `@ai-sdk/anthropic` |
-| **Google**     | `@ai-sdk/google`    |
-| **Grok (xAI)** | `@ai-sdk/openai`    |
-
-```bash
-# Example: OpenAI
-yarn add @ai-sdk/openai
-```
-
-> Grok uses the OpenAI-compatible endpoint, so it shares the `@ai-sdk/openai` package.
-
----
-
-## Module Registration
-
-Import `IntelligenceModule` into your application module. It exposes `IntelligenceTextGenerator` and `IntelligenceCapabilityRegistry` as shared providers.
-
-```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
-
-@Module({
-  imports: [IntelligenceModule],
-})
-export class AppModule {}
-```
-
----
-
-## Configuration
-
-All intelligence settings are read from environment variables via `ConfigService`. No direct `process.env` access is needed.
-
-```env
-INTELLIGENCE_PROVIDER=openai
-INTELLIGENCE_MODEL=gpt-4o-mini
-INTELLIGENCE_API_KEY=sk-...
-INTELLIGENCE_TEMPERATURE=0.7
-INTELLIGENCE_TOP_P=1
-INTELLIGENCE_MAX_OUTPUT_TOKENS=1024
-INTELLIGENCE_BASE_URL=              # optional — override for custom endpoints
-```
-
-### Supported Providers
-
-| `INTELLIGENCE_PROVIDER` | Default model              | Notes                              |
-| ----------------------- | -------------------------- | ---------------------------------- |
-| `openai`                | `gpt-4o-mini`              | OpenAI API                         |
-| `anthropic`             | `claude-sonnet-4-20250514` | Anthropic API                      |
-| `google`                | `gemini-2.0-flash`         | Google Gemini API                  |
-| `grok`                  | `grok-3-mini-fast`         | xAI Grok via OpenAI-compatible API |
-
-Each provider resolves its API key and base URL from dedicated environment variables when the generic `INTELLIGENCE_API_KEY` is not set:
-
-```env
-# Provider-specific keys (optional — fallback from INTELLIGENCE_API_KEY)
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_GENERATIVE_AI_API_KEY=AI...
-GROK_API_KEY=xai-...
-```
-
----
-
-## Generating Text
-
-Inject `IntelligenceTextGenerator` to generate completions:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { IntelligenceTextGenerator } from '@breadstone/archipel-platform-intelligence';
-import type { IIntelligencePrompt } from '@breadstone/archipel-platform-intelligence';
-
-@Injectable()
-export class SummaryService {
-  private readonly _textGenerator: IntelligenceTextGenerator;
-
-  constructor(textGenerator: IntelligenceTextGenerator) {
-    this._textGenerator = textGenerator;
-  }
-
-  public async summarize(content: string): Promise<string> {
-    const prompt: IIntelligencePrompt = {
-      systemPrompt: 'You are a concise summarizer. Respond with a short summary.',
-      messages: [{ role: 'user', content: content }],
-    };
-
-    const completion = await this._textGenerator.generateText(prompt);
-
-    return completion.text;
-  }
-}
-```
-
-### Prompt Structure
-
-A prompt consists of an optional system prompt and an ordered array of messages:
-
-```typescript
-interface IIntelligencePrompt {
-  readonly systemPrompt: string | null;
-  readonly messages: ReadonlyArray<IIntelligencePromptMessage>;
-}
-
-interface IIntelligencePromptMessage {
-  readonly role: 'user' | 'assistant' | 'system';
-  readonly content: string;
-}
-```
-
-### Per-Request Overrides
-
-Override generation parameters for individual requests without changing the global configuration:
-
-```typescript
-const completion = await this._textGenerator.generateText(prompt, {
-  temperature: 0.2, // more deterministic
-  maxOutputTokens: 256, // shorter responses
-});
-```
-
-### Completion Response
-
-The response includes the generated text, the provider/model used, and optional token usage telemetry:
-
-```typescript
-interface IIntelligenceTextCompletion {
-  readonly text: string;
-  readonly provider: string;
-  readonly model: string;
-  readonly usage: IIntelligenceCompletionUsage | null;
-}
-
-interface IIntelligenceCompletionUsage {
-  readonly promptTokens: number | null;
-  readonly completionTokens: number | null;
-  readonly totalTokens: number | null;
-}
-```
-
----
-
-## Multi-Turn Conversations
-
-Build multi-turn conversations by passing the full message history:
-
-```typescript
-const prompt: IIntelligencePrompt = {
-  systemPrompt: 'You are a helpful fitness coach.',
-  messages: [
-    { role: 'user', content: 'What should I eat before a workout?' },
-    { role: 'assistant', content: 'A balanced meal with carbs and protein about 2 hours before.' },
-    { role: 'user', content: 'Can you give me a specific example?' },
-  ],
-};
-
-const completion = await this._textGenerator.generateText(prompt);
-```
-
----
-
-## Capability System
-
-The intelligence module includes a capability registry that lets you build intent-based orchestration. Capabilities are domain-specific handlers that respond to classified user intents.
-
-### Defining a Capability
-
-Implement the `IIntelligenceCapability` interface:
-
-```typescript
-import type {
-  IIntelligenceCapability,
-  IIntelligenceCapabilityMetadata,
-  IIntelligenceCapabilityPayload,
-  IIntelligenceCapabilityResult,
-  IIntelligenceContext,
-  IIntelligenceIntent,
-} from '@breadstone/archipel-platform-intelligence';
-
-export class WorkoutRecommendationCapability implements IIntelligenceCapability {
-  public readonly metadata: IIntelligenceCapabilityMetadata = {
-    id: 'workout-recommendation',
-    name: 'Workout Recommendation',
-    description: 'Recommends workouts based on user preferences.',
-    priority: 10,
-    intentName: 'recommend_workout',
-  };
-
-  public canHandle(intent: IIntelligenceIntent, _context: IIntelligenceContext): boolean {
-    return intent.name === 'recommend_workout' && intent.confidence >= 0.7;
-  }
-
-  public async execute(payload: IIntelligenceCapabilityPayload): Promise<IIntelligenceCapabilityResult> {
-    // Use payload.intent, payload.context, payload.userMessage
-    return {
-      messages: [{ content: 'Here is your personalized workout plan...', metadata: null }],
-      artifacts: [],
-      followUps: [{ id: 'adjust', label: 'Adjust difficulty', payload: { action: 'adjust' } }],
-    };
-  }
-}
-```
-
-### Registering Capabilities
-
-Use `IntelligenceCapabilityRegistrarBase` to auto-register capabilities when a module initializes:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import {
-  IntelligenceCapabilityRegistrarBase,
-  IntelligenceCapabilityRegistry,
-} from '@breadstone/archipel-platform-intelligence';
-import type { IIntelligenceCapability } from '@breadstone/archipel-platform-intelligence';
-
-@Injectable()
-export class WorkoutCapabilityRegistrar extends IntelligenceCapabilityRegistrarBase {
-  constructor(registry: IntelligenceCapabilityRegistry) {
-    super(registry);
-  }
-
-  protected getCapabilities(): ReadonlyArray<IIntelligenceCapability> {
-    return [new WorkoutRecommendationCapability()];
-  }
-}
-```
-
-Register the registrar as a provider in your feature module:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { IntelligenceModule } from '@breadstone/archipel-platform-intelligence';
-
-@Module({
-  imports: [IntelligenceModule],
-  providers: [WorkoutCapabilityRegistrar],
-})
-export class WorkoutModule {}
-```
-
-### Resolving Capabilities at Runtime
-
-Use the registry to find the best-matching capability for a classified intent:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { IntelligenceCapabilityRegistry } from '@breadstone/archipel-platform-intelligence';
-import type {
-  IIntelligenceCapabilityResult,
-  IIntelligenceContext,
-  IIntelligenceIntent,
-} from '@breadstone/archipel-platform-intelligence';
-
-@Injectable()
-export class ChatOrchestrator {
-  private readonly _registry: IntelligenceCapabilityRegistry;
-
-  constructor(registry: IntelligenceCapabilityRegistry) {
-    this._registry = registry;
-  }
-
-  public async handle(
-    intent: IIntelligenceIntent,
-    context: IIntelligenceContext,
-    userMessage: string,
-  ): Promise<IIntelligenceCapabilityResult | null> {
-    const capability = this._registry.resolve(intent, context);
-    if (!capability) {
-      return null; // No matching capability — fall back to generic response
-    }
-
-    return capability.execute({ intent, context, userMessage });
-  }
-}
-```
-
-Capabilities are resolved by priority (lowest number first). If multiple capabilities can handle the same intent, the one with the highest priority (lowest value) wins.
-
----
-
-## Inspecting Configuration
-
-Retrieve the resolved provider configuration at runtime:
-
-```typescript
-const config = this._textGenerator.getConfiguration();
-console.log(config.provider); // 'openai'
-console.log(config.model); // 'gpt-4o-mini'
-```
-
----
-
-## Error Handling
-
-`IntelligenceTextGenerator` logs errors via the NestJS `Logger` and re-throws them. Wrap calls in try/catch to handle provider failures gracefully:
-
-```typescript
-try {
-  const result = await this._textGenerator.generateText(prompt);
-  return result.text;
-} catch (error) {
-  // Handle rate limits, network errors, invalid API keys, etc.
-  this._logger.error(`Text generation failed: ${(error as Error).message}`);
-  return 'Sorry, I could not generate a response right now.';
-}
-```
-
-If an AI SDK provider package is not installed, the error message clearly states which package is missing.
-
----
-
-## Architecture Overview
-
-```
-┌────────────────────────────────────┐
-│         IntelligenceModule         │
-│                                    │
-│  ┌──────────────────────────────┐  │
-│  │  IntelligenceTextGenerator   │──┼── generateText(prompt, options?)
-│  │  (ConfigService → provider)  │  │
-│  └──────────────────────────────┘  │
-│                                    │
-│  ┌──────────────────────────────┐  │
-│  │  IntelligenceCapability      │──┼── resolve(intent, context)
-│  │  Registry                    │  │   register(capability)
-│  └──────────────────────────────┘  │
-└────────────────────────────────────┘
-         │                │
-         ▼                ▼
-  ┌─────────────┐  ┌──────────────┐
-  │ Provider     │  │ Feature      │
-  │ Loaders      │  │ Capabilities │
-  │ (OpenAI,     │  │ (custom      │
-  │  Anthropic,  │  │  handlers)   │
-  │  Google,     │  │              │
-  │  Grok)       │  │              │
-  └─────────────┘  └──────────────┘
-```

package/data/guides/analytics-and-error-tracking.md

@@ -1,189 +0,0 @@
----
-title: Analytics & Error Tracking
-description: Capture errors, messages, and user context with Sentry, Application Insights, Datadog, or a custom provider.
-order: 14
----
-
-# Analytics & Error Tracking
-
-This guide covers error tracking and analytics with `platform-analytics`: choosing a provider, capturing exceptions, recording breadcrumbs, and setting user context.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-analytics
-```
-
----
-
-## Choose a Provider
-
-`platform-analytics` abstracts error tracking and analytics behind an `AnalyticsClientPort`. Supported providers:
-
-| Provider                 | When to use                                  |
-| ------------------------ | -------------------------------------------- |
-| **Sentry**               | Full-featured error tracking and performance |
-| **Application Insights** | Azure-native monitoring                      |
-| **Datadog**              | Infrastructure + APM monitoring              |
-| **Noop**                 | Development / testing — discards all events  |
-
----
-
-## Module Registration
-
-```typescript
-import { Module } from '@nestjs/common';
-import { AnalyticsModule } from '@breadstone/archipel-platform-analytics';
-import { SentryAnalyticsClient } from './adapters/SentryAnalyticsClient';
-import { SENTRY_CONFIG_ENTRIES } from './env';
-
-@Module({
-  imports: [
-    AnalyticsModule.register({
-      analyticsClient: SentryAnalyticsClient,
-      configEntries: [...SENTRY_CONFIG_ENTRIES],
-      isGlobal: true,
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Implementing the Client Port
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import {
-  AnalyticsClientPort,
-  AnalyticsLevel,
-  type IAnalyticsUser,
-  type IAnalyticsBreadcrumb,
-} from '@breadstone/archipel-platform-analytics';
-import * as Sentry from '@sentry/node';
-
-@Injectable()
-export class SentryAnalyticsClient extends AnalyticsClientPort {
-  public captureException(error: Error, context?: Record<string, unknown>): void {
-    Sentry.captureException(error, { extra: context });
-  }
-
-  public captureMessage(message: string, level: AnalyticsLevel): void {
-    Sentry.captureMessage(message, level);
-  }
-
-  public setUser(user: IAnalyticsUser): void {
-    Sentry.setUser({ id: user.id, email: user.email });
-  }
-
-  public addBreadcrumb(breadcrumb: IAnalyticsBreadcrumb): void {
-    Sentry.addBreadcrumb({
-      category: breadcrumb.category,
-      message: breadcrumb.message,
-      level: breadcrumb.level,
-      data: breadcrumb.data,
-    });
-  }
-}
-```
-
----
-
-## Capturing Errors
-
-Inject `AnalyticsClientPort` to capture exceptions with full context:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
-
-@Injectable()
-export class PaymentService {
-  private readonly _analytics: AnalyticsClientPort;
-
-  constructor(analytics: AnalyticsClientPort) {
-    this._analytics = analytics;
-  }
-
-  public async processPayment(orderId: string): Promise<void> {
-    try {
-      // ... payment logic
-    } catch (error) {
-      this._analytics.captureException(error as Error, {
-        orderId,
-        action: 'processPayment',
-      });
-      throw error;
-    }
-  }
-}
-```
-
----
-
-## User Context
-
-Set user context early in the request lifecycle (e.g., via a middleware or interceptor) so all captured events include user information:
-
-```typescript
-import { Injectable, NestMiddleware } from '@nestjs/common';
-import { Request, Response, NextFunction } from 'express';
-import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
-import type { IAuthSubject } from '@breadstone/archipel-platform-authentication';
-
-@Injectable()
-export class AnalyticsUserMiddleware implements NestMiddleware {
-  private readonly _analytics: AnalyticsClientPort;
-
-  constructor(analytics: AnalyticsClientPort) {
-    this._analytics = analytics;
-  }
-
-  public use(req: Request, _res: Response, next: NextFunction): void {
-    const user = req.user as IAuthSubject | undefined;
-
-    if (user) {
-      this._analytics.setUser({
-        id: user.id,
-        email: user.email ?? undefined,
-      });
-    }
-
-    next();
-  }
-}
-```
-
----
-
-## Breadcrumbs
-
-Breadcrumbs are a trail of events leading up to an error. They help you understand what happened before a crash:
-
-```typescript
-this._analytics.addBreadcrumb({
-  category: 'payment',
-  message: 'Checkout session created',
-  level: 'info',
-  data: { orderId, provider: 'stripe' },
-});
-```
-
----
-
-## Development Tips
-
-- Use the **Noop** provider during local development and testing to avoid sending events to production analytics.
-- Set `isGlobal: true` in the module registration so `AnalyticsClientPort` is available everywhere without re-importing.
-- Combine with `platform-telemetry` for metrics. Use analytics for error tracking and telemetry for performance monitoring.
-- Map domain errors to known categories in your analytics context to group related issues.
-
----
-
-## Next Steps
-
-- See the [Telemetry & Observability](/guides/telemetry-and-observability) guide for metrics and tracing
-- Browse the [platform-analytics API reference](/packages/platform-analytics/api/) for complete method signatures