# 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)

```bash
uv pip install -e .
```

### Using pip

```bash
pip install -e .
```

## Configuration

Add Amicus to your `.github/mcp.json`:

```json
{
  "mcpServers": {
    "amicus": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/amicus-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "CONTEXT_BUS_DIR": "${workspaceFolder}/.ai"
      }
    }
  }
}
```

Alternatively, if you have the package installed globally:

```json
{
  "mcpServers": {
    "amicus": {
      "command": "python",
      "args": ["-m", "server"],
      "env": {
        "CONTEXT_BUS_DIR": "${workspaceFolder}/.ai"
      }
    }
  }
}
```

## 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:**
```python
update_state(
    summary="Implemented user authentication",
    next_steps="Add password reset functionality",
    active_files=["src/auth.py", "tests/test_auth.py"],
    ask_user=False
)
```

### `read_state`

Read the current state from the context bus.

**Returns:** Formatted string containing the current state

**Example Output:**
```
📋 Context Bus State
==================================================

**Summary:**
Implemented user authentication

**Next Steps:**
Add password reset functionality

**Active Files:**
  - src/auth.py
  - tests/test_auth.py

**Last Updated:** 12.3 seconds ago
```

### `toggle_tracking`

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

**Parameters:**
- `enabled` (boolean): Whether tracking should be enabled

**Example:**
```python
toggle_tracking(enabled=False)  # Disable tracking
toggle_tracking(enabled=True)   # Re-enable tracking
```

## 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:

```
🚨 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 server.py
```

Or directly with Python:

```bash
python server.py
```

Or using the installed command:

```bash
amicus-mcp
```

### Project Structure

```
amicus-mcp/
├── server.py           # Main MCP server implementation
├── pyproject.toml      # Project dependencies
├── README.md           # This file
└── SPECIFICATION.md    # Original project specification
```

## Requirements

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

## License

MIT