# MCP Wikipedia Server

A production-ready Model Context Protocol (MCP) server that provides Wikipedia search and content retrieval tools using FastMCP and Python 3.11.

[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 🚀 Quick Start

```bash
# 1. Set up environment (one-time setup)
./setup.sh

# 2. Start the server
source .venv311/bin/activate
cd src/mcp_server && python mcp_server.py

# 3. Test with example client
python example_client.py
```

## 🎯 Features

- **Wikipedia Search**: Find articles with intelligent search and get comprehensive summaries
- **Section Listing**: Extract all section titles from any Wikipedia article
- **Content Retrieval**: Get specific section content with proper formatting
- **MCP Protocol**: Full Model Context Protocol compatibility for AI assistant integration
- **FastMCP Framework**: Built on the efficient FastMCP library for optimal performance
- **Python 3.11**: Modern Python with latest features and performance improvements

## 📚 Documentation

| Document | Description |
|----------|-------------|
| [📖 Complete Guide](GUIDE.md) | Detailed setup, usage, and development instructions |
| [⚡ Quick Reference](QUICK_REF.md) | Common commands and tool summaries |
| [🔧 Setup Script](setup.sh) | Automated environment setup and verification |
| [💡 Example Client](example_client.py) | Sample usage and integration examples |

## 🛠️ Available Tools

| Tool | Purpose | Example Usage |
|------|---------|--------------|
| `fetch_wikipedia_info` | Search Wikipedia and get article summaries | Search for "Python programming" |
| `list_wikipedia_sections` | Get all section titles from an article | List sections of "Machine Learning" |
| `get_section_content` | Retrieve specific section content | Get "History" section from "Artificial Intelligence" |

## 🏗️ Project Structure

```
MCPClientServer/
├── 📁 src/mcp_server/           # Core server implementation
│   ├── mcp_server.py           # Main MCP Wikipedia server
│   └── mcp_client.py           # Example MCP client
├── 📁 tests/                   # Comprehensive test suite
│   ├── test_server.py          # Unit tests (pytest)
│   ├── test_integration.py     # Integration tests
│   ├── test_performance.py     # Performance benchmarks
│   ├── test_mcp_compliance.py  # MCP protocol compliance
│   ├── quick_test.py           # Fast validation script
│   ├── run_tests.py            # Unified test runner
│   └── README.md               # Testing documentation
├── 📁 .venv311/               # Python 3.11 virtual environment
├── 🔧 setup.sh                # Automated setup script
├── 💡 example_client.py        # Usage examples and demos
├── 📖 GUIDE.md                # Complete documentation
├── ⚡ QUICK_REF.md             # Quick reference
├── 📄 pytest.ini              # Test configuration
├── 📄 requirements-test.txt    # Test dependencies
└── 📄 pyproject.toml          # Project configuration
```

## 🚦 Prerequisites

- **macOS** (tested on Apple Silicon and Intel)
- **Python 3.11+** (installed via pyenv recommended)
- **Git** (for version control)

## 📦 Installation Options

### Option 1: Automated Setup (Recommended)
```bash
chmod +x setup.sh
./setup.sh
```

### Option 2: Manual Setup
```bash
# Set up Python 3.11 environment
pyenv install 3.11.10
pyenv local 3.11.10

# Create and activate virtual environment
python -m venv .venv311
source .venv311/bin/activate

# Install dependencies
pip install --upgrade pip
pip install wikipedia mcp fastmcp
```

## 🔌 Integration Examples

### With Claude Desktop (MCP Client)
```json
{
  "mcpServers": {
    "wikipedia": {
      "command": "python",
      "args": ["/path/to/MCPClientServer/src/mcp_server/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/MCPClientServer/.venv311/lib/python3.11/site-packages"
      }
    }
  }
}
```

### Direct Python Usage
```python
from mcp_client import WikipediaClient

client = WikipediaClient()
result = await client.search_wikipedia("Artificial Intelligence")
print(result)
```

## 🧪 Testing

### Quick Testing
```bash
# Fast validation (10 seconds)
python tests/quick_test.py

# Comprehensive test suite (5 minutes)
python tests/run_tests.py
```

### Advanced Testing
```bash
# Install test dependencies
pip install -r requirements-test.txt

# Run specific test suites
python tests/run_tests.py --unit          # Unit tests only
python tests/run_tests.py --integration   # Integration tests only
python tests/run_tests.py --performance   # Performance benchmarks
python tests/run_tests.py --mcp          # MCP compliance tests

# Using pytest directly
python -m pytest tests/test_server.py -v --cov=src
```

### Test Suite Overview
- **Unit Tests**: Individual function and component testing
- **Integration Tests**: End-to-end workflow validation  
- **Performance Tests**: Response time and load benchmarks
- **MCP Compliance**: Protocol specification validation
- **95%+ Code Coverage**: Comprehensive test coverage

See [tests/README.md](tests/README.md) for complete testing documentation.

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError: No module named 'mcp'` | Run `pip install mcp fastmcp` in activated environment |
| `Python version issues` | Ensure Python 3.11+ with `python --version` |
| `Server won't start` | Check if port is available, verify dependencies |
| `Wikipedia API errors` | Check internet connection, try different search terms |

For detailed troubleshooting, see [GUIDE.md](GUIDE.md#troubleshooting).

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [Wikipedia API Documentation](https://wikipedia.readthedocs.io/)
- [Python 3.11 Features](https://docs.python.org/3.11/whatsnew/3.11.html)

## 🌟 Support

If you find this project helpful, please consider giving it a star ⭐ on GitHub!

---

**Made with ❤️ for the MCP community**