Amicus MCP Server

# Changelog All notable changes to the Amicus MCP Server project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.8.0] - 2026-02-03 ### Added #### Token Embedding System for Context Efficiency - **3 New Components for Semantic Context Management** (GitHub Issue [#9](https://github.com/earchibald/amicus-mcp/issues/9)): - **`EmbeddingManager`**: Core class for generating and storing vector embeddings using sentence-transformers - **`ContextArchiver`**: Automatic archival of old tasks and messages to embedding database - **`search_history()` MCP Tool**: Semantic search of historical context with similarity scoring - **SQLite Vector Storage**: Efficient storage of 384-dimensional embeddings with metadata - **sentence-transformers Integration**: Uses all-MiniLM-L6-v2 model (80MB, fast, accurate) - **Automatic Context Archival**: Moves old completed tasks/messages from state.json to embeddings - **60-80% Token Reduction**: Significant reduction in active context size for long-running sessions - **32 New Tests**: 13 embedding tests + 19 archival tests, all passing - **Research Documentation**: Comprehensive research docs in copilot/research-token-embedding-efficiency branch ### Changed - **Total MCP Tools**: Increased from 29 to 30 tools - **Dependencies**: Added sentence-transformers>=2.2.0 and numpy>=1.24.0 - **Session Duration**: Expected 4.5x increase in maximum session length (16h → 72h) ### Performance - **Token Efficiency**: 60-80% reduction in context size for multi-agent scenarios - **Search Speed**: ~1000 items/second embedding generation - **Storage**: ~150MB additional disk space per instance --- ## [0.7.0] - 2026-02-02 ### Added #### File Coordination Governance System - **4 New MCP Tools for File Intent Coordination** (GitHub Issue [#7](https://github.com/earchibald/amicus-mcp/issues/7)): - **`declare_file_intent()`**: Declare intent to modify files before starting work - **`check_file_conflicts()`**: Check if files have conflicting intents from other agents - **`release_file_intent()`**: Release file intent after completing work - **`get_file_intents()`**: List all active file intents with optional filtering - **Lightweight Intent-Based Coordination**: Prevents agents from stomping on each other's file changes - **Automatic Expiration**: Intents expire automatically (default 5 min TTL) to handle crashed agents - **Conflict Detection**: Write intents conflict with other write intents; read intents are shared - **State Schema Extension**: New `file_intents` field in state.json tracks active intents - **read_state Integration**: Displays file intent summary and conflict warnings - **[docs/FILE_COORDINATION.md](docs/FILE_COORDINATION.md)**: Comprehensive workflow documentation ### Changed - **Total MCP Tools**: Increased from 25 to 29 tools - **read_state()**: Now displays file intents summary and conflict alerts --- ## [0.6.0] - 2026-02-02 ### Added #### Code Audit Governance System - **6 New MCP Tools for Code Review Workflow** (GitHub Issue [#8](https://github.com/earchibald/amicus-mcp/issues/8)): - **`submit_code_audit_request()`**: Submit proposed file changes for review before execution - **`get_pending_audits()`**: Retrieve all pending audit requests awaiting review - **`approve_code_audit()`**: Approve a pending audit, allowing the requesting agent to proceed - **`reject_code_audit()`**: Reject an audit with required feedback for improvement - **`get_audit_status()`**: Check the status and details of a specific audit request - **`list_code_audits()`**: List all audits with optional status and agent filtering - **Governance Workflow**: Agents must submit code changes for review by a code reviewer agent before execution - **Self-Review Prevention**: Agents cannot approve or reject their own audit requests - **Priority-Based Queue**: Audits are sorted by priority (high, medium, low) and age - **State Schema Extension**: New `code_audits` field in state.json tracks all audit requests - **read_state Integration**: Displays code audit summary with pending review notifications - **[docs/CODE_AUDIT_GOVERNANCE.md](docs/CODE_AUDIT_GOVERNANCE.md)**: Comprehensive workflow documentation ### Changed - **Total MCP Tools**: Increased from 19 to 25 tools - **read_state()**: Now displays code audit status summary and pending review alerts ## [0.5.2] - 2026-02-02 ### Added #### Dynamic MCP Configuration Generator - **Multi-Client Support**: Generate MCP configurations for 7 different AI coding clients from the CLI - GitHub Copilot CLI (`copilot`) - Claude Desktop App (`claude-desktop`) - Claude Code CLI (`claude-code`) - VS Code (`vscode`) - Cursor (`cursor`) - Windsurf (`windsurf`) - Zed Editor (`zed`) - **New CLI Commands**: - `--list-clients`: Display all supported MCP clients with their configuration paths - `--client <name>`: Specify target client for config generation - `--generate-mcp-config {stdout,global,workspace}`: Generate and optionally write config - `--force`: Overwrite existing config files without prompting - **Client-Specific Formats**: Each client gets the correct configuration schema: - Copilot CLI: Includes required `tools: ["*"]` array - Zed: Uses `context_servers` key instead of `mcpServers` - Claude Code: Shows install command recommendation - **Auto-Detection**: Automatically detects `amicus-mcp` installation path for global configs ### Changed - **IDE_INTEGRATION.md**: Added Dynamic Configuration Generator section with usage examples - **GitHub Copilot CLI Section**: Updated to reflect working MCP protocol integration with correct configuration requirements ### Fixed - **Copilot CLI MCP Integration**: Documented correct configuration format (tools array required, args must be empty) ## [0.5.1] - 2026-02-02 ### Added #### IDE and CLI Client Integration Documentation - **[docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md)**: Comprehensive integration guide covering 7 IDEs and CLI clients - VS Code (official and Insiders) with CLI install, manual config, and Settings UI - Cursor with UI-based and manual setup, project-level configurations - Windsurf with Cascade settings and MCP Marketplace integration - Claude Desktop App with platform-specific paths (macOS, Windows, Linux) - Zed Editor with context servers and project-level configuration - Claude CLI with `claude mcp add` commands and scope options - Direct MCP Protocol usage with Python client examples - **[docs/IDE_INTEGRATION_RESEARCH.md](docs/IDE_INTEGRATION_RESEARCH.md)**: Technical research document - IDE support matrix (2026 versions) - Analysis of 5 major CLI clients - Installation badge mechanisms and tools - Platform-specific path conventions - Critical troubleshooting patterns and solutions - Configuration best practices from 40+ sources - **Comprehensive Troubleshooting Guide**: Common issues, platform-specific problems, and solutions - **Quick Reference Materials**: Config file locations, CLI commands, installation templates ### Changed - **README.md**: Added prominent link to IDE integration documentation ### Fixed - Documentation gap for IDE/CLI client integration resolved ## [0.5.0] - 2026-02-02 ### Added #### GitHub Issues Integration - **4 New MCP Tools for GitHub Issues Workflow**: - **`create_github_issue()`**: Create new GitHub issues from agents or humans with optional labels and assignment - **`list_github_issues()`**: List and filter GitHub issues by state (open/closed/all) and labels - **`import_github_issue_to_task()`**: Import GitHub issues to local task context on demand, maintaining full metadata - **`sync_task_to_github_issue()`**: Bidirectional sync - update GitHub issues with task status, add comments, and close issues - **Optional PyGithub Dependency**: Gracefully degrades if PyGithub library not installed - **GitHub Issue Metadata Tracking**: Tasks imported from GitHub maintain issue number, repository, and URL - **Duplicate Prevention**: Prevents importing the same issue multiple times - **On-Demand Import**: Issues only added to local context when explicitly requested (prevents context pollution) #### Documentation - **[docs/GITHUB_ISSUES_INTEGRATION.md](docs/GITHUB_ISSUES_INTEGRATION.md)**: Comprehensive architecture design document covering integration strategy, tool specifications, and usage patterns - **[docs/GITHUB_WORKFLOW.md](docs/GITHUB_WORKFLOW.md)**: User workflow guide with practical examples #### Testing - **`tests/test_github_issues.py`**: Comprehensive unit test suite with 13 tests covering all GitHub tools - **`test_github_workflow.py`**: Manual validation script for structure verification ### Changed - **Enhanced `server.py`**: Added GitHub integration layer with 4 new tools (lines 771-1040) - **Optional Dependencies**: PyGithub is now an optional dependency with clear error messages when not available ### Fixed - GitHub token authentication properly handled via GITHUB_TOKEN environment variable ## [0.4.0] - 2026-02-02 ### Added #### Anti-Idle System - **Intelligent Node Lifecycle Management**: Prevents Synapse nodes from falling idle through automatic workload assessment and graceful termination - **Capacity Enforcement**: Hard limit of 4 concurrent nodes with registration rejection at capacity - **Enhanced State Schema**: - `cluster_nodes`: Now tracks `status`, `idle_since`, `current_task_id`, and `last_activity` - `cluster_metadata`: New top-level structure for cluster statistics (active count, idle count, pending tasks, manager ID) - `work_distribution`: Workload intelligence with status (idle/underutilized/balanced/overloaded) and spawn recommendations #### New MCP Tools - **`set_agent_status(agent_id, status, current_task_id)`**: Update agent status and track idle transitions - **`claim_best_task(agent_id, role)`**: Intelligently claim highest-priority task based on: - Priority scoring (high=30, medium=20, low=10) - Role match bonus (+15 points for architect/developer keywords) - Age bonus (+1 per minute) - **`assess_workload()`**: Analyze cluster state and generate spawn/terminate recommendations - Called by Bootstrap Manager every 20-30 seconds - Returns workload status and actionable recommendations #### Configuration - **New `cluster_settings` in config.py**: - `max_agents`: 4 (hard limit on concurrent nodes) - `idle_timeout_seconds`: 30 (worker self-termination threshold) - `manager_heartbeat_interval`: 20 (manager heartbeat frequency) - `workload_assessment_interval`: 25 (manager assessment frequency) - `grace_period_seconds`: 30 (monitor cleanup threshold) #### Protocol Enhancements - **SYNAPSE_PROTOCOL.md**: Added STEP 1.5 for idle detection and self-termination - Workers check for idle condition after `catch_up()` - 30-second grace period before termination - Bootstrap Managers never auto-terminate - **BOOTSTRAP_MANAGER.md**: Added Section 4 for workload management - Continuous assessment protocol (every 20-30s) - Node spawning protocol (user confirmation required) - Node termination protocol (graceful idle cleanup) - Max agents enforcement guidelines #### Self-Managing Cluster Protocol - **Bootstrap Manager**: Defined a special agent role for initializing the cluster, delegating tasks, and monitoring swarm health - **Node Registration**: Added `register_node` tool for agents to join the cluster, declare a role (e.g., `bootstrap_manager`, `developer`), and report their model - **Intelligent Model Selection**: Added `get_best_model` tool to allow the Bootstrap Manager to select agents based on task requirements - **Automated Recovery**: The `HeartbeatMonitor` now detects a failed Bootstrap Manager and automatically injects a high-priority recovery task into the queue - **Enhanced State Visibility**: `read_state` now displays a real-time view of the "Active Cluster Swarm" with roles, models, and liveness status #### HeartbeatMonitor Enhancements - **Idle Detection**: Automatic cleanup of nodes idle > 60 seconds - **Cluster Metadata Updates**: Real-time tracking of active and idle node counts - **Graceful Termination**: Marks stale idle nodes as `status: "terminated"` #### Documentation - **[docs/ANTI_IDLE_SYSTEM.md](docs/ANTI_IDLE_SYSTEM.md)**: Comprehensive implementation guide covering architecture, protocols, configuration, testing, and troubleshooting - **Enhanced README**: Added anti-idle system overview, quick examples, and demo instructions #### Examples and Testing - **`examples/anti_idle_demo.py`**: Interactive demonstration of cluster lifecycle (bootstrap, scaling, execution, idle detection, termination) - **`test_anti_idle.py`**: Unit test suite for anti-idle functionality (metadata initialization, state schema validation, idle detection logic) ### Changed - **`register_node()`**: Now enforces max_agents constraint and initializes enhanced node schema - Returns error message if cluster is at capacity - Initializes `cluster_metadata` if not present - Sets initial node status to `"working"` - Tracks manager_id for Bootstrap Manager nodes - **`update_state()`**: Preserves `cluster_nodes`, `cluster_metadata`, and `work_distribution` across updates - **`read_state()`**: Enhanced output formatting with cluster metadata, work distribution, and visual node status indicators - **HeartbeatMonitor**: Extended health checks to include idle detection and cleanup - **Heartbeat Protocol**: The `heartbeat` tool and `HeartbeatMonitor` were upgraded to track individual nodes within the cluster, enabling role-specific liveness checks - **Synapse Protocol**: Updated `SYNAPSE_PROTOCOL.md` and related prompts to include the new node registration and role-based interaction patterns - **Core Architecture Refactor**: Migrated the entire codebase from a single root `server.py` to a modular `src/amicus` package structure for better organization and scalability ### Fixed - Removed duplicate `get_best_model()` and `register_node()` function definitions in `server.py` - **Test Suite**: Repaired multiple test regressions in `test_monitor.py` caused by the new Bootstrap Manager recovery logic, ensuring all 32 tests pass - **Security Scanner**: Improved the regex for Stripe API key detection in the `SensitiveDataScanner` to prevent false negatives ### Security - Anti-idle system prevents runaway node spawning (user confirmation required) - Max 4 nodes enforced at registration time (cannot be bypassed) - Idle nodes terminate gracefully (no orphaned processes) ## [0.2.0] - 2026-02-01 ### Added - **CLI Commands**: Added comprehensive CLI interface for introspection and validation - `--list-tools`: List all available MCP tools with parameters - `--list-prompts`: List all available MCP prompts - `--list-resources`: List all available MCP resources - `--validate-env`: Validate environment configuration and show diagnostics - `--show-state`: Display current state without starting the server - `--audit-prompt`: Display comprehensive audit prompt - `--help`: Show all commands with usage examples - **Audit Framework**: Added comprehensive audit framework for project evaluation - `prompts/comprehensive-audit.md`: Multi-dimensional audit covering 10 key areas - `prompts/testing-guide.md`: Practical test implementation patterns and examples - `prompts/LAUNCH.md`: One-line launch prompt for easy audit execution - `prompts/README.md`: Documentation for using the audit framework - **Documentation**: Enhanced README with CLI usage, audit instructions, and examples ### Changed - Updated `pyproject.toml` to use `dependency-groups` instead of deprecated `tool.uv.dev-dependencies` - Enhanced build configuration to include `prompts/` directory in package builds ### Fixed - Fixed package build configuration to properly include `server.py` module - Resolved hatchling build errors by adding explicit file inclusion configuration ## [0.1.0] - 2026-02-01 ### Added - Initial implementation of Amicus MCP Server - Core MCP tools: - `update_state`: Update context bus state with agent information - `read_state`: Read current state from the context bus - `toggle_tracking`: Enable or disable state tracking - MCP prompt: - `catch_up`: Get current state with headers to reset agent focus - State persistence with JSON file storage - File locking with stale lock detection (10-second timeout) - Atomic write operations using temporary files - Auto-ignore: Automatically adds `.ai/` to `.gitignore` - Configurable via `CONTEXT_BUS_DIR` environment variable - Race condition safe operations - Elicitation pattern for human input signaling - Comprehensive README with usage examples - MIT License - Project specification document ### Technical Details - Python 3.10+ support - FastMCP integration for MCP protocol - Portalocker for cross-platform file locking - Hatchling build backend [0.2.0]: https://github.com/yourusername/amicus-mcp/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/yourusername/amicus-mcp/releases/tag/v0.1.0