cognitive-core 0.0.2 → 0.1.0

package/src/mcp/playbook-server.ts

@@ -0,0 +1,565 @@
+/**
+ * MCP Playbook Server
+ * Exposes playbook retrieval via Model Context Protocol
+ *
+ * @deprecated This module is deprecated in favor of the CLI interface and SKILL.md approach.
+ * See /SKILL.md for instructions on how agents should interact with cognitive-core.
+ * Use the CLI at bin/cognitive-core instead of this MCP server.
+ *
+ * This server provides on-demand access to the full playbook library,
+ * allowing agents to search for specific guidance beyond what's in their
+ * system prompt.
+ */
+
+import type { Playbook } from '../types/index.js';
+import type { PlaybookLibrary, PlaybookMatch } from '../memory/playbook.js';
+import type { SkillLibrary } from '../surfacing/skill-library.js';
+import type { MCPServerConfig } from '../types/config.js';
+import {
+  validateMCPArgs,
+  MCPSearchPlaybooksSchema,
+  MCPGetPlaybookDetailsSchema,
+  MCPGetPlaybooksByDomainSchema,
+} from '../utils/validation.js';
+
+/**
+ * MCP Tool definition
+ */
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+/**
+ * MCP Tool call request
+ */
+export interface MCPToolCall {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * MCP Tool call result
+ */
+export interface MCPToolResult {
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+  isError?: boolean;
+}
+
+/**
+ * Search result for MCP
+ */
+export interface PlaybookSearchResult {
+  id: string;
+  name: string;
+  confidence: number;
+  matchScore: number;
+  matchType: string;
+  strategy: string;
+  tactics: string[];
+  successRate: number;
+  domains: string[];
+}
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: MCPServerConfig = {
+  enabled: true,
+  exposeResources: true,
+  exposeTools: true,
+  maxResults: 5,
+  minConfidence: 0.3,
+  includeRefinements: true,
+  enableDomainFiltering: true,
+};
+
+/**
+ * MCP Playbook Server
+ * Provides playbook search tools for agents
+ */
+export class PlaybookMCPServer {
+  private playbooks: PlaybookLibrary;
+  private config: MCPServerConfig;
+
+  constructor(
+    playbooks: PlaybookLibrary,
+    _skillLibrary?: SkillLibrary,
+    config?: Partial<MCPServerConfig>
+  ) {
+    this.playbooks = playbooks;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Get available MCP tools
+   */
+  getTools(): MCPTool[] {
+    return [
+      {
+        name: 'search_playbooks',
+        description:
+          'Search for playbooks that provide guidance for solving a problem. ' +
+          'Returns strategies, tactics, and success indicators for matching playbooks.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: {
+              type: 'string',
+              description: 'Description of the problem or task to find playbooks for',
+            },
+            domain: {
+              type: 'string',
+              description: 'Optional domain to filter results (e.g., "code", "testing", "refactoring")',
+            },
+            maxResults: {
+              type: 'number',
+              description: 'Maximum number of playbooks to return (default: 5)',
+            },
+          },
+          required: ['query'],
+        },
+      },
+      {
+        name: 'get_playbook_details',
+        description:
+          'Get detailed information about a specific playbook by ID, ' +
+          'including full tactics, steps, refinements, and usage statistics.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            playbookId: {
+              type: 'string',
+              description: 'The ID of the playbook to retrieve',
+            },
+          },
+          required: ['playbookId'],
+        },
+      },
+      {
+        name: 'list_domains',
+        description: 'List all domains that have playbooks available.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'get_playbooks_by_domain',
+        description: 'Get all playbooks for a specific domain.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            domain: {
+              type: 'string',
+              description: 'The domain to get playbooks for',
+            },
+            maxResults: {
+              type: 'number',
+              description: 'Maximum number of playbooks to return (default: 10)',
+            },
+          },
+          required: ['domain'],
+        },
+      },
+    ];
+  }
+
+  /**
+   * Handle an MCP tool call
+   */
+  async handleToolCall(call: MCPToolCall): Promise<MCPToolResult> {
+    try {
+      switch (call.name) {
+        case 'search_playbooks':
+          return await this.handleSearchPlaybooks(call.arguments);
+        case 'get_playbook_details':
+          return await this.handleGetPlaybookDetails(call.arguments);
+        case 'list_domains':
+          return await this.handleListDomains();
+        case 'get_playbooks_by_domain':
+          return await this.handleGetPlaybooksByDomain(call.arguments);
+        default:
+          return {
+            content: [{ type: 'text', text: `Unknown tool: ${call.name}` }],
+            isError: true,
+          };
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  /**
+   * Handle search_playbooks tool call
+   */
+  private async handleSearchPlaybooks(
+    args: Record<string, unknown>
+  ): Promise<MCPToolResult> {
+    // Validate arguments
+    const validated = validateMCPArgs(
+      MCPSearchPlaybooksSchema,
+      args,
+      'search_playbooks'
+    );
+    const { query, domain } = validated;
+    const maxResults = validated.maxResults ?? this.config.maxResults;
+
+    const matches = await this.playbooks.findMatching(query, {
+      k: maxResults,
+      domains: domain ? [domain] : undefined,
+      minConfidence: this.config.minConfidence,
+      excludeAntiPatterns: true,
+    });
+
+    if (matches.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No playbooks found matching your query. Try a different description or broader search terms.',
+          },
+        ],
+      };
+    }
+
+    const results: PlaybookSearchResult[] = matches.map((m) =>
+      this.formatPlaybookForSearch(m)
+    );
+
+    const formattedResults = results
+      .map((r) => this.formatSearchResultAsText(r))
+      .join('\n\n---\n\n');
+
+    return {
+      content: [{ type: 'text', text: formattedResults }],
+    };
+  }
+
+  /**
+   * Handle get_playbook_details tool call
+   */
+  private async handleGetPlaybookDetails(
+    args: Record<string, unknown>
+  ): Promise<MCPToolResult> {
+    // Validate arguments
+    const validated = validateMCPArgs(
+      MCPGetPlaybookDetailsSchema,
+      args,
+      'get_playbook_details'
+    );
+    const playbook = await this.playbooks.get(validated.playbookId);
+
+    if (!playbook) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Playbook not found: ${validated.playbookId}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const details = this.formatPlaybookDetails(playbook);
+    return {
+      content: [{ type: 'text', text: details }],
+    };
+  }
+
+  /**
+   * Handle list_domains tool call
+   */
+  private async handleListDomains(): Promise<MCPToolResult> {
+    const allPlaybooks = await this.playbooks.getAll();
+    const domains = new Set<string>();
+
+    for (const playbook of allPlaybooks) {
+      for (const domain of playbook.applicability.domains) {
+        domains.add(domain);
+      }
+    }
+
+    const domainList = Array.from(domains).sort();
+
+    if (domainList.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No domains found. Playbooks may not have domain assignments yet.',
+          },
+        ],
+      };
+    }
+
+    const text = `Available domains:\n${domainList.map((d) => `  - ${d}`).join('\n')}`;
+    return {
+      content: [{ type: 'text', text }],
+    };
+  }
+
+  /**
+   * Handle get_playbooks_by_domain tool call
+   */
+  private async handleGetPlaybooksByDomain(
+    args: Record<string, unknown>
+  ): Promise<MCPToolResult> {
+    // Validate arguments
+    const validated = validateMCPArgs(
+      MCPGetPlaybooksByDomainSchema,
+      args,
+      'get_playbooks_by_domain'
+    );
+    const { domain } = validated;
+    const maxResults = validated.maxResults ?? 10;
+
+    const allPlaybooks = await this.playbooks.getAll();
+    const domainPlaybooks = allPlaybooks
+      .filter((p) => p.applicability.domains.includes(domain))
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, maxResults);
+
+    if (domainPlaybooks.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No playbooks found for domain: ${domain}`,
+          },
+        ],
+      };
+    }
+
+    const formatted = domainPlaybooks
+      .map((p) => this.formatPlaybookSummary(p))
+      .join('\n\n');
+
+    return {
+      content: [{ type: 'text', text: formatted }],
+    };
+  }
+
+  /**
+   * Format playbook match for search results
+   */
+  private formatPlaybookForSearch(match: PlaybookMatch): PlaybookSearchResult {
+    const { playbook, score, matchType } = match;
+    const { successCount, failureCount } = playbook.evolution;
+    const totalUses = successCount + failureCount;
+
+    return {
+      id: playbook.id,
+      name: playbook.name,
+      confidence: playbook.confidence,
+      matchScore: score,
+      matchType,
+      strategy: playbook.guidance.strategy,
+      tactics: playbook.guidance.tactics,
+      successRate: totalUses > 0 ? successCount / totalUses : 0,
+      domains: playbook.applicability.domains,
+    };
+  }
+
+  /**
+   * Format search result as text
+   */
+  private formatSearchResultAsText(result: PlaybookSearchResult): string {
+    const lines: string[] = [];
+
+    lines.push(`## ${result.name}`);
+    lines.push(`ID: ${result.id}`);
+    lines.push(`Match: ${Math.round(result.matchScore * 100)}% (${result.matchType})`);
+    lines.push(`Confidence: ${Math.round(result.confidence * 100)}%`);
+    lines.push(`Success Rate: ${Math.round(result.successRate * 100)}%`);
+
+    if (result.domains.length > 0) {
+      lines.push(`Domains: ${result.domains.join(', ')}`);
+    }
+
+    lines.push('');
+    lines.push(`**Strategy**: ${result.strategy}`);
+
+    if (result.tactics.length > 0) {
+      lines.push('**Tactics**:');
+      for (const tactic of result.tactics.slice(0, 5)) {
+        lines.push(`  - ${tactic}`);
+      }
+      if (result.tactics.length > 5) {
+        lines.push(`  ... and ${result.tactics.length - 5} more`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format playbook summary
+   */
+  private formatPlaybookSummary(playbook: Playbook): string {
+    const lines: string[] = [];
+    const { successCount, failureCount } = playbook.evolution;
+    const totalUses = successCount + failureCount;
+    const successRate = totalUses > 0 ? successCount / totalUses : 0;
+
+    lines.push(`## ${playbook.name}`);
+    lines.push(`ID: ${playbook.id}`);
+    lines.push(`Confidence: ${Math.round(playbook.confidence * 100)}%`);
+    lines.push(`Uses: ${totalUses} (${Math.round(successRate * 100)}% success)`);
+    lines.push('');
+    lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format full playbook details
+   */
+  private formatPlaybookDetails(playbook: Playbook): string {
+    const lines: string[] = [];
+    const { successCount, failureCount } = playbook.evolution;
+    const totalUses = successCount + failureCount;
+    const successRate = totalUses > 0 ? successCount / totalUses : 0;
+
+    lines.push(`# ${playbook.name}`);
+    lines.push(`ID: ${playbook.id}`);
+    lines.push(`Version: ${playbook.evolution.version}`);
+    lines.push(`Confidence: ${Math.round(playbook.confidence * 100)}%`);
+    lines.push(`Complexity: ${playbook.complexity}`);
+    lines.push(`Estimated Effort: ${playbook.estimatedEffort} steps`);
+    lines.push('');
+
+    // Applicability
+    lines.push('## Applicability');
+    if (playbook.applicability.situations.length > 0) {
+      lines.push('**When to use**:');
+      for (const sit of playbook.applicability.situations) {
+        lines.push(`  - ${sit}`);
+      }
+    }
+    if (playbook.applicability.triggers.length > 0) {
+      lines.push('**Triggers**:');
+      for (const trigger of playbook.applicability.triggers) {
+        lines.push(`  - ${trigger}`);
+      }
+    }
+    if (playbook.applicability.antiPatterns.length > 0) {
+      lines.push('**Avoid when**:');
+      for (const anti of playbook.applicability.antiPatterns) {
+        lines.push(`  - ${anti}`);
+      }
+    }
+    if (playbook.applicability.domains.length > 0) {
+      lines.push(`**Domains**: ${playbook.applicability.domains.join(', ')}`);
+    }
+    lines.push('');
+
+    // Guidance
+    lines.push('## Guidance');
+    lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
+    if (playbook.guidance.tactics.length > 0) {
+      lines.push('**Tactics**:');
+      for (const tactic of playbook.guidance.tactics) {
+        lines.push(`  - ${tactic}`);
+      }
+    }
+    if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+      lines.push('**Steps**:');
+      for (let i = 0; i < playbook.guidance.steps.length; i++) {
+        lines.push(`  ${i + 1}. ${playbook.guidance.steps[i]}`);
+      }
+    }
+    lines.push('');
+
+    // Verification
+    lines.push('## Verification');
+    if (playbook.verification.successIndicators.length > 0) {
+      lines.push('**Success indicators**:');
+      for (const ind of playbook.verification.successIndicators) {
+        lines.push(`  - ${ind}`);
+      }
+    }
+    if (playbook.verification.failureIndicators.length > 0) {
+      lines.push('**Failure indicators**:');
+      for (const ind of playbook.verification.failureIndicators) {
+        lines.push(`  - ${ind}`);
+      }
+    }
+    lines.push('');
+
+    // Statistics
+    lines.push('## Statistics');
+    lines.push(`- Total uses: ${totalUses}`);
+    lines.push(`- Success rate: ${Math.round(successRate * 100)}%`);
+    lines.push(`- Successes: ${successCount}`);
+    lines.push(`- Failures: ${failureCount}`);
+    lines.push('');
+
+    // Refinements (if enabled)
+    if (
+      this.config.includeRefinements &&
+      playbook.evolution.refinements.length > 0
+    ) {
+      lines.push('## Context-Specific Refinements');
+      for (const ref of playbook.evolution.refinements) {
+        lines.push(`- **${ref.context}**: ${ref.addition}`);
+      }
+      lines.push('');
+    }
+
+    // Failure modes
+    if (playbook.evolution.failures.length > 0) {
+      lines.push('## Known Failure Modes');
+      for (const failure of playbook.evolution.failures.slice(0, 5)) {
+        lines.push(`- ${failure.context}: ${failure.failureMode}`);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get server info for MCP protocol
+   */
+  getServerInfo(): {
+    name: string;
+    version: string;
+    description: string;
+  } {
+    return {
+      name: 'atlas-playbook-server',
+      version: '1.0.0',
+      description:
+        'MCP server providing access to the Atlas playbook library for on-demand guidance retrieval',
+    };
+  }
+}
+
+/**
+ * Create an MCP playbook server
+ */
+export function createPlaybookMCPServer(
+  playbooks: PlaybookLibrary,
+  skillLibrary?: SkillLibrary,
+  config?: Partial<MCPServerConfig>
+): PlaybookMCPServer {
+  return new PlaybookMCPServer(playbooks, skillLibrary, config);
+}

package/src/memory/curated-loader.ts

@@ -0,0 +1,160 @@
+/**
+ * Curated Playbook Loader
+ *
+ * Loads playbooks from JSON files on disk and manages them separately
+ * from runtime-extracted playbooks. Supports a --recreate workflow:
+ * drop all curated playbooks and reload from source files without
+ * losing extracted or imported playbooks.
+ *
+ * Inspired by Dash's separation of curated knowledge (file-loaded)
+ * vs learnings (runtime-discovered).
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { PlaybookProvenance } from '../types/index.js';
+import { createPlaybook } from '../types/index.js';
+import type { PlaybookLibrary } from './playbook.js';
+
+/**
+ * Schema for a curated playbook JSON file
+ */
+export interface CuratedPlaybookFile {
+  name: string;
+  applicability: {
+    situations: string[];
+    triggers?: string[];
+    antiPatterns?: string[];
+    domains: string[];
+  };
+  guidance: {
+    strategy: string;
+    tactics: string[];
+    steps?: string[];
+    codeExample?: string;
+  };
+  verification?: {
+    successIndicators?: string[];
+    failureIndicators?: string[];
+    rollbackStrategy?: string;
+  };
+  confidence?: number;
+  complexity?: 'simple' | 'moderate' | 'complex';
+  estimatedEffort?: number;
+  curatedBy?: string;
+}
+
+/**
+ * Result of a curated playbook load operation
+ */
+export interface CuratedLoadResult {
+  loaded: number;
+  skipped: number;
+  errors: Array<{ file: string; error: string }>;
+  recreated: boolean;
+}
+
+/**
+ * Load curated playbooks from a directory of JSON files into the library.
+ *
+ * @param curatedDir - Directory containing curated playbook JSON files
+ * @param library - PlaybookLibrary to load into
+ * @param options.recreate - If true, delete existing curated playbooks before loading
+ */
+export async function loadCuratedPlaybooks(
+  curatedDir: string,
+  library: PlaybookLibrary,
+  options?: { recreate?: boolean }
+): Promise<CuratedLoadResult> {
+  const result: CuratedLoadResult = {
+    loaded: 0,
+    skipped: 0,
+    errors: [],
+    recreated: false,
+  };
+
+  if (!existsSync(curatedDir)) {
+    return result;
+  }
+
+  // Recreate: drop all curated playbooks first
+  if (options?.recreate) {
+    await library.deleteByOrigin('curated');
+    result.recreated = true;
+  }
+
+  // Find all JSON files in the directory (non-recursive)
+  const files = await readdir(curatedDir);
+  const jsonFiles = files.filter((f) => f.endsWith('.json'));
+
+  for (const file of jsonFiles) {
+    const filePath = join(curatedDir, file);
+    const fileStat = await stat(filePath);
+    if (!fileStat.isFile()) continue;
+
+    try {
+      const content = await readFile(filePath, 'utf-8');
+      const parsed = JSON.parse(content) as CuratedPlaybookFile;
+
+      // Validate required fields
+      if (!parsed.name || !parsed.applicability || !parsed.guidance) {
+        result.errors.push({
+          file,
+          error: 'Missing required fields: name, applicability, guidance',
+        });
+        continue;
+      }
+
+      // Check if this curated playbook already exists (by name)
+      const existing = await library.getByName(parsed.name);
+      if (existing && !options?.recreate) {
+        result.skipped++;
+        continue;
+      }
+
+      const relativePath = relative(process.cwd(), filePath);
+      const provenance: PlaybookProvenance = {
+        origin: 'curated',
+        sourceFile: relativePath,
+        curatedBy: parsed.curatedBy,
+        recordedAt: new Date(),
+      };
+
+      const playbook = createPlaybook({
+        name: parsed.name,
+        applicability: {
+          situations: parsed.applicability.situations,
+          triggers: parsed.applicability.triggers ?? [],
+          antiPatterns: parsed.applicability.antiPatterns ?? [],
+          domains: parsed.applicability.domains,
+        },
+        guidance: {
+          strategy: parsed.guidance.strategy,
+          tactics: parsed.guidance.tactics,
+          steps: parsed.guidance.steps,
+          codeExample: parsed.guidance.codeExample,
+        },
+        verification: {
+          successIndicators: parsed.verification?.successIndicators ?? [],
+          failureIndicators: parsed.verification?.failureIndicators ?? [],
+          rollbackStrategy: parsed.verification?.rollbackStrategy,
+        },
+        provenance,
+        confidence: parsed.confidence ?? 0.7, // Curated starts higher than extracted (0.3)
+        complexity: parsed.complexity ?? 'moderate',
+        estimatedEffort: parsed.estimatedEffort ?? 3,
+      });
+
+      await library.add(playbook);
+      result.loaded++;
+    } catch (error) {
+      result.errors.push({
+        file,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}