Contract Comparisons - MCP Server with Multi-Agent Orchestration
Using WIPO to give recommendations
A Model Context Protocol (MCP) server with multi-agent orchestration capabilities, featuring a simple web interface for querying agents. This system supports multiple LLM providers (Ollama, OpenAI, Anthropic, Google) and orchestrates multiple agents to process complex queries with document management.
Features
- MCP-Compliant: Implements Model Context Protocol standards
- FastAPI Server: Modern async Python web framework
- Multi-Agent Orchestration: Intelligent query splitting and result synthesis
- PDF Document Upload: Upload and manage PDF documents with automatic text extraction
- Document Selection: Manual selection via UI or automatic detection from query text
- Smart Document Matching: Orchestrator automatically matches document names from queries
- Flexible LLM Provider Support: Switch between Ollama (local), OpenAI, Anthropic, or Google via UI or environment variables
- Model Selection: Choose from available models for your selected provider
- Web Interface: Modern Next.js frontend with document management sidebar and provider/model selection
- Automatic Agent Discovery: Agents are automatically discovered and registered
- RESTful API: Standard HTTP endpoints for agent and document management
Quick Start
For detailed setup instructions, see SETUP.md
Prerequisites
- Python 3.11+
- Node.js 18+
- LLM Provider (choose one or more):
- Ollama (local, free): Install from ollama.ai and pull a model:
ollama pull llama3:latest - OpenAI (cloud, paid): Get API key from platform.openai.com
- Anthropic (cloud, paid): Get API key from console.anthropic.com
- Google (cloud, paid): Get API key from ai.google.dev
- Ollama (local, free): Install from ollama.ai and pull a model:
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 LLM provider settings (see Configuration section below)
# 5. Start your LLM provider (if using Ollama)
# macOS: Open Ollama.app
# Linux: ollama serve
# For OpenAI/Anthropic/Google: Just add API key to .env
# 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
Using the System
- Select LLM Provider & Model:
- Use the dropdowns at the top of the chat to select your provider (Ollama, OpenAI, etc.)
- Choose a model from the available models for that provider
- The system will use your selection for all LLM calls in that query
- Upload Documents: Click "Upload PDF" in the sidebar to upload text-based PDF files
- Select Documents:
- Manual: Check the box next to documents you want to query
- Automatic: Just mention the document in your query (e.g., "tell me about my italy document")
- Ask Questions: Type your query in the chat
- The system will use your selected provider/model
- Automatically uses selected documents
- Internal agent searches through actual document text
- External agent queries external databases (WIPO, etc.)
Architecture
Components
-
MCP Server (Python/FastAPI)
- Orchestrates multi-agent workflows
- LLM-agnostic architecture - supports Ollama, OpenAI, Anthropic, Google
- Provider can be switched per-request via UI or defaults to
LLM_PROVIDERenv var - Runs on port 8000
-
Frontend (Next.js/React)
- Simple chat interface
- Connects to MCP server
- Runs on port 3000
-
Agents
- Internal Agent: Searches through uploaded PDF documents using extracted text
- External Agent: Queries external databases (e.g., WIPO for compliance information)
-
Orchestrator
- Analyzes user queries using LLM
- Automatically detects and matches documents from query text
- Splits queries into agent-specific tasks
- Synthesizes results from multiple agents
- Has access to all uploaded documents for intelligent routing
Workflow
User Uploads PDF → Text Extraction (pdfplumber) → Storage (filesystem + memory)
↓
User Query + Provider/Model Selection → Orchestrator → Query Analysis (LLM)
↓
Get Available Documents List
↓
Match Documents from Query (LLM + Fallback)
↓
Determine Agents Needed
↓
Generate Optimized Queries (with document context)
↓
Execute Agents (with selected documents + LLM provider)
↓
Internal Agent: Uses document text from storage
External Agent: Queries external databases
(Both use selected LLM provider/model)
↓
Compare & Synthesize Results (LLM)
↓
Return Final Answer
Document Management
The system supports two ways to select documents for queries:
- Manual Selection: Users can select documents via checkboxes in the sidebar
- Automatic Detection: Orchestrator automatically detects documents mentioned in queries
- Example: "tell me about my italy document" → automatically finds "Italy-111.pdf"
- Works with variations: "italian document", "japan-111", etc.
- Both methods can work together (manual + auto-detected)
API Endpoints
MCP Server (Port 8000)
GET /health- Health checkGET /api/providers- Get list of configured LLM providersGET /api/models?provider=ollama- Get available models for a providerPOST /orchestrate- Process user query{ "query": "your query here", "selected_documents": ["document1.pdf", "document2.pdf"], // Optional "provider": "openai", // Optional: override default provider "model": "gpt-4" // Optional: override default model }POST /api/upload- Upload a PDF document- Content-Type:
multipart/form-data - Body:
file(PDF file)
- Content-Type:
GET /api/documents- List all uploaded documentsDELETE /api/documents/{filename}- Delete a documentGET /mcp/agents- List all registered agentsGET /mcp/resources- List all MCP resourcesPOST /discover- Trigger agent discovery
Frontend (Port 3000)
GET /- Main chat interfacePOST /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 with upload endpoints
│ ├── agents/
│ │ ├── internal_agent.py # Internal document agent (uses uploaded PDFs)
│ │ └── external_agent.py # External database agent
│ ├── orchestrator/
│ │ └── orchestrator.py # Query orchestration with document matching
│ ├── services/
│ │ ├── ollama_service.py # Ollama API wrapper
│ │ └── document_storage.py # PDF storage and text extraction
│ ├── uploads/ # Uploaded PDF files (created on first upload)
│ ├── 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 (forwards to MCP server)
│ │ ├── components/
│ │ │ ├── chat.tsx # Chat UI component
│ │ │ └── document-sidebar.tsx # Document upload and selection UI
│ │ └── page.tsx # Main page with sidebar layout
│ └── 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:
Basic Configuration
PORT=8000
LOG_LEVEL=INFO
ENV=development
ALLOWED_ORIGINS=*
LLM Provider Configuration
Option 1: Ollama (Local, Free)
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3:latest
# Optional: Add more models for dropdown
OLLAMA_MODELS=llama3:latest,llama3.1:latest,mistral:latest
Option 2: OpenAI (Cloud, Paid)
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4
# Optional: Add more models for dropdown
OPENAI_MODELS=gpt-4,gpt-4-turbo,gpt-3.5-turbo
Option 3: Anthropic (Cloud, Paid)
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
Option 4: Google (Cloud, Paid)
LLM_PROVIDER=google
GOOGLE_API_KEY=your-api-key-here
GOOGLE_MODEL=gemini-pro
Note: You can configure multiple providers in .env. The UI will show all configured providers in the dropdown, and you can switch between them per-request. The LLM_PROVIDER variable sets the default provider.
Documentation
- SETUP.md - Comprehensive setup guide with step-by-step instructions
- WORKFLOW.md - Detailed workflow explanation including document upload, processing, and LLM provider architecture
- QUICKSTART.md - Quick start guide for getting up and running in 5 minutes
- FUTURE_GOALS.md - Planned improvements and next steps (LangGraph, WIPO integration, agent enhancements)
Key Features Explained
Document Upload & Management
- Upload PDFs: Use the sidebar "Upload PDF" button to upload text-based PDF files
- Text Extraction: pdfplumber automatically extracts text from all pages
- Storage: Documents saved to
backend/uploads/(persists) + text cached in memory (fast access) - Document Selection:
- Manual: Check boxes in sidebar
- Automatic: Mention document in query (e.g., "italy document" → finds "Italy-111.pdf")
How Documents Are Used
- Upload: PDF → Text extraction → Storage
- Query: User asks question (with or without mentioning document)
- Detection: Orchestrator matches documents from query or uses manual selection
- Processing: Internal agent retrieves document text and includes it in LLM prompt
- Response: LLM searches through actual document content to answer
Example Use Cases
- "What does my italy contract say?" → Auto-detects Italy-111.pdf, searches through it
- "Compare my italy and japan documents" → Finds both, searches through both
- "What do I need to change in my italy contract for australia?" → Uses internal agent (Italy document) + external agent (Australian compliance)
Development
Running Tests
pytest
Viewing Logs
MCP server logs are written to /tmp/mcp_server.log:
tail -f /tmp/mcp_server.log
Or use the helper script:
./view_logs.sh
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 - OpenAI/Anthropic/Google errors: Check API key is set correctly in
.env - Provider not showing in UI: Ensure API key is set in
.envfor that provider - 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