README.mdโข6.74 kB
# 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.
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](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**