# Wikipedia MCP Server

A Model Context Protocol (MCP) server that provides Claude with real-time access to Wikipedia. This server implements 4 essential tools for effective Wikipedia research while demonstrating core MCP concepts.

## Features

### Core Tools
- **`search_wikipedia`** - Find articles when you don't know exact titles
- **`get_article`** - Retrieve full article content for detailed analysis  
- **`get_summary`** - Get concise summaries for quick understanding
- **`find_related`** - Discover related articles to expand research

### Key Benefits
- 🔄 **Real-time data** - Access current Wikipedia content, not training data
- 🏗️ **Structured output** - Well-defined schemas for reliable data access
- 🏠 **Local control** - Self-hosted, no API keys required
- ⚡ **Fast & efficient** - Async operations with proper error handling

## Installation

### Prerequisites
- Python 3.9 or higher
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install Dependencies

Using pip:
```bash
# Navigate to the project directory
cd wikipedia-mcp-server

# Install dependencies
pip install mcp httpx pydantic beautifulsoup4
```

Using uv (if available):
```bash
# Clone or create the project directory
cd wikipedia-mcp-server

# Install dependencies
uv sync
```

## Usage

### Running the Server

#### With python directly:
```bash
python -m src.wikipedia_mcp_server
```

#### With uv (if available):
```bash
uv run python -m src.wikipedia_mcp_server
```

### Testing the Tools

You can test individual tools by running the server and connecting with an MCP client:

```python
# Example: Search for articles
search_wikipedia("quantum computing", limit=3)

# Example: Get article summary
get_summary("Albert Einstein")

# Example: Get full article
get_article("Machine Learning")

# Example: Find related articles
find_related("Artificial Intelligence", limit=5)
```

## Claude Desktop Integration

To use this MCP server with Claude Desktop, add it to your MCP configuration:

### macOS/Linux Configuration
Edit `~/.config/claude-desktop/mcp.json`:

```json
{
  "mcpServers": {
    "wikipedia": {
      "command": "python",
      "args": [
        "-m", 
        "src.wikipedia_mcp_server"
      ],
      "cwd": "/ABSOLUTE/PATH/TO/wikipedia-mcp-server"
    }
  }
}
```

### Windows Configuration  
Edit `%APPDATA%\Claude\mcp.json`:

```json
{
  "mcpServers": {
    "wikipedia": {
      "command": "python",
      "args": [
        "-m", 
        "src.wikipedia_mcp_server"
      ],
      "cwd": "C:\\ABSOLUTE\\PATH\\TO\\wikipedia-mcp-server"
    }
  }
}
```

### Alternative: Using uv
If you have uv installed:

```json
{
  "mcpServers": {
    "wikipedia": {
      "command": "uv",
      "args": [
        "run", 
        "python", 
        "-m", 
        "src.wikipedia_mcp_server"
      ],
      "cwd": "/ABSOLUTE/PATH/TO/wikipedia-mcp-server"
    }
  }
}
```

## Research Workflows

### Typical Research Flow
1. **Discover**: `search_wikipedia("quantum computing")` → Find relevant articles
2. **Overview**: `get_summary("Quantum computing")` → Quick understanding  
3. **Deep dive**: `get_article("Quantum computing")` → Full content when needed
4. **Expand**: `find_related("Quantum computing")` → Related topics

### Example Claude Conversation
```
User: I want to learn about Marie Curie's discoveries

Claude: I'll help you research Marie Curie's discoveries. Let me start by getting a summary of her Wikipedia article.

[Uses get_summary("Marie Curie")]

Based on the summary, Marie Curie was a pioneering scientist who discovered radium and polonium. Let me find related articles about her specific discoveries.

[Uses find_related("Marie Curie")]

Now let me get detailed information about her discovery of radium.

[Uses get_article("Radium")]
```

## Tool Specifications

### search_wikipedia
- **Purpose**: Find articles when you don't know exact titles
- **Input**: query (required), limit (1-10), language (default: "en")
- **Output**: List of search results with titles, snippets, and URLs

### get_article  
- **Purpose**: Retrieve full article content
- **Input**: title (required), language (default: "en")
- **Output**: Complete article with content, metadata, and sections

### get_summary
- **Purpose**: Get concise article summaries
- **Input**: title (required), language (default: "en") 
- **Output**: Summary text with key facts

### find_related
- **Purpose**: Discover related articles
- **Input**: title (required), limit (1-10), language (default: "en")
- **Output**: Related articles with relationship types

## Error Handling

The server includes comprehensive error handling for:
- Invalid article titles
- Network timeouts
- Wikipedia API errors
- Malformed requests
- Rate limiting

## Development

### Project Structure
```
wikipedia-mcp-server/
├── src/wikipedia_mcp_server/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py          # Main MCP server
│   ├── models.py          # Pydantic data models
│   └── wikipedia_client.py # Wikipedia API client
├── pyproject.toml
├── README.md
└── mvp.md
```

### Key MCP Concepts Demonstrated
- ✅ Tool registration with `@mcp.tool()`
- ✅ Structured input/output with Pydantic models
- ✅ Async operations for performance
- ✅ Proper error handling and validation
- ✅ Clear tool documentation

### Adding New Tools
To add a new tool:

1. Define the output model in `models.py`
2. Add the Wikipedia API method in `wikipedia_client.py`
3. Register the tool in `server.py` with `@mcp.tool()`

## Performance Considerations

- **Async operations**: All Wikipedia API calls are non-blocking
- **Response times**: Typically < 3 seconds per operation
- **Rate limiting**: Respects Wikipedia's guidelines
- **Error resilience**: Graceful handling of API failures

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is open source and available under the MIT License.

## Acknowledgments

- Built using the [Model Context Protocol](https://modelcontextprotocol.io/)
- Wikipedia data via the [Wikipedia REST API](https://en.wikipedia.org/api/rest_v1/)
- Uses the [FastMCP](https://github.com/modelcontextprotocol/python-sdk) framework

---

**Happy researching with Claude and Wikipedia! 🔍📚**