Skip to main content
Glama
earchibald

Amicus MCP Server

by earchibald
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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)

uv pip install -e .

Using pip

pip install -e .

Configuration

Add Amicus to your .github/mcp.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:

{
  "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:

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:

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

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

Or directly with Python:

python server.py

Or using the installed command:

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

Available Tools

3 tools
read_stateB

Read the current state from the context bus.

Returns: The current state as a formatted string

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool reads and returns state, but doesn't describe what 'state' encompasses, whether it's cached or real-time, if there are permissions or rate limits, or what happens on errors. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately concise with two sentences that directly state the action and return value. It's front-loaded with the primary purpose and avoids unnecessary elaboration, though it could be slightly more structured by explicitly labeling sections like 'Purpose' and 'Returns'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 0 parameters, 100% schema coverage, and an output schema exists (so return values don't need explanation in the description), the description is minimally adequate. However, it lacks context about what 'state' means, how it relates to siblings, or behavioral details, making it incomplete for full understanding despite the structured data support.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description appropriately doesn't add parameter information beyond what's in the schema, maintaining a baseline score of 4 for zero-parameter tools as per guidelines.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Read') and resource ('current state from the context bus'), making it immediately understandable. However, it doesn't explicitly differentiate from its sibling tools (toggle_tracking, update_state), which would require mentioning that this is a read-only operation versus their likely mutation functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention its read-only nature in contrast to update_state (which likely modifies state) or toggle_tracking (which likely changes tracking behavior), nor does it specify prerequisites or contextual triggers for invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

toggle_trackingB

Enable or disable state tracking.

Args: enabled: Whether tracking should be enabled

Returns: Success message

ParametersJSON Schema
NameRequiredDescriptionDefault
enabledYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool enables or disables tracking but doesn't describe what 'state tracking' entails, whether this requires specific permissions, if changes are reversible, potential side effects, or rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first. The Args and Returns sections are structured clearly, though they could be integrated more seamlessly. There's minimal waste, but the formatting as separate lines might slightly reduce flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (a toggle operation with one parameter), no annotations, and an output schema present (which handles return values), the description is minimally adequate. It covers the basic purpose and parameter meaning but lacks details on behavioral traits, usage context, and integration with sibling tools, leaving room for improvement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context for the single parameter 'enabled' by explaining it determines 'Whether tracking should be enabled.' This clarifies the boolean's purpose beyond the schema's type definition. With 0% schema description coverage and only one parameter, the description adequately compensates, though it could specify default states or effects more explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Enable or disable state tracking.' This is a specific verb+resource combination that indicates a toggle action on tracking functionality. However, it doesn't explicitly differentiate from sibling tools like 'read_state' or 'update_state' which might handle related but different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'read_state' or 'update_state', nor does it specify prerequisites, contexts, or exclusions for usage. The agent must infer usage from the tool name and description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_stateB

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

Args: summary: A summary of what has been done so far next_steps: What needs to be done next active_files: List of files currently being worked on ask_user: Whether human input is required

Returns: Success message

ParametersJSON Schema
NameRequiredDescriptionDefault
summaryYes
next_stepsYes
active_filesYes
ask_userNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It states this is an update operation (implying mutation) and mentions a success message return, but lacks critical behavioral details: required permissions, whether changes are reversible, rate limits, or side effects. For a state-mutation tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a purpose statement followed by categorized Arg and Return sections. Each sentence earns its place by defining the tool and its parameters. It could be slightly more front-loaded by integrating parameter hints into the main description, but overall it's well-organized and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, 0% schema description coverage, but an output schema exists (implied by 'Returns: Success message'), the description is moderately complete. It covers all parameters semantically and states the return, but for a state-update tool, it should more explicitly address mutation behavior, idempotency, or error cases to be fully adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates well by explaining all 4 parameters in the 'Args' section with clear semantic meaning (e.g., 'summary: A summary of what has been done so far'). It adds value beyond the bare schema types, though it doesn't detail format constraints or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update the context bus state') and specifies what is being updated ('with the current agent's information'). It distinguishes from sibling 'read_state' by being a write operation, though it doesn't explicitly contrast with 'toggle_tracking'. The purpose is specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'read_state' or 'toggle_tracking'. The description implies it's for updating state with agent information, but doesn't specify scenarios, prerequisites, or exclusions. Usage context is left entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.2.0
    • First observedread_state
    • First observedtoggle_tracking
    • First observedupdate_state
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: read_state retrieves current state, toggle_tracking controls tracking functionality, and update_state modifies state with agent information. There is no overlap in functionality between these three tools.

Naming Consistency5/5

All tools follow a consistent verb_noun naming pattern (read_state, toggle_tracking, update_state) with perfect consistency. The naming convention is clear, predictable, and follows the same structure throughout.

Tool Count3/5

With only 3 tools, this feels somewhat thin for a context management server. While the tools cover basic state operations, the limited count suggests potential gaps in functionality that agents might need for comprehensive context management.

Completeness3/5

The tools provide read, update, and tracking control for state management, but there are notable gaps. Missing operations include clearing/resetting state, managing state history, or handling multiple contexts. The surface covers basic needs but lacks comprehensive lifecycle management.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/earchibald/amicus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server