NLP-project-contract-comparison by ec49ca - MCP Server

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

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

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_PROVIDER env 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 check
GET /api/providers - Get list of configured LLM providers
GET /api/models?provider=ollama - Get available models for a provider

POST /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)
GET /api/documents - List all uploaded documents
DELETE /api/documents/{filename} - Delete a document
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 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

- Comprehensive setup guide with step-by-step instructions
- Detailed workflow explanation including document upload, processing, and LLM provider architecture
- Quick start guide for getting up and running in 5 minutes
- 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 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 .env for 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