Agent MCP

Agent MCP

A MCP for creating multi-agent systems using the MCP (Multi-Agent Collaboration Protocol) for coordinated, efficient AI collaboration.

Features

• Multi-agent collaboration framework
• Task management and coordination
• Context and knowledge sharing between agents
• Graph visualization of agent interactions
• Support for embedding and RAG capabilities
• Interactive dashboard for visualizing tasks, agents and context.

Project Planning with the Main Context Document (MCD)

Before starting development, it's essential to use deep research to create a Main Context Document (MCD) - the single source of truth for your application. This document provides a granular plan detailing:

• System architecture and component relationships
• UI/UX design for all screens and components
• API routes and endpoints
• Data structures and models
• Implementation units and tasks
• Dependencies and technology stack

The MCD is critical because:

1. It enables agents to understand the overall system before working on individual components
2. It allows linear, coordinated building (like constructing a house from blueprints)
3. It reduces token usage by providing structured, relevant context
4. It prevents conflicting implementations between agents

Review the MCD.md file in this repository to understand the structure and level of detail required. The MCD should contain:

• Overview and goals
• Context and architecture diagrams
• Functional requirements
• Design specifications (UI/UX, API, data models)
• Implementation details
• Task breakdown for agents

With a comprehensive MCD, agents can implement your application part-by-part with a clear understanding of how each piece fits into the whole.

Installation

Prerequisites

• Python 3.8+
• uv (recommended for faster package installation)

Setup

1. Clone the repository:

   git clone https://github.com/your-username/agent-mcp.git
   cd agent-mcp
   

2. Set up environment variables by copying the example file:

   cp .env.example .env
   

3. Edit the .env file and add your OpenAI API key:

   OPENAI_API_KEY=your_openai_api_key_here
   

4. Install using uv:

   uv venv
   uv pip install -e .
   

   Or with pip:

   pip install -e .
   

Multi-Agent Workflow

Architecture Overview

The MCP system uses a hierarchical structure with:

• Admin Agent: Coordinates other agents, assigns tasks, and maintains overall project direction
• Worker Agents: Specialized agents that execute specific tasks (frontend, backend, data modeling, etc.)

Agent Setup and Operation

1. Starting the MCP Server

uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project

Options:

• --port: Port to run the server on (default: 8080)
• --project-dir: Base directory for the project

2. Configure Admin Token

The admin token provides privileged access to the MCP server. You can set it in your .env file:

MCP_ADMIN_TOKEN=your_custom_admin_token

If not set, a random token will be generated at server startup and printed to the console. Make note of this token as it's required for admin operations.

3. Launching Agents

1. Admin Agent: Start the admin agent using:

   python -m mcp_template.mcp_client_runner --admin
   

2. Worker Agents: Start worker agents using:

   python -m mcp_template.mcp_client_runner --agent-id worker1 --capabilities "frontend,react"
   python -m mcp_template.mcp_client_runner --agent-id worker2 --capabilities "backend,api"
   

4. Using AUTO Mode with Worker Agents

Once your environment is set up and agents are connected, you can activate AUTO mode with specialized worker capabilities:

AUTO --worker --memory

This commands the agent to:

• Operate autonomously without user intervention
• Follow the worker protocol with task status tracking
• Utilize memory for context retention across interactions

Dashboard

Access the dashboard at http://localhost:8080 to:

• Monitor agent activities in real-time
• View task status and dependencies
• Observe agent relationships and coordination
• Track file operations and context sharing

Token System and Resource Management

Understanding Tokens

Tokens serve multiple purposes in the MCP system:

1. Authentication Tokens: Used for agent identification and admin access
2. RAG Tokens: Used for embedding and retrieving context from the knowledge base
3. OpenAI Tokens: Consumed during agent operations (model usage)

Token Management

To monitor and manage token usage:

1. Install SQLite Viewer plugin or use the command line:

   sqlite3 /path/to/project/.agent/mcp_state.db
   

2. Query token usage:

   SELECT * FROM token_usage;
   

3. Monitor in the dashboard under the "Resources" tab

Resource Optimization

For large projects:

1. Use specialized agents with focused capabilities to reduce context size
2. Break tasks into smaller units with clear dependencies
3. Utilize the RAG system for efficient context retrieval
4. Store shared information in the project context rather than repeating in messages

Project RAG and Knowledge Base

Setting Up the Project RAG

The Retrieval-Augmented Generation (RAG) system allows agents to access relevant project knowledge efficiently:

1. Index project files:

   python -m mcp_template.rag_indexer --project-dir /path/to/project
   

2. Add documentation to the knowledge base:

   python -m mcp_template.rag_indexer --add-doc /path/to/document.md
   

Using RAG in Agent Workflows

Agents can query the knowledge base using:

response = await client.ask_project_rag("How does the authentication system work?")

This returns relevant context without loading entire files, saving tokens and improving response quality.

Agent Task Assignment Strategy

For optimal performance, follow these guidelines:

1. Task Granularity: Break down large tasks into atomic units with clear inputs/outputs
2. Dependency Tracking: Explicitly define task dependencies in assignment
3. Capability Matching: Assign tasks to agents with relevant capabilities
4. Progress Monitoring: Use explicit status updates to track task progress
5. Context Sharing: Provide necessary context at assignment time to reduce later lookups

Example task assignment from admin to worker:

@worker1 Please implement the login form component based on the MCD section 6.1. 
Dependencies: None
Artifacts: src/components/LoginForm.tsx
Context: Uses FormKit, requires email validation

Components

• main.py: MCP server implementation
• mcp_client.py: Client library for connecting agents to MCP
• dashboard_api.py: API endpoints for visualization
• rag_agent_test.py: Example of a RAG-capable agent
• INSTRUCTIONS.md: Operational guidelines for agents

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key
• MCP_SERVER_URL: URL of the MCP server
• MCP_ADMIN_TOKEN: (Optional) Admin token for direct access
• MCP_PROJECT_DIR: Path to the project directory

License

MIT License