ClumsyWizardHands/AI-Agent-Deck-MCP-server

Agent Swarm MCP Server

A FastAPI-based MCP (Model Context Protocol) server for agent swarm operations that generates AI agent specifications using Claude API.

Description

This server provides an API endpoint that accepts empire/organization descriptions and generates tailored AI agent specifications. It leverages Claude AI to analyze requirements and suggest optimal agent configurations for building AI agent swarms.

Project Structure

agent_swarm_mcp_server/
├── venv/                    # Python virtual environment
├── app/
│   ├── __init__.py         # Package initializer
│   ├── main.py             # FastAPI application entry point
│   ├── models.py           # Pydantic data models
│   ├── config.py           # Configuration management
│   └── claude_service.py   # Claude API integration
├── prompts/                # Directory for prompt templates
│   └── master_prompt.txt   # AI Agent Swarm Architect prompt
├── memory-bank/            # Project context and documentation
├── requirements.txt        # Python dependencies
├── .env.example           # Example environment variables
├── .gitignore             # Git ignore file
└── README.md              # This file

Prerequisites

• Python 3.7 or higher
• Claude API key from Anthropic

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd agent_swarm_mcp_server

2. Create Virtual Environment

Windows:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file by copying the example:

cp .env.example .env

Edit the .env file and set your Claude API key:

CLAUDE_API_KEY=YOUR_CLAUDE_API_KEY_HERE
MASTER_PROMPT_PATH=./prompts/master_prompt.txt

Important: Never commit your .env file to version control. The .gitignore file is already configured to exclude it.

5. Run the Server

Using uvicorn with auto-reload (recommended for development):

uvicorn app.main:app --reload

Or run directly with Python:

python app/main.py

The server will start on http://localhost:8000

API Endpoints

Root Endpoint

• GET / - Welcome message with navigation links

Health Check

• GET /health - Server health status

Agent Suggestions

• POST /suggest-agents - Generate AI agent specifications based on empire description
  • Request body: EmpireDescriptionRequest (see models.py for schema)
  • Response: List of AgentSpecificationResponse objects

MCP Protocol

• POST /mcp - MCP protocol endpoint (placeholder for future implementation)

Interactive Documentation

• GET /docs - Swagger UI documentation (automatically generated by FastAPI)
• GET /redoc - ReDoc documentation (automatically generated by FastAPI)

Development

Access the interactive API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

CORS Configuration

The server is configured with CORS middleware to allow cross-origin requests. In development, all origins are allowed. For production deployment, update the allow_origins parameter in app/main.py to specify your frontend domain:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-frontend-domain.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Environment Variables

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 422 - Validation Error (invalid request data)
• 500 - Internal Server Error
• 502 - Bad Gateway (Claude API returned invalid data)
• 503 - Service Unavailable (network errors)
• 504 - Gateway Timeout (Claude API timeout)

Next Steps

1. Implement full MCP protocol handlers
2. Add authentication and authorization
3. Implement agent registration and discovery
4. Add message routing for agent-to-agent communication
5. Add structured logging and monitoring
6. Implement agent state management
7. Add database integration for persistence