### A2AMCP Development Setup

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

Provides instructions for setting up the A2AMCP development environment. This includes cloning the repository, installing Python dependencies, running tests, and starting the development server using Docker Compose.

```bash
# Clone repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest

# Start development server
docker-compose -f docker-compose.dev.yml up
```

--------------------------------

### Start Docker with Debug Profile for Redis UI

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Launches Docker containers with a debug profile, including the Redis Commander UI. Access `http://localhost:8081` to visually inspect and manage Redis data, aiding in troubleshooting.

```bash
docker-compose --profile debug up -d
```

--------------------------------

### Start A2AMCP Docker Containers

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Starts the A2AMCP server and Redis Docker containers in detached mode. This sets up the core components for the SplitMind platform's agent communication.

```bash
docker-compose up -d
```

--------------------------------

### Verify A2AMCP Server Installation

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

These commands allow users to verify the successful installation and functionality of the A2AMCP server. The first command lists all configured MCP servers, and the second tests a specific server instance.

```bash
claude mcp list

# Test the A2AMCP server
claude mcp test splitmind-a2amcp
```

--------------------------------

### A2AMCP Agent Coordination Commands in Claude Code

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

These examples demonstrate how to interact with the A2AMCP server directly within Claude Code prompts. They show commands for registering agents, retrieving active agents, sending messages between agents, and marking tasks as completed.

```Claude Code Prompt
@splitmind-a2amcp register_agent project_id="my-project" session_name="frontend-agent" task_id="TASK-001" branch="feature/ui" description="Building user interface"

@splitmind-a2amcp get_active_agents project_id="my-project"

@splitmind-a2amcp send_message project_id="my-project" from_session="frontend-agent" to_session="backend-agent" message="What's the user API endpoint?"

@splitmind-a2amcp mark_task_completed project_id="my-project" session_name="frontend-agent" task_id="TASK-001"
```

--------------------------------

### A2AMCP Server API Tools Reference

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Documents the 16+ A2AMCP API tools implemented by the server using the modern MCP SDK. These tools facilitate agent management, communication, file coordination, and task completion, leveraging `@server.list_tools()` and `@server.call_tool()` for robust functionality.

```APIDOC
Agent Management:
  register_agent - Register an agent for a project
  unregister_agent - Unregister an agent when done
  list_active_agents - List all active agents
  heartbeat - Keep agent alive

Todo Management:
  add_todo - Add a todo item
  update_todo - Update todo status
  get_my_todos - Get agent's todos

Communication:
  query_agent - Send query to another agent
  check_messages - Check and retrieve messages
  respond_to_query - Respond to a specific query

File Coordination:
  announce_file_change - Lock a file before editing
  release_file_lock - Release file lock after editing
  get_recent_changes - Get recent file changes

Shared Definitions:
  register_interface - Share a type/interface definition
  query_interface - Get shared interface definition
  list_interfaces - List all shared interfaces

Task Completion:
  mark_task_completed - Signal task completion to orchestrator
```

--------------------------------

### Quick Start with Docker for A2AMCP Server

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

This snippet provides the commands to quickly set up and verify the A2AMCP server using Docker. It involves cloning the repository, starting the server with docker-compose, and verifying its running status and connection.

```bash
# Clone the repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP

# Start the server
docker-compose up -d

# Verify it's running
docker ps | grep splitmind

# Test the connection
python verify_mcp.py
```

--------------------------------

### Check A2AMCP Server Logs

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Displays the real-time logs of the `splitmind-mcp-server` container. Use this to monitor server activity, debug issues, and observe agent interactions.

```bash
docker logs splitmind-mcp-server
```

--------------------------------

### Customize A2AMCP Server with Environment Variables

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command demonstrates how to add the A2AMCP server while customizing its behavior using additional environment variables. It shows examples for setting `REDIS_URL`, `LOG_LEVEL`, and `HEARTBEAT_TIMEOUT`.

```bash
claude mcp add splitmind-a2amcp \
  -e REDIS_URL=redis://localhost:6379 \
  -e LOG_LEVEL=DEBUG \
  -e HEARTBEAT_TIMEOUT=300 \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### Verify Running SplitMind Containers

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Checks if the `splitmind-mcp-server` and `splitmind-redis` containers are actively running. This confirms the server infrastructure is operational.

```bash
docker ps | grep splitmind
```

--------------------------------

### Run A2AMCP Endpoint Test Script

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Executes the Python test script to validate all implemented A2AMCP server endpoints. This ensures the server's functionality and API compliance.

```python
python test_endpoints.py
```

--------------------------------

### Python Example: Register Agent

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/docs/REFERENCE.md

Python code example demonstrating how to call the `register_agent` function with sample parameters for an e-commerce project, registering a task to implement user authentication.

```python
register_agent("ecommerce", "task-001", "001", "feature/auth", "Implement user authentication")
```

--------------------------------

### Example: Registering an Agent in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Demonstrates how to call the `register_agent` function with required parameters to set up an agent's session.

```python
register_agent(
    "ecommerce-v2",
    "task-auth-001",
    "001",
    "feature/authentication",
    "Implement user authentication with JWT tokens"
)
```

--------------------------------

### Bash: Deploying A2AMCP with Docker Compose

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-paper.md

This snippet provides the commands to quickly deploy the A2AMCP server using Docker Compose. It covers cloning the repository, navigating into the project directory, starting the server in detached mode, and verifying that the 'a2amcp-server' container is running, enabling rapid setup for development or production environments.

```bash
# Clone the repository
git clone https://github.com/webdevtodayjason/A2AMCP
cd A2AMCP

# Start the server
docker-compose up -d

# Verify it's running
docker ps | grep a2amcp-server
```

--------------------------------

### Initialize and Run a Basic A2AMCP Agent

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This example demonstrates how to set up and run a basic A2AMCP agent. It covers client and project initialization, agent creation, adding and completing todos, and coordinating file access with automatic locking and release.

```python
import asyncio
from a2amcp import A2AMCPClient, Project, Agent

async def main():
    # Initialize client and project
    client = A2AMCPClient("localhost:5000")
    project = Project(client, "my-project")
    
    # Create and run an agent
    async with Agent(
        project=project,
        task_id="001",
        branch="feature/auth",
        description="Build authentication"
    ) as agent:
        # Add todos
        todo_id = await agent.todos.add("Implement login", priority=1)
        
        # Work with files
        async with agent.files.coordinate("src/auth.py") as file:
            # File is locked
            print(f"Working on {file}")
        # File automatically released
        
        # Mark todo complete
        await agent.todos.complete(todo_id)

asyncio.run(main())
```

--------------------------------

### Install A2AMCP Python SDK

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This snippet shows how to install the A2AMCP Python SDK using pip, the standard Python package installer. It ensures all necessary dependencies are downloaded and configured for use.

```bash
pip install a2amcp
```

--------------------------------

### Open Claude Code Configuration File

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command opens the Claude Code configuration file for manual editing. It allows users to directly modify settings like `mcpServers`.

```bash
claude config edit
```

--------------------------------

### Frontend Agent Initial Registration Example

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

A partial Python script showing the initial steps for a frontend agent. It demonstrates how the agent registers itself within a project to begin work on a specific feature, such as building a login interface.

```python
# Frontend agent starting work
project_id = "ecommerce-v2"
session_name = "task-frontend-003"

# 1. Register
register_agent(project_id, session_name, "003", "feature/login-ui", "Build login interface")
```

--------------------------------

### Run A2AMCP Server Locally

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Instruction to start the A2AMCP server locally using the `mcp_server_redis.py` script, connecting to the Redis instance.

```bash
python mcp_server_redis.py
```

--------------------------------

### Add A2AMCP for Documentation Project Coordination

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command adds an A2AMCP server instance for coordinating multiple agents working on interconnected documentation projects. It sets a `PROJECT_ID` for the documentation effort.

```bash
claude mcp add a2amcp-docs \
  -e PROJECT_ID=documentation \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### Prompt Formatting for MCP Instructions

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/MCP_CLAUDE_INtAGRATION.md

This snippet shows a basic example of how to format a prompt string to include references to MCP setup instructions and a specific task prompt, typically used when preparing input for an agent.

```python
prompt = f"Read {instructions_file} for MCP setup instructions. {task_prompt}"
```

--------------------------------

### Install Python Dependencies for A2AMCP Development

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Commands to install both core and development Python dependencies for A2AMCP from `requirements.txt` and `requirements-dev.txt` using pip.

```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

--------------------------------

### Manage Agent Todos in A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This example demonstrates how to manage tasks (todos) for an A2AMCP agent. It covers adding new todos with priorities, updating their status (start, complete), and retrieving all todos associated with a project.

```python
# Add todos
todo1 = await agent.todos.add("Design schema", priority=1)
todo2 = await agent.todos.add("Write tests", priority=2)

# Update status
await agent.todos.start(todo1)
await agent.todos.complete(todo1)

# Check all todos in project
all_todos = await project.todos.get_all()
```

--------------------------------

### Install A2AMCP Python SDK

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

This command installs the A2AMCP Python SDK using pip, allowing Python applications to interact with the A2AMCP server.

```bash
pip install a2amcp-sdk
```

--------------------------------

### Configure Claude Desktop for A2AMCP Server

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/SETUP.md

Adds a new MCP server configuration to Claude Desktop's settings. This entry directs Claude Desktop to connect to the A2AMCP server running within its Docker container, specifying the execution command and Redis URL.

```json
{
  "mcpServers": {
    "splitmind-a2amcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "splitmind-mcp-server",
        "python",
        "/app/mcp-server-redis.py"
      ],
      "env": {
        "REDIS_URL": "redis://redis:6379"
      }
    }
  }
}
```

--------------------------------

### Complete Authentication Agent Workflow Example

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

A comprehensive Python script demonstrating an authentication agent's lifecycle. It covers agent registration, task management (todos), file change announcements, interface registration, inter-agent communication (heartbeats, messages), and task completion.

```python
# Start of authentication agent
project_id = "ecommerce-v2"
session_name = "task-auth-001"

# 1. Register
register_agent(project_id, session_name, "001", "feature/auth", "Build authentication system")

# 2. Create todo list
todos = [
    ("Research JWT best practices", 1),
    ("Design User schema", 1),
    ("Implement password hashing", 1),
    ("Create login endpoint", 2),
    ("Create register endpoint", 2),
    ("Add authentication middleware", 2),
    ("Write tests", 3)
]

todo_ids = []
for text, priority in todos:
    result = add_todo(project_id, session_name, text, priority)
    todo_ids.append(result['todo_id'])

# 3. Start working
update_todo(project_id, session_name, todo_ids[0], "in_progress")

# 4. Check who else is active
agents = list_active_agents(project_id)
print(f"Working with {len(agents) - 1} other agents")

# 5. Create User model
result = announce_file_change(
    project_id, 
    session_name,
    "src/models/user.ts",
    "create",
    "Creating User model with authentication fields"
)

if result['status'] == 'locked':
    # Create the file...
    # Then register the interface
    register_interface(
        project_id,
        session_name,
        "User",
        """interface User {
  id: string;
  email: string;
  password: string;  // bcrypt hashed
  role: 'admin' | 'user' | 'guest';
  emailVerified: boolean;
  createdAt: Date;
  updatedAt: Date;
}""",
        "src/models/user.ts"
    )
    
    # Release the lock
    release_file_lock(project_id, session_name, "src/models/user.ts")
    
    # Update todo
    update_todo(project_id, session_name, todo_ids[1], "completed")
    
    # Broadcast completion
    broadcast_message(
        project_id,
        session_name,
        "info",
        "User model is ready! Interface 'User' is now available."
    )

# 6. Periodically check messages and send heartbeat
import time
while working:
    # Send heartbeat
    heartbeat(project_id, session_name)
    
    # Check messages
    messages = check_messages(project_id, session_name)
    for msg in messages:
        if msg['type'] == 'query':
            if 'User' in msg['content']:
                respond_to_query(
                    project_id,
                    session_name,
                    msg['from'],
                    msg['id'],
                    "User interface has: id, email, password (hashed), role, emailVerified, timestamps"
                )
    
    time.sleep(30)

# 7. Complete task
unregister_agent(project_id, session_name)
```

--------------------------------

### Add A2AMCP for Microservices Coordination

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command adds an A2AMCP server instance specifically for coordinating multiple agents involved in microservices development. It sets a `PROJECT_ID` for the microservices project.

```bash
claude mcp add a2amcp-microservices \
  -e PROJECT_ID=my-microservices \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### A2AMCP Development After SDK Integration

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This example demonstrates the simplified development workflow with the A2AMCP SDK. It shows how to initialize a project, spawn agents, and monitor project completion with significantly less code, showcasing the SDK's ability to abstract away complexity and improve developer productivity.

```python
from a2amcp import Project, spawn_agents

async def build_app(tasks):
    project = Project("my-app")
    agents = await spawn_agents(project, tasks)
    
    await project.monitor_until_complete()
    print(f"✅ Built by {len(agents)} agents")
```

--------------------------------

### Create Python Virtual Environment for A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Steps to create and activate a Python virtual environment, isolating project dependencies from the system Python installation for A2AMCP development.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### Add A2AMCP for Full-Stack Application Coordination

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command adds an A2AMCP server instance to facilitate coordination between frontend and backend agents in a full-stack application development scenario. It assigns a `PROJECT_ID` for the application.

```bash
claude mcp add a2amcp-fullstack \
  -e PROJECT_ID=my-app \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### A2AMCP Orchestrator Integration Example

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/docs/ARCHITECtURE.md

Demonstrates how to initialize an A2AMCP client and project, and use the AgentSpawner to launch multiple agents. This snippet illustrates the basic steps for integrating the A2AMCP system with an external orchestrator for managing agent lifecycles.

```python
from a2amcp import A2AMCPClient, Project, AgentSpawner

client = A2AMCPClient("localhost:5000")
project = Project(client, "my-app")
spawner = AgentSpawner(project)

# Spawn agents with A2AMCP awareness
sessions = await spawner.spawn_multiple(tasks, worktree_base)
```

--------------------------------

### Example: Listing Active Agents in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Shows how to call `list_active_agents` and iterate through the returned dictionary to display information about each active agent.

```python
agents = list_active_agents("ecommerce-v2")
print(f"Active agents: {len(agents)}")
for session, info in agents.items():
    print(f"  {session}: {info['description']}")
```

--------------------------------

### Resolve Docker Permission Issues

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command addresses Docker permission issues by adding the current user to the `docker` group. It requires logging out and back in for the changes to take effect, ensuring Docker is accessible.

```bash
# Ensure Docker is accessible
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect
```

--------------------------------

### Install A2AMCP JavaScript/TypeScript SDK

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

This command installs the A2AMCP JavaScript/TypeScript SDK using npm, enabling Node.js or browser-based applications to communicate with the A2AMCP server. Note that this SDK is currently under development.

```bash
npm install @a2amcp/sdk
```

--------------------------------

### Troubleshoot A2AMCP Server Not Responding

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

These commands help diagnose issues when the A2AMCP server is not responding. They allow checking Docker container status, viewing server logs, and testing the Redis connection.

```bash
# Check if Docker containers are running
docker ps | grep splitmind

# View server logs
docker logs splitmind-mcp-server

# Test Redis connection
docker exec splitmind-redis redis-cli ping
```

--------------------------------

### Traditional Agentic Framework for Sequential Development

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-comparison.md

This Python example demonstrates a typical setup for an agentic framework where all agents operate within a single process. It highlights the sequential nature of their work, where agents take turns, and the vulnerability of the entire process to a single point of failure.

```python
# Everything in one process
crew = Crew(
    agents=[
        Agent(role="Backend Developer"),
        Agent(role="Frontend Developer"),
        Agent(role="Database Designer")
    ]
)
# They take turns, can't work simultaneously on files
# If it crashes, all work stops
```

--------------------------------

### Example: Adding Multiple Todo Items in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Illustrates how an agent can break down its main task into multiple, prioritized todo items using the `add_todo` function.

```python
# Break down your task into todos
add_todo("ecommerce-v2", "task-auth-001", "Research JWT best practices", 1)
add_todo("ecommerce-v2", "task-auth-001", "Design User database schema", 1)
add_todo("ecommerce-v2", "task-auth-001", "Implement password hashing", 1)
add_todo("ecommerce-v2", "task-auth-001", "Create login endpoint", 2)
add_todo("ecommerce-v2", "task-auth-001", "Write authentication tests", 2)
```

--------------------------------

### Configure A2AMCP Server in Claude Code JSON

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This JSON snippet defines the configuration for the `splitmind-a2amcp` server within the `mcpServers` section of the Claude Code configuration. It specifies the Docker command, arguments, and environment variables for the server.

```json
{
  "mcpServers": {
    "splitmind-a2amcp": {
      "command": "docker",
      "args": ["exec", "-i", "splitmind-mcp-server", "python", "/app/mcp-server-redis.py"],
      "env": {
        "REDIS_URL": "redis://redis:6379"
      }
    }
  }
}
```

--------------------------------

### Start Redis Service with Docker Compose for A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Command to start the Redis service required by A2AMCP using Docker Compose in detached mode, ensuring the database is running for local development.

```bash
docker-compose up -d redis
```

--------------------------------

### Python: Registering an AI Agent and Adding To-Dos

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-paper.md

This snippet demonstrates how an AI agent registers itself with the A2AMCP system and adds specific tasks (to-dos) to its work queue. It shows the initial setup for an authentication agent in an e-commerce project, outlining its responsibilities like creating a User model and implementing JWT tokens.

```python
register_agent("ecommerce-v2", "task-auth-001", "001", "feature/auth", "Build authentication")
add_todo("ecommerce-v2", "task-auth-001", "Create User model", 1)
add_todo("ecommerce-v2", "task-auth-001", "Implement JWT tokens", 1)
```

--------------------------------

### Multi-Agent Coordination Data Flow Example

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/HOW_IT_WORKS.md

This example illustrates a typical sequence of interactions between multiple agents and the MCP server. It demonstrates how agents register, manage tasks, share interfaces, and coordinate their activities over time to achieve project goals without conflicts.

```text
Time 0: Project "ecommerce-v2" starts
        └── MCP Server already running in Docker

Time 1: Agent task-001 (auth) starts
        ├── Registers with MCP
        ├── Creates 5 todos
        └── Starts working

Time 2: Agent task-002 (profile) starts
        ├── Registers with MCP
        ├── Sees task-001 is active
        ├── Checks task-001's todos
        └── Sees "Create User model" is pending

Time 3: Agent task-001 completes User model
        ├── Updates todo to "completed"
        ├── Registers interface "User"
        └── Broadcasts completion

Time 4: Agent task-002 queries
        ├── "What's the User interface?"
        └── Gets immediate response

Time 5: Both agents coordinate
        ├── task-001: "I'll do auth endpoints"
        ├── task-002: "I'll do profile endpoints"
        └── No conflicts!
```

--------------------------------

### Example: Sending Heartbeat in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Illustrates how to integrate the `heartbeat` call into an agent's main loop to maintain its active status.

```python
import time
while working:
    heartbeat("ecommerce-v2", "task-auth-001")
    time.sleep(30)
```

--------------------------------

### A2AMCP Project Directory Structure

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Illustrates the hierarchical directory structure of the A2AMCP project, highlighting key components like the server, Docker configuration, documentation, SDKs, tests, and examples.

```APIDOC
A2AMCP/
├── mcp_server_redis.py    # Core MCP server implementation
├── docker-compose.yml     # Docker configuration
├── docs/                  # Documentation
│   ├── API_REFERENCE.md   # API documentation
│   └── ARCHITECTURE.md    # Architecture overview
├── sdk/                   # SDKs for different languages
│   ├── python/           # Python SDK
│   ├── javascript/       # JavaScript/TypeScript SDK (planned)
│   └── TODO.md          # SDK development tracking
├── tests/                # Test suite
└── examples/            # Usage examples
```

--------------------------------

### Example: Unregistering an Agent in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Demonstrates how to call `unregister_agent` when an agent's task is finished and how to access the returned completion summary.

```python
# When agent completes its task
result = unregister_agent("ecommerce-v2", "task-auth-001")
print(f"Task complete: {result['message']}")
```

--------------------------------

### TypeScript SDK: Orchestrator Agent Creation and Interaction

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This TypeScript example illustrates agent creation using a builder pattern, specifying tasks, dependencies, and shared interfaces. It covers spawning agents with retry mechanisms and custom event handlers for progress and conflict resolution, and demonstrates high-level queries to retrieve interfaces and interact with other agents.

```typescript
import { A2AMCPClient, Project, AgentBuilder } from '@a2amcp/sdk';

const client = new A2AMCPClient('localhost:5000');
const project = new Project(client, 'ecommerce-v2');

// Typed agent creation
const agent = new AgentBuilder(project)
  .withTask({
    id: '001',
    branch: 'feature/auth',
    description: 'Build authentication'
  })
  .withDependencies(['database-setup'])
  .withSharedInterfaces(['User', 'AuthToken'])
  .build();

// Spawn with auto-retry and monitoring
await agent.spawn({
  retries: 3,
  onProgress: (todo) => console.log(`✓ ${todo.text}`),
  onConflict: async (conflict) => {
    // SDK provides conflict resolution helpers
    await conflict.negotiate({
      strategy: 'wait',
      maxWait: 60
    });
  }
});

// High-level queries
const userInterface = await project.interfaces.get('User');
const authAgent = await project.agents.find('task-auth-001');
const response = await authAgent.query({
  type: 'api',
  question: 'What endpoints are available?',
  timeout: 30
});
```

--------------------------------

### A2AMCP SDK Project Directory Structure

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/TODO.md

Defines the standard directory layout for the A2AMCP SDK project, categorizing different language SDKs, documentation, testing, and examples.

```plaintext
sdk/
├── TODO.md (this file)
├── python/           ✅ In Progress
├── javascript/       📋 Planned
├── cli/             📋 Planned
├── go/              🔮 Future
├── testing/         📋 Planned
├── integrations/    🔮 Future
└── examples/        ✅ In Progress
```

--------------------------------

### Coordinate Multiple Agents and Register API Contracts

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

This example illustrates how an API agent can coordinate with other agents (auth, database) within a project. It covers registering an agent, listing available interfaces, finding specific agents based on their descriptions, querying multiple agents for information, registering API contracts for shared use, and handling file conflicts when working on shared resources.

```python
# API agent needs to coordinate with both auth and database agents
project_id = "ecommerce-v2"
session_name = "task-api-004"

# 1. Register
register_agent(project_id, session_name, "004", "feature/user-api", "Build user management API")

# 2. Check all interfaces
interfaces = list_interfaces(project_id)
print(f"Available interfaces: {list(interfaces.keys())}")

# 3. See what everyone is working on
all_todos = get_all_todos(project_id)

# Find agents working on related features
auth_agent = None
db_agent = None

for agent, info in all_todos.items():
    if 'auth' in info['description'].lower():
        auth_agent = agent
    elif 'database' in info['description'].lower():
        db_agent = agent

# 4. Query multiple agents
if auth_agent:
    auth_response = query_agent(
        project_id,
        session_name,
        auth_agent,
        "interface",
        "What auth middleware should I use for protecting user endpoints?"
    )

if db_agent:
    db_response = query_agent(
        project_id,
        session_name,
        db_agent,
        "help",
        "What's the database connection pattern we're using?"
    )

# 5. Register API contracts for others to use
register_interface(
    project_id,
    session_name,
    "UserAPI",
    """interface UserAPI {\n  GET /api/users - List all users (admin only)\n  GET /api/users/:id - Get user by ID\n  PUT /api/users/:id - Update user\n  DELETE /api/users/:id - Delete user (admin only)\n  \n  All endpoints require Authorization: Bearer <token>\n}""",
    "src/routes/users.ts"
)

# 6. Check for conflicts before working on shared files
shared_files = ["src/app.ts", "src/routes/index.ts"]
for file_path in shared_files:
    result = announce_file_change(
        project_id,
        session_name,
        file_path,
        "modify",
        "Adding user routes to main app"
    )
    
    if result['status'] == 'conflict':
        # Someone else is working on it
        lock_info = result['lock_info']
        print(f"{file_path} is locked by {lock_info['session']}")
        print(f"They are: {lock_info['description']}")
        
        # Query them about timeline
        response = query_agent(
            project_id,
            session_name,
            lock_info['session'],
            "status",
            f"When will you be done with {file_path}? I need to add user routes."
        )
```

--------------------------------

### Perform Inter-Agent Communication in A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This example demonstrates various methods for inter-agent communication within A2AMCP. It covers querying specific agents, broadcasting messages to all agents, and checking for incoming messages.

```python
# Query another agent
response = await agent.communication.query(
    "task-002",
    "interface", 
    "What fields does User have?"
)

# Broadcast to all
await agent.communication.broadcast(
    "info",
    "User model updated with new fields"
)

# Check messages
messages = await agent.communication.check_messages()
```

--------------------------------

### A2AMCP SDK Real-time Event Streaming

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This example showcases the real-time event processing capabilities of the A2AMCP SDK. It demonstrates iterating through project events and using pattern matching to handle different event types, such as 'TodoCompleted', 'FileConflict', and 'InterfaceShared', enabling dynamic responses to system changes.

```python
async for event in project.events():
    match event:
        case TodoCompleted(agent, todo):
            update_dashboard(agent, todo)
        case FileConflict(file, agents):
            alert_orchestrator(file, agents)
        case InterfaceShared(name, definition):
            update_type_registry(name, definition)
```

--------------------------------

### Manage A2AMCP Agent Lifecycle Automatically

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This example highlights the automatic lifecycle management features of an A2AMCP agent. Using an async context manager, agents handle registration, heartbeats, message checking, and unregistration seamlessly.

```python
# Automatic lifecycle management
async with Agent(project, "001", "feature", "description") as agent:
    # Agent is registered and heartbeat is running
    pass
# Agent is automatically unregistered
```

--------------------------------

### API Documentation for Querying Registered Interfaces

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Details the 'query_interface' API endpoint, which retrieves a registered interface definition. It specifies required parameters, return formats for both found and not-found scenarios, and includes a Python example demonstrating its usage.

```APIDOC
query_interface(project_id: str, interface_name: str)
  project_id: Project identifier
  interface_name: Name of the interface to query

Returns (found):
  definition: string (e.g., "interface User { id: string; email: string; ... }")
  registered_by: string (e.g., "task-auth-001")
  file_path: string (e.g., "src/types/user.ts")
  timestamp: string (ISO 8601 datetime)

Returns (not found):
  status: string ("not_found")
  error: string (e.g., "Interface User not found")
  similar: array of string (e.g., ["UserProfile", "UserRole"])
```

```json
{
  "definition": "interface User { id: string; email: string; ... }",
  "registered_by": "task-auth-001",
  "file_path": "src/types/user.ts",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

```json
{
  "status": "not_found",
  "error": "Interface User not found",
  "similar": ["UserProfile", "UserRole"]
}
```

```python
# Get an interface definition
user_interface = query_interface("ecommerce-v2", "User")
if user_interface.get('status') != 'not_found':
    print(f"User interface: {user_interface['definition']}")
    print(f"Defined in: {user_interface['file_path']}")
else:
    # Interface doesn't exist yet
    similar = user_interface.get('similar', [])
    if similar:
        print(f"Did you mean: {', '.join(similar)}?")
```

--------------------------------

### A2AMCP Horizontal Scaling with Separate Sessions

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-comparison.md

This conceptual example demonstrates A2AMCP's approach to horizontal scaling. Agents run in separate `tmux` sessions, each with its own git worktree, communicating via Redis. This design naturally supports horizontal scaling and distributed operations.

```bash
# 20 agents in separate tmux sessions
# Each with its own git worktree
# Communicating through Redis
# Natural horizontal scaling
```

--------------------------------

### Handle Inter-Agent Messages and Events in A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

This example shows how an A2AMCP agent can define handlers for specific message types and events. It demonstrates processing incoming 'interface' queries and reacting to 'todo_completed' events, enabling dynamic agent behavior.

```python
from a2amcp import Agent

agent = Agent(project, "003", "feature/api", "Build API")

@agent.handles("interface")
async def handle_interface_query(message):
    if "User" in message['content']:
        return "User has: id, email, password, role"

@agent.on("todo_completed") 
async def on_todo_completed(event):
    print(f"Completed: {event['todo']['text']}")

async with agent:
    while True:
        await agent.process_messages()
        await asyncio.sleep(5)
```

--------------------------------

### A2AMCP SDK File Conflict Resolution

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This example illustrates how the A2AMCP SDK handles file conflicts using built-in strategies. It shows acquiring a file lock with a 'queue' strategy and a custom 'on_conflict' callback to query the lock owner, ensuring orderly access to shared resources and preventing data corruption.

```python
await agent.files.acquire('src/models/user.ts', 
    strategy='queue',  # Wait in line
    timeout=300,
    on_conflict=lambda lock: agent.query(
        lock.owner, 
        'status',
        f'When will {lock.file} be available?'
    )
)
```

--------------------------------

### Registering an Agent First in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Demonstrates the essential first step of registering an agent with the system, providing project, session, task, branch, and description details.

```python
# ALWAYS do this first
register_agent(project_id, session_name, task_id, branch, description)
```

--------------------------------

### Initialize MCP Server and Redis Containers

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/HOW_IT_WORKS.md

Instructions for developers to quickly start the MCP Server and Redis containers using `docker-compose`. This sets up the core communication infrastructure, making the MCP Server available on port 5000 and Redis on port 6379, with both networked together.

```bash
./quickstart.sh

# This starts:
docker-compose up -d
```

--------------------------------

### Resolve Redis Port Conflicts for A2AMCP

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command shows how to resolve Redis port conflicts by updating the `REDIS_URL` environment variable to use a different port, such as 6380, when adding the A2AMCP server.

```bash
claude mcp add splitmind-a2amcp \
  -e REDIS_URL=redis://localhost:6380 \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### Python SDK: Orchestrator Agent Spawning and Monitoring

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This Python snippet demonstrates how to initialize the A2AMCP client, create a project context, and spawn agents. It shows how to build task prompts with dependencies and shared interfaces, and how to set up event handlers for agent progress and interface registration, as well as project-level monitoring for conflicts and timeouts.

```python
from a2amcp import A2AMCPClient, Agent, Project, TaskPromptBuilder

# Initialize client
client = A2AMCPClient("localhost:5000")

# Create project context
project = Project("ecommerce-v2")

# High-level agent spawning
async def spawn_agent(task):
    agent = Agent(
        project=project,
        task_id=task['id'],
        branch=task['branch'],
        description=task['description']
    )
    
    # SDK generates optimal prompt with MCP instructions
    prompt = TaskPromptBuilder()\
        .with_task(task)\
        .with_dependencies(task.get('depends_on', []))\
        .with_shared_interfaces(['User', 'Product'])\
        .with_coordination_rules()\
        .build()
    
    # Spawn with monitoring
    session = await agent.spawn(prompt)
    
    # SDK provides event handlers
    @agent.on('todo_completed')
    def on_progress(todo):
        print(f"✓ {agent.session_name} completed: {todo['text']}")
    
    @agent.on('interface_registered')
    def on_interface(interface):
        print(f"📝 New interface available: {interface['name']}")
    
    return agent

# Monitor all agents
async def monitor_project():
    async with project.monitor() as monitor:
        async for event in monitor.events():
            if event.type == 'conflict':
                print(f"⚠️ Conflict: {event.agents} on {event.file}")
            elif event.type == 'query_timeout':
                print(f"⏱️ No response: {event.from_agent} → {event.to_agent}")
```

--------------------------------

### Clone A2AMCP Repository for Local Development

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

Instructions to clone the A2AMCP project repository from GitHub using Git, preparing the local environment for development.

```bash
git clone https://github.com/your-username/A2AMCP.git
cd A2AMCP
```

--------------------------------

### Add A2AMCP Server to Claude Code using CLI

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CLAUDE_CODE_SETUP.md

This command adds the A2AMCP server to Claude Code using the `claude mcp add` command. It specifies the server name `splitmind-a2amcp` and sets the `REDIS_URL` environment variable, executing the MCP server via Docker.

```bash
claude mcp add splitmind-a2amcp \
  -e REDIS_URL=redis://localhost:6379 \
  -- docker exec -i splitmind-mcp-server python /app/mcp-server-redis.py
```

--------------------------------

### Python Agent Helper Library: Task Implementation and Communication

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/PLAN.md

This Python snippet showcases the A2AMCP agent helper library, designed to be injected into agent contexts. It demonstrates automatic agent registration, lifecycle management, and the use of decorators for common patterns like `todo` and `handles`. It also illustrates high-level file coordination with automatic locking and sharing results via interface registration.

```python
# This would be available to agents through the prompt
from a2amcp_agent import A2AMCPAgent, coordinate, shared, todo

# Auto-registration and lifecycle management
agent = A2AMCPAgent.current()  # Auto-detects from environment

# Decorators for common patterns
@todo("Implement user authentication", priority=1)
async def implement_auth():
    # SDK handles todo updates automatically
    user_model = await agent.interfaces.require('User')
    
    # High-level file coordination
    async with coordinate.file('src/auth/login.ts') as file:
        # File automatically locked
        file.write(generate_login_code(user_model))
        # File automatically released
    
    # Share results
    await agent.interfaces.register('LoginResponse', {
        'token': 'string',
        'user': 'User',
        'expiresIn': 'number'
    })

# Simplified communication
@agent.handles('api_query')
async def handle_api_query(query):
    if 'login' in query.content:
        return {
            'endpoint': '/api/auth/login',
            'method': 'POST',
            'expects': {'email': 'string', 'password': 'string'}
        }

# Auto-heartbeat and cleanup handled by SDK
```

--------------------------------

### Direct MCP Tool Usage with Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

Illustrates direct interactions with MCP tools for agent registration, querying other agents, and sharing interfaces. This shows lower-level commands for direct protocol interaction compared to the SDK's higher-level abstractions.

```python
# Register agent
register_agent("my-project", "task-001", "001", "feature/auth", "Building authentication")

# Query another agent
query_agent("my-project", "task-001", "task-002", "interface", "What's the User schema?")

# Share interface
register_interface("my-project", "task-001", "User", "interface User {...}")
```

--------------------------------

### Generate Optimal Prompts with PromptBuilder

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/python/README.md

Demonstrates how to use the `PromptBuilder` class to construct complex prompts for agents, including task details, coordination rules, error recovery, and custom instructions.

```python
from a2amcp import PromptBuilder

prompt = PromptBuilder("project-id")\
    .with_task({
        "task_id": "001",
        "branch": "feature/auth",
        "description": "Build authentication",
        "depends_on": ["database"],
        "shared_interfaces": ["User", "Session"]
    })\
    .with_coordination_rules()\
    .with_error_recovery()\
    .add_instruction("Use bcrypt for passwords")\
    .build()
```

--------------------------------

### Python SDK Agent and File Coordination

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/README.md

Demonstrates how to use the A2AMCP Python SDK to create an agent, coordinate file access, and register interfaces. It shows agent registration, heartbeat maintenance, file locking, and interface sharing within an asynchronous context.

```python
from a2amcp import A2AMCPClient, Project, Agent

async def run_agent():
    client = A2AMCPClient("localhost:5000")
    project = Project(client, "my-app")
    
    async with Agent(project, "001", "feature/auth", "Build authentication") as agent:
        # Agent automatically registers and maintains heartbeat
        
        # Coordinate file access
        async with agent.files.coordinate("src/models/user.ts") as file:
            # File is locked, safe to modify
            pass
        # File automatically released
        
        # Share interfaces
        await project.interfaces.register(
            agent.session_name,
            "User",
            "interface User { id: string; email: string; }"
        )
```

--------------------------------

### Get Recent File Changes

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/docs/REFERENCE.md

Retrieves a log of recent file changes announced by all agents in the project. This provides an overview of ongoing development and modifications.

```APIDOC
get_recent_changes(
  project_id: str,
  limit: int = 20
)

Returns:
[
  {
    "session": "task-001",
    "file_path": "src/models/user.ts",
    "change_type": "create",
    "description": "Created User model with auth fields",
    "timestamp": "2024-01-15T10:45:00Z"
  }
]
```

--------------------------------

### Get All Project Todos

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/docs/REFERENCE.md

Retrieves todos for all agents within a specified project. This provides an aggregated view of tasks across the entire team or project.

```APIDOC
get_all_todos(
  project_id: str
)

Returns:
{
  "task-001": {
    "task_id": "001",
    "description": "Implement authentication",
    "total_todos": 5,
    "completed": 3,
    "todos": [...]
  },
  "task-002": {
    "task_id": "002",
    "description": "Create user profiles",
    "total_todos": 4,
    "completed": 1,
    "todos": [...]
  }
}
```

--------------------------------

### Python: Test Agent Registration with A2AMCP Server

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/CONTRIBUTING.md

This Python snippet demonstrates a unit test for an agent's registration functionality with the A2AMCP server. It initializes a client and project, creates an agent instance, attempts to register it, and then asserts the successful registration status and internal state of the agent.

```python
def test_agent_registration():
    """Test that agent can register with server"""
    # Arrange
    client = A2AMCPClient("localhost:5000")
    project = Project(client, "test-project")
    
    # Act
    agent = Agent(project, "001", "feature/test", "Test")
    result = await agent.register()
    
    # Assert
    assert result['status'] == 'registered'
    assert agent._registered is True
```

--------------------------------

### Creating Detailed and Actionable Todos in Python

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Compares good and bad practices for adding todos, emphasizing the importance of specific and actionable descriptions for better task management.

```python
# Good: Specific and actionable
add_todo(project_id, session_name, "Implement bcrypt password hashing with salt rounds=10", 1)

# Bad: Too vague
add_todo(project_id, session_name, "Do authentication", 1)
```

--------------------------------

### Get Agent's Own Todos

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/docs/REFERENCE.md

Retrieves a list of todos specific to the calling agent within a project. This allows an agent to manage its individual task list.

```APIDOC
get_my_todos(
  project_id: str,
  session_name: str
)

Returns:
{
  "session_name": "task-001",
  "total": 5,
  "todos": [
    {
      "id": "todo-1705320600.123",
      "text": "Research JWT best practices",
      "status": "completed",
      "priority": 1,
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

--------------------------------

### Go A2AMCP SDK Core Features Specification

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/sdk/TODO.md

Outlines the planned core functionalities for the Go SDK, focusing on native client implementation, concurrent agent management, connection pooling, and gRPC support for high-performance use cases.

```APIDOC
Core Features:
  - Native Go client
  - Concurrent agent management
  - Connection pooling
  - gRPC support
  - Kubernetes operator
```

--------------------------------

### APIDOC: Unregister Agent and Get Todo Summary

Source: https://github.com/webdevtodayjason/a2amcp/blob/main/a2amcp-api-reference.md

Unregisters an agent from the A2AMCP server, typically called when its task is complete, and provides a summary of its todo list completion.

```APIDOC
unregister_agent:
  Parameters:
    project_id (str): Project identifier
    session_name (str): Agent's session name
  Returns:
    {
      "status": "unregistered",
      "todo_summary": {
        "total": 5,
        "completed": 4,
        "pending": 1,
        "in_progress": 0
      },
      "message": "Successfully unregistered. Completed 4/5 todos."
    }
```