@ace-sdk/mcp 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# @ace-sdk/mcp
+
+MCP Server for ACE pattern learning - works with any MCP-compatible client.
+
+[![npm version](https://img.shields.io/npm/v/@ace-sdk/mcp.svg)](https://www.npmjs.com/package/@ace-sdk/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install @ace-sdk/mcp
+```
+
+## Features
+
+- **15 MCP Tools**: Full ACE functionality as MCP tools
+- **Client Agnostic**: Works with Claude Code, Cursor, Cline, VSCode Copilot, or any MCP client
+- **Auto Learning**: Automatic pattern capture from coding sessions
+- **Semantic Search**: Find relevant patterns while coding
+
+## MCP Client Setup
+
+Add to your MCP configuration (e.g., `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ace-pattern-learning": {
+      "command": "npx",
+      "args": ["@ace-sdk/mcp"],
+      "env": {
+        "ACE_SERVER_URL": "https://ace-api.code-engine.app",
+        "ACE_API_TOKEN": "your-token",
+        "ACE_ORG_ID": "your-org",
+        "ACE_PROJECT_ID": "your-project"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `ace_get_playbook` | Fetch learned patterns |
+| `ace_search` | Semantic search for patterns |
+| `ace_learn` | Submit learning from execution |
+| `ace_bootstrap` | Initialize playbook from codebase |
+| `ace_status` | Get playbook statistics |
+| `ace_delta` | Manual pattern management |
+| `ace_cache_clear` | Clear local caches |
+
+## Documentation
+
+Full documentation: [packages/mcp/docs](./docs)
+
+## License
+
+MIT © [CE.NET Team](mailto:ace@code-engine.net)

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * ACE MCP Server v1.0.0
+ *
+ * Model Context Protocol server for ACE (Agentic Context Engineering) pattern learning.
+ * Uses @ace-sdk/core for HTTP client, caching, and configuration.
+ *
+ * Server-side intelligence: Reflector + Curator run on ACE server
+ * Client responsibility: Send traces, retrieve playbooks
+ *
+ * Compatible with: Claude Code, Cursor, Cline, any MCP client
+ *
+ * @package @ace-sdk/mcp
+ */
+export declare const VERSION = "1.0.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAwBH,eAAO,MAAM,OAAO,UAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,590 @@
+#!/usr/bin/env node
+/**
+ * ACE MCP Server v1.0.0
+ *
+ * Model Context Protocol server for ACE (Agentic Context Engineering) pattern learning.
+ * Uses @ace-sdk/core for HTTP client, caching, and configuration.
+ *
+ * Server-side intelligence: Reflector + Curator run on ACE server
+ * Client responsibility: Send traces, retrieve playbooks
+ *
+ * Compatible with: Claude Code, Cursor, Cline, any MCP client
+ *
+ * @package @ace-sdk/mcp
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { AceClient, loadConfig, THOROUGHNESS_PRESETS } from '@ace-sdk/core';
+import { tools } from './tools/definitions.js';
+import { InitializationService } from './services/initialization.js';
+import { checkVersionCompatibility, MCP_VERSION } from './utils/version-checker.js';
+// Re-export version
+export const VERSION = MCP_VERSION;
+// Initialize configuration
+const config = loadConfig();
+if (!config.serverUrl || !config.apiToken || !config.projectId) {
+    console.error('❌ Failed to load configuration: missing required fields');
+    console.error('   Required: serverUrl, apiToken, projectId');
+    console.error('   Run "ace-mcp" with ACE_SERVER_URL, ACE_API_TOKEN, ACE_PROJECT_ID environment variables');
+    console.error('   Or configure ~/.ace/config.json');
+    process.exit(1);
+}
+// Create AceClient from @ace-sdk/core
+const aceClient = new AceClient(config);
+// Create initialization service for bootstrap
+const initializationService = new InitializationService();
+// Check version compatibility (async, non-blocking)
+let versionStatus = null;
+checkVersionCompatibility().then(status => {
+    versionStatus = status;
+}).catch(error => {
+    console.error('⚠️  Version check failed (non-critical):', error.message);
+});
+// Create MCP server (NO SAMPLING - works with all MCP clients!)
+const server = new Server({
+    name: 'ace-pattern-learning',
+    version: VERSION
+}, {
+    capabilities: {
+        tools: {} // Just tools, no sampling required
+    }
+});
+// Register handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            // ========================================================================
+            // Configuration Tools
+            // ========================================================================
+            case 'ace_save_config': {
+                const { serverUrl, apiToken, projectId } = args;
+                console.error('💾 Saving configuration...');
+                // Save config to disk
+                const fs = await import('fs/promises');
+                const os = await import('os');
+                const path = await import('path');
+                const configDir = path.join(os.homedir(), '.ace');
+                const configPath = path.join(configDir, 'config.json');
+                await fs.mkdir(configDir, { recursive: true });
+                // Read existing config to preserve orgs section
+                let existingConfig = {};
+                try {
+                    const existingContent = await fs.readFile(configPath, 'utf8');
+                    existingConfig = JSON.parse(existingContent);
+                }
+                catch {
+                    // File doesn't exist, start fresh
+                }
+                const newConfig = {
+                    ...existingConfig,
+                    serverUrl,
+                    apiToken,
+                    projectId
+                };
+                await fs.writeFile(configPath, JSON.stringify(newConfig, null, 2), 'utf8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Configuration saved to ~/.ace/config.json',
+                                config: { serverUrl, projectId }
+                            }, null, 2)
+                        }]
+                };
+            }
+            case 'ace_get_config': {
+                console.error('🔍 Fetching server configuration...');
+                const serverConfig = await aceClient.getConfig();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(serverConfig, null, 2)
+                        }]
+                };
+            }
+            case 'ace_set_config': {
+                const { scope, ...updates } = args;
+                if (!scope) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: 'Missing required parameter',
+                                    message: 'The "scope" parameter is required',
+                                    hint: 'Use scope="project" for Claude Code CLI'
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+                if (scope !== 'project') {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: 'Invalid scope',
+                                    message: 'Claude Code CLI only supports scope="project"',
+                                    hint: 'Org-level config must be set via website dashboard'
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+                console.error('⚙️  Updating server configuration...');
+                const result = await aceClient.updateConfig(updates, scope);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Configuration updated successfully:\n${JSON.stringify(result, null, 2)}`
+                        }]
+                };
+            }
+            case 'ace_reset_config': {
+                const { scope } = args;
+                if (!scope) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: 'Missing required parameter',
+                                    message: 'The "scope" parameter is required',
+                                    hint: 'Use scope="project" for Claude Code CLI'
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+                if (scope !== 'project') {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: 'Invalid scope',
+                                    message: 'Claude Code CLI only supports scope="project"',
+                                    hint: 'Org-level config must be set via website dashboard'
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+                console.error('🔄 Resetting project configuration to defaults...');
+                const result = await aceClient.resetConfig(scope);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Configuration reset successfully:\n${JSON.stringify(result, null, 2)}`
+                        }]
+                };
+            }
+            // ========================================================================
+            // Playbook Operations
+            // ========================================================================
+            case 'ace_get_playbook': {
+                const { section, min_helpful, include_metadata } = args;
+                console.error('📖 Fetching playbook from server...');
+                const response = await aceClient.getPlaybook({ include_metadata });
+                let playbook = response.playbook;
+                // Client-side filtering if requested
+                if (section) {
+                    playbook = {
+                        strategies_and_hard_rules: section === 'strategies_and_hard_rules' ? playbook.strategies_and_hard_rules : [],
+                        useful_code_snippets: section === 'useful_code_snippets' ? playbook.useful_code_snippets : [],
+                        troubleshooting_and_pitfalls: section === 'troubleshooting_and_pitfalls' ? playbook.troubleshooting_and_pitfalls : [],
+                        apis_to_use: section === 'apis_to_use' ? playbook.apis_to_use : []
+                    };
+                }
+                if (min_helpful !== undefined) {
+                    for (const key of Object.keys(playbook)) {
+                        playbook[key] = playbook[key].filter((b) => (b.helpful || 0) >= min_helpful);
+                    }
+                }
+                const result = { playbook };
+                if (response.metadata) {
+                    result.metadata = response.metadata;
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            }
+            case 'ace_search': {
+                const { query, section, threshold, include_metadata } = args;
+                console.error(`🔍 Searching for patterns: "${query}"`);
+                // Fetch config if threshold not specified
+                let searchThreshold = threshold;
+                if (!searchThreshold) {
+                    const serverConfig = await aceClient.getConfig();
+                    searchThreshold = serverConfig.constitution_threshold || 0.85;
+                    console.error(`📊 Using dynamic threshold from config: ${searchThreshold}`);
+                }
+                const response = await aceClient.searchPatterns({
+                    query,
+                    section,
+                    threshold: searchThreshold,
+                    include_metadata
+                });
+                const result = {
+                    query,
+                    threshold: response.threshold,
+                    results: response.similar_patterns,
+                    count: response.count,
+                    message: `Found ${response.count} patterns matching "${query}"`
+                };
+                if (response.metadata) {
+                    result.metadata = response.metadata;
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            }
+            case 'ace_top_patterns': {
+                const { section, limit, min_helpful } = args;
+                console.error('⭐ Fetching top patterns...');
+                const results = await aceClient.getTopPatterns({
+                    section,
+                    limit: limit || 10,
+                    min_helpful: min_helpful || 0
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                section: section || 'all',
+                                results,
+                                count: results.length,
+                                message: `Retrieved ${results.length} top-rated patterns`
+                            }, null, 2)
+                        }]
+                };
+            }
+            case 'ace_clear': {
+                const { confirm } = args;
+                if (!confirm) {
+                    throw new Error('Must set confirm=true to clear playbook');
+                }
+                console.error('🗑️  Clearing playbook...');
+                await aceClient.clearPlaybook();
+                aceClient.invalidateCache();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Playbook cleared successfully'
+                            }, null, 2)
+                        }]
+                };
+            }
+            case 'ace_batch_get': {
+                const { pattern_ids } = args;
+                if (!Array.isArray(pattern_ids) || pattern_ids.length === 0) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: 'Error: pattern_ids must be a non-empty array'
+                            }]
+                    };
+                }
+                console.error(`📦 Batch fetching ${pattern_ids.length} patterns...`);
+                const result = await aceClient.batchGetPatterns(pattern_ids);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            }
+            case 'ace_delta': {
+                const { operation, bullets } = args;
+                console.error(`🔄 Applying delta operation: ${operation}...`);
+                for (const bullet of bullets) {
+                    await aceClient.applyDelta({
+                        type: operation.toUpperCase(),
+                        section: bullet.section,
+                        content: bullet.content,
+                        bullet_id: bullet.id,
+                        helpful_delta: bullet.helpful,
+                        harmful_delta: bullet.harmful,
+                        evidence: bullet.evidence
+                    });
+                }
+                aceClient.invalidateCache();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                operation,
+                                bullets_affected: bullets.length,
+                                message: `Successfully applied ${operation} operation to ${bullets.length} bullet(s)`
+                            }, null, 2)
+                        }]
+                };
+            }
+            // ========================================================================
+            // Learning & Bootstrap
+            // ========================================================================
+            case 'ace_learn': {
+                const { task, trajectory, success, output, error, playbook_used } = args;
+                console.error('📤 Sending execution trace to server...');
+                // Convert string array to TrajectoryStep array if needed
+                const formattedTrajectory = trajectory.map((step, index) => {
+                    if (typeof step === 'string') {
+                        return {
+                            step: index + 1,
+                            action: step,
+                            args: {},
+                            result: 'Completed'
+                        };
+                    }
+                    return step;
+                });
+                const trace = {
+                    task,
+                    trajectory: formattedTrajectory,
+                    result: { success, output, error },
+                    playbook_used: playbook_used || [],
+                    timestamp: new Date().toISOString()
+                };
+                try {
+                    const result = await aceClient.storeExecutionTrace(trace);
+                    aceClient.invalidateCache();
+                    console.error('✅ Execution trace stored. Server is analyzing...');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: true,
+                                    message: 'Execution trace stored successfully. Server-side Reflector and Curator will process asynchronously.',
+                                    task,
+                                    timestamp: trace.timestamp,
+                                    analysis_triggered: result.analysis_performed || false,
+                                    learning_statistics: result.learning_statistics
+                                }, null, 2)
+                            }]
+                    };
+                }
+                catch (err) {
+                    console.error('❌ Error storing trace:', err);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: err.message || 'Failed to store execution trace'
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+            }
+            case 'ace_bootstrap': {
+                const { mode, thoroughness, repo_path, max_files, commit_limit, days_back, merge_with_existing: _mergeWithExisting } = args;
+                const thoroughnessLevel = thoroughness || 'medium';
+                const preset = THOROUGHNESS_PRESETS[thoroughnessLevel];
+                const effectiveMaxFiles = max_files ?? preset.max_files;
+                const effectiveCommitLimit = commit_limit ?? preset.commit_limit;
+                const effectiveDaysBack = days_back ?? preset.days_back;
+                const analysisMode = mode || 'hybrid';
+                const projectPath = repo_path || process.cwd();
+                console.error(`🚀 Bootstrapping playbook (mode: ${analysisMode}, thoroughness: ${thoroughnessLevel})...`);
+                console.error(`   Files: ${effectiveMaxFiles === -1 ? 'unlimited' : effectiveMaxFiles}, Commits: ${effectiveCommitLimit}, Days: ${effectiveDaysBack}`);
+                try {
+                    console.error('📚 Running local codebase analysis...');
+                    const playbook = await initializationService.initializeFromCodebase(projectPath, {
+                        mode: analysisMode,
+                        commitLimit: effectiveCommitLimit,
+                        daysBack: effectiveDaysBack,
+                        maxFiles: effectiveMaxFiles
+                    });
+                    const allBullets = [
+                        ...playbook.strategies_and_hard_rules,
+                        ...playbook.useful_code_snippets,
+                        ...playbook.troubleshooting_and_pitfalls,
+                        ...playbook.apis_to_use
+                    ];
+                    console.error(`✅ Discovered ${allBullets.length} patterns locally`);
+                    if (allBullets.length === 0) {
+                        console.error('⚠️  No patterns found - playbook is empty');
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        success: true,
+                                        patternsExtracted: 0,
+                                        message: 'No patterns found in codebase. Try working on real tasks to build the playbook through online learning.'
+                                    }, null, 2)
+                                }]
+                        };
+                    }
+                    // Build code blocks for bootstrap endpoint
+                    const codeBlocks = [];
+                    for (const snippet of playbook.useful_code_snippets) {
+                        if (snippet.evidence && snippet.evidence.length > 0) {
+                            codeBlocks.push(`File: ${snippet.evidence[0]}\n\n${snippet.content}`);
+                        }
+                        else {
+                            codeBlocks.push(snippet.content);
+                        }
+                    }
+                    for (const pattern of playbook.troubleshooting_and_pitfalls) {
+                        if (pattern.content.length > 100) {
+                            codeBlocks.push(pattern.content);
+                        }
+                    }
+                    for (const pattern of playbook.strategies_and_hard_rules) {
+                        if (pattern.content.length > 100) {
+                            codeBlocks.push(pattern.content);
+                        }
+                    }
+                    for (const pattern of playbook.apis_to_use) {
+                        if (pattern.content.length > 100) {
+                            codeBlocks.push(pattern.content);
+                        }
+                    }
+                    console.error(`📤 Sending ${codeBlocks.length} code blocks to ACE server for bootstrap...`);
+                    const bootstrapResult = await aceClient.bootstrap({
+                        mode: analysisMode,
+                        code_blocks: codeBlocks,
+                        metadata: {
+                            blocks_extracted: codeBlocks.length,
+                            thoroughness: thoroughness || 'medium',
+                            file_extensions: []
+                        }
+                    });
+                    aceClient.invalidateCache();
+                    console.error(`✅ Bootstrap complete: ${bootstrapResult.blocks_received} blocks → ${bootstrapResult.patterns_extracted} patterns (${bootstrapResult.compression_percentage}% compression)`);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: true,
+                                    mode: analysisMode,
+                                    blocks_sent: bootstrapResult.blocks_received,
+                                    patterns_extracted: bootstrapResult.patterns_extracted,
+                                    compression_percentage: bootstrapResult.compression_percentage,
+                                    breakdown: bootstrapResult.by_section,
+                                    average_confidence: bootstrapResult.average_confidence,
+                                    analysis_time_seconds: bootstrapResult.analysis_time_seconds,
+                                    message: `Bootstrap complete! Sent ${bootstrapResult.blocks_received} code blocks → Server extracted ${bootstrapResult.patterns_extracted} unique patterns (${bootstrapResult.compression_percentage}% compression via semantic deduplication)`,
+                                    next_steps: 'Use /ace-patterns to view the deduplicated playbook.'
+                                }, null, 2)
+                            }]
+                    };
+                }
+                catch (err) {
+                    console.error('❌ Error during bootstrap:', err);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: err.message || 'Failed to bootstrap playbook',
+                                    stack: err.stack
+                                }, null, 2)
+                            }],
+                        isError: true
+                    };
+                }
+            }
+            // ========================================================================
+            // Utilities
+            // ========================================================================
+            case 'ace_status': {
+                console.error('📊 Fetching status from server...');
+                const status = await aceClient.getAnalytics();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(status, null, 2)
+                        }]
+                };
+            }
+            case 'ace_version_status': {
+                console.error('📊 Checking version compatibility...');
+                if (!versionStatus) {
+                    versionStatus = await checkVersionCompatibility();
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(versionStatus, null, 2)
+                        }]
+                };
+            }
+            case 'ace_cache_clear': {
+                const { cache_type } = args;
+                const cacheType = cache_type || 'all';
+                console.error(`🗑️  Clearing ${cacheType} cache...`);
+                if (cacheType === 'ram' || cacheType === 'all') {
+                    aceClient.invalidateCache();
+                    aceClient.clearConfigCache();
+                    console.error('✅ RAM cache cleared (playbook + config)');
+                }
+                if (cacheType === 'sqlite' || cacheType === 'all') {
+                    const localCache = aceClient.getLocalCache();
+                    if (localCache) {
+                        localCache.clear();
+                        console.error('✅ SQLite cache cleared');
+                    }
+                    else {
+                        console.error('ℹ️  SQLite cache not available (skipped)');
+                    }
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                cache_type: cacheType,
+                                message: `${cacheType.toUpperCase()} cache cleared successfully`
+                            }, null, 2)
+                        }]
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        console.error(`❌ Error in ${name}:`, err);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: err.message || String(err)
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`✅ ACE MCP Server v${VERSION} started`);
+    console.error('🔗 Server:', config.serverUrl);
+    console.error('📋 Project:', config.projectId);
+    if (config.orgs && Object.keys(config.orgs).length > 0) {
+        console.error('🌐 Multi-org:', `${Object.keys(config.orgs).length} organization(s) configured`);
+    }
+    console.error('🌍 Universal MCP compatibility (no sampling required)');
+}
+main().catch((error) => {
+    console.error('❌ Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map