MCP Server with Multi-Agent Orchestration

A Model Context Protocol (MCP) server with multi-agent orchestration capabilities, featuring a simple web interface for querying agents. This system uses local Ollama for LLM inference and orchestrates multiple agents to process complex queries.

Features

MCP-Compliant: Implements Model Context Protocol standards
FastAPI Server: Modern async Python web framework
Multi-Agent Orchestration: Intelligent query splitting and result synthesis
Local LLM Support: Uses Ollama for local LLM inference
Web Interface: Simple Next.js frontend for querying the server
Automatic Agent Discovery: Agents are automatically discovered and registered
RESTful API: Standard HTTP endpoints for agent management

Quick Start

For detailed setup instructions, see

Prerequisites

Python 3.11+
Node.js 18+
Ollama installed and running
Model pulled: ollama pull llama3:latest

Quick Installation

# 1. Clone repository git clone <repository-url> cd mcp-server-orchestration # or whatever you name the repository # 2. Set up Python backend python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt # 3. Set up frontend cd frontend npm install cd .. # 4. Configure environment cp env.example .env # Edit .env with your settings # 5. Start Ollama (if not running) # macOS: Open Ollama.app # Linux: ollama serve # 6. Start servers # Terminal 1: MCP Server source venv/bin/activate python3 -m uvicorn backend.server.mcp_server:app --host 0.0.0.0 --port 8000 # Terminal 2: Frontend cd frontend npm run dev

Access the frontend at http://localhost:3000

Architecture

Components

MCP Server (Python/FastAPI)
- Orchestrates multi-agent workflows
- Uses Ollama for LLM inference
- Runs on port 8000
Frontend (Next.js/React)
- Simple chat interface
- Connects to MCP server
- Runs on port 3000
Agents
- Internal Agent: Simulates internal document retrieval
- External Agent: Simulates external database queries
Orchestrator
- Analyzes user queries using LLM
- Splits queries into agent-specific tasks
- Synthesizes results from multiple agents

Workflow

User Query → Orchestrator → Query Analysis (LLM) ↓ Determine Agents Needed ↓ Generate Optimized Queries ↓ Execute Agents (Parallel) ↓ Compare & Synthesize Results (LLM) ↓ Return Final Answer

API Endpoints

MCP Server (Port 8000)

GET /health - Health check
POST /orchestrate - Process user query
{ "query": "your query here" }
GET /mcp/agents - List all registered agents
GET /mcp/resources - List all MCP resources
POST /discover - Trigger agent discovery

Frontend (Port 3000)

GET / - Main chat interface
POST /api/chat - Chat endpoint (forwards to MCP server)

Project Structure

mcp-server-orchestration/ # Project root ├── backend/ # Backend MCP Server (Python/FastAPI) │ ├── server/ │ │ └── mcp_server.py # FastAPI server │ ├── agents/ │ │ ├── internal_agent.py # Internal document agent │ │ └── external_agent.py # External database agent │ ├── orchestrator/ │ │ └── orchestrator.py # Query orchestration │ ├── services/ │ │ └── ollama_service.py # Ollama API wrapper │ ├── interfaces/ │ │ └── agent.py # Agent interface │ ├── registry/ │ │ └── registry.py # Agent registry │ └── discovery/ │ └── agent_discovery.py # Auto-discovery ├── frontend/ # Frontend UI (Next.js) │ ├── app/ │ │ ├── api/chat/route.ts # Chat API │ │ └── components/chat.tsx # Chat UI │ └── package.json ├── requirements.txt # Python dependencies ├── env.example # Environment template ├── SETUP.md # Detailed setup guide └── README.md # This file

Configuration

Create a .env file from env.example:

PORT=8000 LOG_LEVEL=INFO ENV=development ALLOWED_ORIGINS=* OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_MODEL=llama3:latest

Documentation

SETUP.md - Comprehensive setup guide with step-by-step instructions
QUICKSTART.md - Quick start guide (if exists)

Development

Running Tests

pytest

Viewing Logs

MCP server logs are written to /tmp/mcp_server.log:

tail -f /tmp/mcp_server.log

Helper Scripts

./start_server.sh - Start MCP server with log viewing
./view_logs.sh - View MCP server logs

Troubleshooting

See SETUP.md for detailed troubleshooting guide.

Common issues:

Ollama not running: Start Ollama and verify with curl http://localhost:11434/api/tags
Port conflicts: Kill processes on ports 8000 or 3000
Module not found: Ensure virtual environment is activated and dependencies installed

License

[Add your license information here]

Contributing

Create a feature branch
Make your changes
Add tests
Submit a pull request

MCP Multi-Agent Orchestration Server