# 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
[](https://glama.ai/mcp/connector/install?url=https%3A%2F%2Fraw.githubusercontent.com%2Famicus-mcp%2Famicus%2Fmain%2Fmcp-config.json)
### CLI (Universal)
```bash
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:
```bash
# 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](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](docs/IDE_INTEGRATION.md)**.
<details>
<summary><b>Quick Setup: Cursor</b></summary>
1. Go to **Settings > Cursor Settings > MCP**.
2. Click **+ Add New MCP Server**.
3. Name: `Amicus`
4. Type: `command`
5. Command: `uvx amicus-mcp`
</details>
<details>
<summary><b>Quick Setup: Windsurf</b></summary>
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "uv",
"args": ["tool", "run", "amicus-mcp"],
"env": {
"CONTEXT_BUS_DIR": "/path/to/your/project/.ai"
}
}
}
}
```
</details>
<details>
<summary><b>Quick Setup: Claude Desktop</b></summary>
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"amicus": {
"command": "uv",
"args": ["tool", "run", "amicus-mcp"]
}
}
}
```
</details>
## 🎯 Quick Start
Once installed, here's how to get started with Amicus in your project:
### 1. Initialize Your Project
```bash
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):**
```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):**
```python
# 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:
```bash
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:
```bash
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
```python
# 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](docs/ANTI_IDLE_SYSTEM.md) - Complete implementation details
- [SYNAPSE_PROTOCOL.md](prompts/SYNAPSE_PROTOCOL.md) - Worker node lifecycle protocol
- [BOOTSTRAP_MANAGER.md](prompts/BOOTSTRAP_MANAGER.md) - Manager coordination protocol
### Demo
Run the interactive demonstration:
```bash
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](SECURITY.md) for details on:
* Filesystem Sandboxing
* Command Whitelisting
## Usage Examples
### Updating State
```python
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
```bash
amicus-mcp --help
```
Shows all available CLI commands with usage examples.
### List Available Tools
```bash
amicus-mcp --list-tools
```
Shows all MCP tools with their parameters and descriptions.
### List Available Prompts
```bash
amicus-mcp --list-prompts
```
Shows all MCP prompts available for use.
### Validate Environment
```bash
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
```bash
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
```bash
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:
```bash
# 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:**
```bash
# 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`](prompts/LAUNCH.md) and [`prompts/README.md`](prompts/README.md) for detailed usage instructions.
## Development
### Running the Server
```bash
uv run -m amicus
```
Or directly with Python:
```bash
python3 -m amicus
```
Or using the installed command:
```bash
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
