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

• 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: Respects CONTEXT_BUS_DIR environment variable

Installation

Using uv (recommended)

Using pip

Configuration

Add Amicus to your .github/mcp.json:

Alternatively, if you have the package installed globally:

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 (string): What needs to be done next

• active_files (list): List of files currently being worked on

• ask_user (boolean, optional): Whether human input is required

Example:

read_state

Read the current state from the context bus.

Returns: Formatted string containing the current state

Example Output:

toggle_tracking

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

Parameters:

• enabled (boolean): Whether tracking should be enabled

Example:

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.

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:

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

Shows all available CLI commands with usage examples.

List Available Tools

Shows all MCP tools with their parameters and descriptions.

List Available Prompts

Shows all MCP prompts available for use.

Validate Environment

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

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

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:

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:

Using the CLI:

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

Development

Running the Server

Or directly with Python:

Or using the installed command:

Project Structure

Requirements

• Python 3.10+

• fastmcp >= 0.2.0

• portalocker >= 2.8.2

License

MIT