# Wikidata MCP Server - Optimized Hybrid Architecture

A Model Context Protocol (MCP) server with Server-Sent Events (SSE) transport that connects Large Language Models to Wikidata's structured knowledge base. Features an **optimized hybrid architecture** that balances speed, accuracy, and verifiability by using fast basic tools for simple queries and advanced orchestration only for complex temporal/relational queries.

## Architecture Highlights

- **🚀 Fast Basic Tools**: 140-250ms for simple entity/property searches
- **🧠 Advanced Orchestration**: 1-11s for complex temporal queries (when needed)
- **⚡ 50x Performance Difference**: Empirically measured and optimized
- **🔄 Hybrid Approach**: Right tool for each query type
- **🛡️ Graceful Degradation**: Works with or without Vector DB API key

## MCP Tools

### Basic Tools (Fast & Reliable)
- **`search_wikidata_entity`**: Find entities by name (140-250ms)
- **`search_wikidata_property`**: Find properties by name (~200ms)
- **`get_wikidata_metadata`**: Entity labels, descriptions (~200ms)
- **`get_wikidata_properties`**: All entity properties (~200ms)
- **`execute_wikidata_sparql`**: Direct SPARQL queries (~200ms)

### Advanced Tool (Complex Queries)
- **`query_wikidata_complex`**: Temporal/relational queries (1-11s)
  - ✅ "last 3 popes", "recent presidents of France"
  - ❌ Simple entity searches (use basic tools instead)

## Live Demo

The server is deployed and accessible at:

- **URL**: [https://wikidata-mcp-mirror.onrender.com](https://wikidata-mcp-mirror.onrender.com)
- **MCP Endpoint**: [https://wikidata-mcp-mirror.onrender.com/mcp](https://wikidata-mcp-mirror.onrender.com/mcp)
- **Health Check**: [https://wikidata-mcp-mirror.onrender.com/health](https://wikidata-mcp-mirror.onrender.com/health)

## Usage with Claude Desktop

To use this server with Claude Desktop:

1. **Install mcp-remote** (if not already installed):
   ```bash
   npm install -g @modelcontextprotocol/mcp-remote
   ```

2. Edit the Claude Desktop configuration file located at:
   ```
   ~/Library/Application Support/Claude/claude_desktop_config.json
   ```

3. Configure it to use the remote MCP server:
   ```json
   {
     "mcpServers": {
       "Wikidata MCP": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://wikidata-mcp-mirror.onrender.com/mcp"
         ]
       }
     }
   }
   ```

4. Restart Claude Desktop

5. When using Claude, you can now access Wikidata knowledge through the configured MCP server.

## Deployment

### Deploying to Render

1. **Create a new Web Service** in your Render dashboard
2. **Connect your GitHub repository**
3. **Configure the service**:
   - **Build Command**: `pip install -e .`
   - **Start Command**: `python -m wikidata_mcp.api`
4. **Set Environment Variables**:
   - Add all variables from `.env.example`
   - For production, set `DEBUG=false`
   - Make sure to set a proper `WIKIDATA_VECTORDB_API_KEY`
5. **Deploy**

The service will be available at `https://your-service-name.onrender.com`

## Environment Setup

### Prerequisites

- Python 3.10+
- Virtual environment tool (venv, conda, etc.)
- Vector DB API key (for enhanced semantic search)

### Environment Variables

Create a `.env` file in the project root with the following variables:

```bash
# Required for Vector DB integration

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/wikidata-mcp-mirror.git
   cd wikidata-mcp-mirror
   ```

2. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate
   ```

3. Install the required dependencies:
   ```bash
   pip install -e .
   ```

4. Create a `.env` file based on `.env.example` and configure your environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

5. Run the application:
   ```bash
   # Development
   python -m wikidata_mcp.api
   
   # Production (with Gunicorn)
   gunicorn --bind 0.0.0.0:8000 --workers 4 --timeout 120 --keep-alive 5 --worker-class uvicorn.workers.UvicornWorker wikidata_mcp.api:app
   ```

   The server will start on `http://localhost:8000` by default with the following endpoints:
   - `GET /health` - Health check
   - `GET /messages/` - SSE endpoint for MCP communication
   - `GET /docs` - Interactive API documentation (if enabled)
   - `GET /metrics` - Prometheus metrics (if enabled)

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 8000 | Port to run the server on |
| `WORKERS` | 4 | Number of worker processes |
| `TIMEOUT` | 120 | Worker timeout in seconds |
| `KEEPALIVE` | 5 | Keep-alive timeout in seconds |
| `DEBUG` | false | Enable debug mode |
| `LOG_LEVEL` | INFO | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `USE_VECTOR_DB` | true | Enable/disable vector DB integration |
| `USE_CACHE` | true | Enable/disable caching system |
| `USE_FEEDBACK` | true | Enable/disable feedback system |
| `CACHE_TTL_SECONDS` | 3600 | Cache time-to-live in seconds |
| `CACHE_MAX_SIZE` | 1000 | Maximum number of items in cache |
| `WIKIDATA_VECTORDB_API_KEY` | | API key for the vector DB service |

### Running with Docker

1. Build the Docker image:
   ```bash
   docker build -t wikidata-mcp .
   ```

2. Run the container:
   ```bash
   docker run -p 8000:8000 --env-file .env wikidata-mcp
   ```

### Running with Docker Compose

1. Start the application:
   ```bash
   docker-compose up --build
   ```

2. For production, use the production compose file:
   ```bash
   docker-compose -f docker-compose.prod.yml up --build -d
   ```

## Monitoring

The service exposes Prometheus metrics at `/metrics` when the `PROMETHEUS_METRICS` environment variable is set to `true`.

### Health Check

```bash
curl http://localhost:8000/health
```

### Metrics

```bash
curl http://localhost:8000/metrics
```

## Testing

### Running Tests

Run the test suite with:

```bash
# Run all tests
pytest

# Run specific test file
pytest tests/orchestration/test_query_orchestrator.py -v

# Run with coverage report
pytest --cov=wikidata_mcp tests/
```

### Integration Tests

To test the Vector DB integration, you'll need to set the `WIKIDATA_VECTORDB_API_KEY` environment variable:

```bash
WIKIDATA_VECTORDB_API_KEY=your_key_here pytest tests/orchestration/test_vectordb_integration.py -v
```

### Test Client

You can also test the server using the included test client:

```bash
python test_mcp_client.py
```

Or manually with curl:

```bash
# Connect to SSE endpoint
curl -N -H "Accept: text/event-stream" https://wikidata-mcp-mirror.onrender.com/messages/

# Send a message (replace SESSION_ID with the one received from the SSE endpoint)
curl -X POST "https://wikidata-mcp-mirror.onrender.com/messages/?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"0.1.0"}},"id":0}'
```

## Deployment on Render.com

This server is configured for deployment on Render.com using the `render.yaml` file.

### Deployment Configuration

- **Build Command**: `pip install -r requirements.txt`
- **Start Command**: `gunicorn -k uvicorn.workers.UvicornWorker server_sse:app`
- **Environment Variables**:
  - `PORT`: 10000
- **Health Check Path**: `/health`

### Docker Support

The repository includes a Dockerfile that's used by Render.com for containerized deployment. This allows the server to run in a consistent environment with all dependencies properly installed.

### How to Deploy

1. Fork or clone this repository to your GitHub account
2. Create a new Web Service on Render.com
3. Connect your GitHub repository
4. Render will automatically detect the `render.yaml` file and configure the deployment
5. Click "Create Web Service"

After deployment, you can access your server at the URL provided by Render.com.

## Architecture

The server is built using:

- **FastAPI**: For handling HTTP requests and routing
- **SSE Transport**: For bidirectional communication with clients
- **MCP Framework**: For implementing the Model Context Protocol
- **Wikidata API**: For accessing Wikidata's knowledge base

### Key Components

- `server_sse.py`: Main server implementation with SSE transport
- `wikidata_api.py`: Functions for interacting with Wikidata's API and SPARQL endpoint
- `requirements.txt`: Dependencies for the project
- `Dockerfile`: Container configuration for Docker deployment on Render
- `render.yaml`: Configuration for deployment on Render.com
- `test_mcp_client.py`: Test client for verifying server functionality

## Available MCP Tools

The server provides the following MCP tools:

- `search_wikidata_entity`: Search for entities by name
- `search_wikidata_property`: Search for properties by name
- `get_wikidata_metadata`: Get entity metadata (label, description)
- `get_wikidata_properties`: Get all properties for an entity
- `execute_wikidata_sparql`: Execute a SPARQL query
- `find_entity_facts`: Search for an entity and find its facts
- `get_related_entities`: Find entities related to a given entity

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Based on the Model Context Protocol (MCP) specification
- Uses Wikidata as the knowledge source
- Inspired by the MCP examples from the official documentation