# 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](./SETUP.md)**

### Prerequisites

- Python 3.11+
- Node.js 18+
- **LLM Provider** (choose one or more):
  - **Ollama** (local, free): Install from [ollama.ai](https://ollama.ai/) and pull a model: `ollama pull llama3:latest`
  - **OpenAI** (cloud, paid): Get API key from [platform.openai.com](https://platform.openai.com/)
  - **Anthropic** (cloud, paid): Get API key from [console.anthropic.com](https://console.anthropic.com/)
  - **Google** (cloud, paid): Get API key from [ai.google.dev](https://ai.google.dev/)

### Quick Installation

```bash
# 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

1. **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
2. **Upload Documents**: Click "Upload PDF" in the sidebar to upload text-based PDF files
3. **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")
4. **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

1. **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

2. **Frontend** (Next.js/React)
   - Simple chat interface
   - Connects to MCP server
   - Runs on port 3000

3. **Agents**
   - **Internal Agent**: Searches through uploaded PDF documents using extracted text
   - **External Agent**: Queries external databases (e.g., WIPO for compliance information)

4. **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:

1. **Manual Selection**: Users can select documents via checkboxes in the sidebar
2. **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
  ```json
  {
    "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

```env
PORT=8000
LOG_LEVEL=INFO
ENV=development
ALLOWED_ORIGINS=*
```

### LLM Provider Configuration

**Option 1: Ollama (Local, Free)**
```env
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)**
```env
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)**
```env
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
```

**Option 4: Google (Cloud, Paid)**
```env
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](./SETUP.md)** - Comprehensive setup guide with step-by-step instructions
- **[WORKFLOW.md](./WORKFLOW.md)** - Detailed workflow explanation including document upload, processing, and LLM provider architecture
- **[QUICKSTART.md](./QUICKSTART.md)** - Quick start guide for getting up and running in 5 minutes
- **[FUTURE_GOALS.md](./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

1. **Upload**: PDF → Text extraction → Storage
2. **Query**: User asks question (with or without mentioning document)
3. **Detection**: Orchestrator matches documents from query or uses manual selection
4. **Processing**: Internal agent retrieves document text and includes it in LLM prompt
5. **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

```bash
pytest
```

### Viewing Logs

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

```bash
tail -f /tmp/mcp_server.log
```

Or use the helper script:
```bash
./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](./SETUP.md#troubleshooting) 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

1. Create a feature branch
2. Make your changes
3. Add tests
4. Submit a pull request