Amicus MCP Server - The Synapse Protocol

A state persistence layer ("Context Bus") for AI coding agents in VS Code. Amicus enables seamless handoffs between different AI assistants (Gemini, Copilot, Claude) by maintaining shared state.

Features

• State Persistence: Maintains context across different AI agents
• Agent Communication: Persistent messages stream for inter-agent signals
• Anti-Idle System: Intelligent node lifecycle management with automatic scaling (NEW in v0.4.0)
  • Max 4 concurrent nodes with capacity enforcement
  • Automatic idle detection and graceful termination
  • Workload-based spawn recommendations
  • Smart task prioritization and claiming
• Sandboxing: Filesystem guardrails to restrict agents to project root
• Security: Command execution whitelisting
• Race Condition Safe: Uses file locking with stale lock detection
• Atomic Operations: Ensures state is never corrupted by partial writes
• Auto-Ignore: Automatically adds .ai/ directory to .gitignore
• Configurable: Supports Global and Workspace configurations

🚀 Quick Install

CLI (Universal)

uv tool install amicus-mcp --force
amicus-mcp --version  # Verify installation
amicus-mcp --init

Development Install (with validation)

⚠️ IMPORTANT: Always validate before installing from source:

# 1. Clone repository
git clone https://github.com/amicus-mcp/amicus.git
cd amicus

# 2. REQUIRED: Run validation
./scripts/validate_before_install.sh

# 3. Only install if validation passes
uv tool install . --force

# 4. Verify installation
amicus-mcp --version
amicus-mcp --list-tools  # Should show 15 tools

See GOVERNANCE.md for installation safety protocol.

🛠️ Client Configuration

For comprehensive IDE integration guides covering VS Code, Cursor, Windsurf, Claude Desktop, Zed, and CLI clients, see IDE Integration Guide.

{
  "mcpServers": {
    "amicus": {
      "command": "uv",
      "args": ["tool", "run", "amicus-mcp"],
      "env": {
        "CONTEXT_BUS_DIR": "/path/to/your/project/.ai"
      }
    }
  }
}

{
  "mcpServers": {
    "amicus": {
      "command": "uv",
      "args": ["tool", "run", "amicus-mcp"]
    }
  }
}

🎯 Quick Start

Once installed, here's how to get started with Amicus in your project:

1. Initialize Your Project

cd /path/to/your/project
amicus-mcp --init

This creates a .ai/ directory in your project root for state persistence.

2. Basic Agent Coordination

Here's a simple example of two agents coordinating through Amicus:

Agent A (Python):

import sys
sys.path.insert(0, '/path/to/amicus-mcp/src')
from amicus.core import get_state_file, read_with_lock, write_with_lock

# Read current state
state = read_with_lock(get_state_file())

# Add a task
state.setdefault("tasks", []).append({
    "id": "task-1",
    "title": "Review authentication code",
    "status": "pending",
    "created_by": "Agent A"
})

# Broadcast a message
state.setdefault("messages", []).append({
    "from": "Agent A",
    "message": "Task created! Agent B, please take this.",
    "timestamp": "2026-02-02T10:00:00Z"
})

# Write back to context bus
write_with_lock(get_state_file(), state)

Agent B (reads the same state):

# Agent B reads the state
state = read_with_lock(get_state_file())

# See Agent A's message
messages = state.get("messages", [])
print(messages[-1])  # {'from': 'Agent A', 'message': '...'}

# Claim the task
for task in state.get("tasks", []):
    if task["id"] == "task-1" and task["status"] == "pending":
        task["status"] = "in_progress"
        task["assigned_to"] = "Agent B"
        break

# Update state
write_with_lock(get_state_file(), state)

3. Check Your State

View the current context bus state anytime:

amicus-mcp --show-state

4. Complete Example

See a full working example in examples/basic_usage.py that demonstrates:

• Reading and writing state
• Agent registration
• Task management
• Message broadcasting
• Completion tracking

Run it with:

python3 examples/basic_usage.py

5. Using MCP Tools in Claude Desktop

Once configured, you can use Amicus tools directly in conversations:

• "Use read_state to see what the previous agent was working on"
• "Add a task to review the authentication module using add_task"
• "Broadcast a message that I've completed the database migration"

The tools handle all the locking and state management automatically.

Anti-Idle System (v0.4.0)

Amicus now includes an intelligent anti-idle system that prevents Synapse nodes from remaining idle while work is available. The system automatically manages node lifecycle, enforces a maximum of 4 concurrent nodes, and provides workload-based scaling recommendations.

Key Features

• Capacity Enforcement: Hard limit of 4 concurrent nodes
• Idle Detection: Automatic detection and graceful termination of idle worker nodes
• Intelligent Task Claiming: Priority-based task scoring for optimal work distribution
• Workload Assessment: Real-time cluster health monitoring and spawn recommendations
• Bootstrap Manager Coordination: Central orchestration of node lifecycle

New MCP Tools

set_agent_status(agent_id, status, current_task_id)

Update an agent's status (working/idle/waiting/terminated) and track idle transitions.

claim_best_task(agent_id, role)

Intelligently claim the highest-priority task based on role match, priority, and age.

assess_workload()

Analyze cluster state and generate spawn/terminate recommendations. Called by Bootstrap Manager every 20-30 seconds.

Quick Example

# Worker node claiming best-fit task
claim_best_task("Node-X9J2", "developer")
# → "Claimed task 3: Implement user authentication"

# Bootstrap Manager assessing workload
assess_workload()
# → Status: OVERLOADED, Recommendation: spawn_developer

# Worker going idle after completing tasks
set_agent_status("Node-X9J2", "idle", None)
# (After 30s grace period, node terminates gracefully)

Documentation

• Anti-Idle System Guide - Complete implementation details
• SYNAPSE_PROTOCOL.md - Worker node lifecycle protocol
• BOOTSTRAP_MANAGER.md - Manager coordination protocol

Demo

Run the interactive demonstration:

python examples/anti_idle_demo.py

This simulates a complete cluster lifecycle including bootstrap, scaling up, task execution, idle detection, and graceful termination.

Tools

update_state

Update the context bus state with current agent's information.

Parameters:

• summary (string): Summary of what has been done so far
• next_steps (list of dicts): A list of task dictionaries. Example: [{"task": "Fix bug", "status": "pending", "assigned_to": "Node-1"}]
• active_files (list): List of files currently being worked on
• ask_user (boolean, optional): Whether human input is required
• messages (list, optional): Optional list of messages for other agents
• model_info (dict, optional): Optional dictionary containing information about the agent's model (e.g., {'name': 'gemini-1.5-flash', 'strength': 'high'})
• model_info (dict, optional): Optional dictionary containing information about the agent's model (e.g., {'name': 'gemini-1.5-flash', 'strength': 'high'})

add_task

Add a new task to the next_steps queue.

Parameters:

• task_description (string): Description of the task to be done
• priority (string, optional): Priority of the task (low, medium, high). Defaults to "medium".

read_state

Read the current state from the context bus.

broadcast_message

Send a message to all other agents via the context bus.

Parameters:

• message (string): The message to broadcast

claim_task

Claim a task from the next_steps queue.

Parameters:

• task_index (int): The 1-based index of the task to claim (as shown in read_state)
• agent_id (string): The ID of the agent claiming the task

complete_task

Mark a task as completed.

Parameters:

• task_index (int): The 1-based index of the task to complete
• agent_id (string): The ID of the agent completing the task
• outcome (string, optional): Brief description of the result. Defaults to "Success".

register_node

Register a node with a specific role and model information.

Parameters:

• agent_id (string): Unique identifier for the agent
• role (string): Role of the agent (e.g., bootstrap_manager, architect, developer)
• model_name (string): Name of the model being used
• model_strength (string, optional): Manual strength assessment (low, medium, high)

get_best_model

Select the best model for a given task based on strength assessments.

Parameters:

• task_description (string): A description of the task to assess

register_node

Register a node with a specific role and model information.

Parameters:

• agent_id (string): Unique identifier for the agent
• role (string): Role of the agent (e.g., bootstrap_manager, architect, developer)
• model_name (string): Name of the model being used
• model_strength (string, optional): Manual strength assessment (low, medium, high)

get_best_model

Select the best model for a given task based on strength assessments.

Parameters:

• task_description (string): A description of the task to assess

is_safe_path

Check if a path is safe for operations (within project root).

Parameters:

• path (string): The path to check

execute_safe_command

Execute a shell command if it is in the whitelist.

Parameters:

• command (string): The command to execute

heartbeat

Signal that the current agent is still active.

toggle_tracking

Enable or disable state tracking (useful for throwaway sessions).

Parameters:

• enabled (boolean): Whether tracking should be enabled

Prompts

catch_up

Injects the current state with headers designed to reset agent focus. Use this when switching between AI agents to help them understand the current context.

Security

Amicus includes built-in security guardrails to ensure AI agents operate safely. See SECURITY.md for details on:

• Filesystem Sandboxing
• Command Whitelisting

Usage Examples

Updating State

from unittest.mock import MagicMock
# Mock server for documentation validation
server = MagicMock()

server.update_state(
    summary="Implemented user authentication",
    next_steps=[
        {"task": "Add password reset", "status": "pending", "priority": "high"}
    ],
    active_files=["src/auth.py"]
)

Architecture

State Storage

State is stored in a JSON file at:

• ${CONTEXT_BUS_DIR}/state.json (if CONTEXT_BUS_DIR is set)
• {CWD}/.ai/state.json (default)

Concurrency Safety

1. Stale Lock Detection: Lock files older than 10 seconds are automatically removed
2. Atomic Writes: Uses temporary file + os.replace() to ensure atomic operations
3. File Locking: Uses portalocker for cross-platform file locking

The "Elicitation" Pattern

When ask_user=True is set in update_state, the read_state output appends:

🚨 PREVIOUS AGENT REQUESTED HUMAN INPUT.

This ensures subsequent agents know that human intervention is needed.

Philosophy

• Correctness: State must never be lost or corrupted by race conditions
• Completeness: All CRUD operations for context are available
• Resilience: Self-heals from stale locks caused by crashed agents

CLI Usage

Amicus includes CLI commands for inspection and validation. Run amicus-mcp --help to see all available options.

Getting Help

amicus-mcp --help

Shows all available CLI commands with usage examples.

List Available Tools

amicus-mcp --list-tools

Shows all MCP tools with their parameters and descriptions.

List Available Prompts

amicus-mcp --list-prompts

Shows all MCP prompts available for use.

Validate Environment

amicus-mcp --validate-env

Validates your environment configuration:

• Checks if CONTEXT_BUS_DIR is set
• Verifies the context directory exists and is accessible
• Shows state file status and age
• Checks tracking configuration
• Verifies .gitignore setup

Show Current State

amicus-mcp --show-state

Displays the current context bus state without starting the MCP server. Useful for debugging or checking what state other agents will see.

Display Audit Prompt

amicus-mcp --audit-prompt

Displays the comprehensive audit prompt that can be used with strongly-thinking models to perform a thorough evaluation of the project. You can pipe this directly to Claude or copy it for analysis:

# Display and copy to clipboard (macOS)
amicus-mcp --audit-prompt | pbcopy

# Pipe to a file for later use
amicus-mcp --audit-prompt > audit-request.md

Quality & Testing

Comprehensive Audit

The project includes a comprehensive audit prompt designed for use with strongly-thinking models. This prompt provides deep analysis across multiple dimensions:

• Code quality and architecture
• Security vulnerabilities
• Testing strategies
• Multi-agent coordination patterns
• Reliability and performance
• Developer experience
• Operational readiness

To run an audit:

One-Line Launch Prompt:

Perform a comprehensive audit of the Amicus MCP Server project following the framework in prompts/comprehensive-audit.md: analyze code quality, security vulnerabilities, architectural design, testing strategy, multi-agent coordination patterns, performance, and provide a scorecard with prioritized recommendations including implementation guides and test examples.

Using the CLI:

# Display the audit prompt
amicus-mcp --audit-prompt

# Copy to clipboard
amicus-mcp --audit-prompt | pbcopy

# View the full framework
cat prompts/comprehensive-audit.md

See prompts/LAUNCH.md and prompts/README.md for detailed usage instructions.

Development

Running the Server

uv run -m amicus

Or directly with Python:

python3 -m amicus

Or using the installed command:

amicus-mcp

Project Structure

amicus-mcp/
├── src/
│   └── amicus/         # Main package
├── pyproject.toml      # Project dependencies
├── README.md           # This file
└── TASKS.md            # Active task list

Requirements

• Python 3.10+
• fastmcp >= 0.2.0
• portalocker >= 2.8.2

License

MIT