MCP Wikipedia Server

# 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**