Wikipedia MCP Server

# Wikipedia MCP Server - Project Scope ## Overview This project will create a **Wikipedia MCP Server** - a local Model Context Protocol server that provides Claude with real-time access to Wikipedia data through a standardized set of tools. The server will implement the MCP specification to enable seamless integration with Claude Desktop and other MCP-compatible clients. ## Project Goals ### Primary Objective Build a production-ready MCP server that acts as a bridge between Claude and Wikipedia, allowing: - Live Wikipedia content retrieval - Intelligent article search and discovery - Structured data access from Wikipedia - Real-time content summarization ### Key Benefits - **Real-time Data**: Access to current Wikipedia content (not training data cutoff) - **Structured Access**: Well-defined tools for specific Wikipedia operations - **Local Control**: Self-hosted server with no external API keys required - **Extensible**: Foundation for additional Wikipedia-related features ## Technical Architecture ### MCP Implementation Details **Server Type**: Local MCP Server using Python SDK **Transport**: Standard I/O (stdio) for Claude Desktop integration **Protocol Version**: Latest MCP specification (2024) ### Core Components 1. **MCP Server Framework** - Python-based using `@modelcontextprotocol/python-sdk` - FastMCP for rapid development and built-in features - Stdio transport for Claude Desktop compatibility 2. **Wikipedia Integration** - Wikipedia API client for content retrieval - Caching layer for performance optimization - Rate limiting and error handling 3. **Tool Architecture** - Structured tool definitions with JSON schemas - Type-safe input/output validation - Comprehensive error handling ## Functional Requirements ### Core Tools (Phase 1) #### 1. `search_wikipedia` ```python @mcp.tool() def search_wikipedia( query: str, limit: int = 10, language: str = "en" ) -> WikipediaSearchResult: """Search Wikipedia articles by query terms""" ``` **Input Schema:** - `query` (required): Search terms - `limit` (optional): Number of results (default: 10, max: 50) - `language` (optional): Wikipedia language code (default: "en") **Output:** List of article titles, URLs, and brief descriptions #### 2. `get_article` ```python @mcp.tool() def get_article( title: str, language: str = "en", sections: list[str] | None = None ) -> WikipediaArticle: """Retrieve full Wikipedia article content""" ``` **Input Schema:** - `title` (required): Article title or page ID - `language` (optional): Wikipedia language code - `sections` (optional): Specific sections to retrieve **Output:** Structured article data with content, metadata, and references #### 3. `get_summary` ```python @mcp.tool() def get_summary( title: str, language: str = "en", sentences: int = 3 ) -> WikipediaSummary: """Get concise article summary""" ``` **Input Schema:** - `title` (required): Article title - `language` (optional): Wikipedia language code - `sentences` (optional): Number of summary sentences **Output:** Article summary with key facts and metadata #### 4. `search_related` ```python @mcp.tool() def search_related( title: str, language: str = "en", limit: int = 10 ) -> RelatedArticles: """Find articles related to a given article""" ``` **Input Schema:** - `title` (required): Base article title - `language` (optional): Wikipedia language code - `limit` (optional): Number of related articles **Output:** List of related articles with relevance scores ### Enhanced Features (Phase 2) #### 5. `get_categories` ```python @mcp.tool() def get_categories( title: str, language: str = "en" ) -> ArticleCategories: """Get Wikipedia categories for an article""" ``` #### 6. `search_by_category` ```python @mcp.tool() def search_by_category( category: str, language: str = "en", limit: int = 20 ) -> CategoryArticles: """Find articles in a specific category""" ``` #### 7. `get_page_info` ```python @mcp.tool() def get_page_info( title: str, language: str = "en" ) -> PageMetadata: """Get article metadata and statistics""" ``` ## Data Models ### Structured Output Types ```python class WikipediaSearchResult(BaseModel): articles: list[SearchResult] total_found: int language: str class SearchResult(BaseModel): title: str url: str description: str page_id: int class WikipediaArticle(BaseModel): title: str content: str sections: dict[str, str] url: str last_modified: datetime page_id: int language: str categories: list[str] references: list[str] class WikipediaSummary(BaseModel): title: str summary: str url: str language: str page_id: int key_facts: list[str] ``` ## Technical Requirements ### Dependencies - **Core**: `mcp` Python SDK, `httpx` for HTTP requests - **Wikipedia API**: Custom client using Wikipedia REST API v1 - **Data Processing**: `pydantic` for data validation, `beautifulsoup4` for HTML parsing - **Performance**: `asyncio` for async operations, local caching ### Performance Targets - **Response Time**: < 2 seconds for most operations - **Caching**: 5-minute cache for article content, 1-hour cache for search results - **Rate Limiting**: Respect Wikipedia's rate limits (max 100 requests/minute) - **Concurrent Requests**: Support up to 5 concurrent Wikipedia API calls ### Error Handling - Graceful handling of Wikipedia API errors - Network timeout and retry logic - Invalid article title handling - Language not supported fallbacks ## Installation & Configuration ### Claude Desktop Integration ```json { "mcpServers": { "wikipedia": { "command": "uv", "args": [ "run", "--directory", "/path/to/wikipedia-mcp", "wikipedia_mcp_server.py" ] } } } ``` ### Environment Configuration ```python # Optional environment variables WIKIPEDIA_DEFAULT_LANGUAGE=en WIKIPEDIA_CACHE_TTL=300 WIKIPEDIA_MAX_CONCURRENT=5 WIKIPEDIA_RATE_LIMIT=100 ``` ## Development Phases ### Phase 1: Core Implementation (Week 1) - [ ] Set up MCP server foundation using FastMCP - [ ] Implement basic Wikipedia API client - [ ] Create core tools: `search_wikipedia`, `get_article`, `get_summary`, `search_related` - [ ] Add structured output models - [ ] Basic error handling and validation ### Phase 2: Enhanced Features (Week 2) - [ ] Add caching layer with TTL - [ ] Implement rate limiting - [ ] Add category-based tools - [ ] Enhanced error handling and logging - [ ] Performance optimization ### Phase 3: Production Ready (Week 3) - [ ] Comprehensive testing suite - [ ] Documentation and usage examples - [ ] Claude Desktop integration guide - [ ] Performance monitoring - [ ] Optional: Multiple language support ## Success Criteria ### Functional Success - ✅ All core tools working reliably - ✅ Structured output with proper schemas - ✅ Integration with Claude Desktop - ✅ Real-time Wikipedia data access ### Performance Success - ✅ Sub-2-second response times for 90% of requests - ✅ Proper rate limiting and caching - ✅ Graceful error handling - ✅ No Wikipedia API abuse ### Usability Success - ✅ Clear tool descriptions and schemas - ✅ Intuitive search and retrieval workflows - ✅ Comprehensive article access - ✅ Related content discovery ## Future Enhancements ### Potential Extensions - **Multi-language Support**: Automatic language detection and translation - **Image Access**: Wikipedia media and image retrieval - **Citation Tracking**: Enhanced reference and citation tools - **Personalization**: User preference-based content filtering - **Wikidata Integration**: Access to structured knowledge base - **Historical Data**: Access to article revision history ### Advanced Features - **Semantic Search**: AI-powered content discovery - **Content Analysis**: Automatic fact extraction and summarization - **Cross-reference**: Link analysis between articles - **Export Tools**: PDF/markdown generation from Wikipedia content ## Constraints & Considerations ### Technical Constraints - Must comply with Wikipedia's Terms of Use and API guidelines - Rate limiting required to be a good citizen of Wikipedia infrastructure - No modification or redistribution of Wikipedia content - Respect for Wikipedia's server resources ### Operational Constraints - Local-only server (no cloud deployment in scope) - Stdio transport only (no HTTP server) - Python-only implementation - Compatible with latest Claude Desktop versions ### Licensing & Legal - Comply with Wikipedia's CC BY-SA 3.0 license - Proper attribution for Wikipedia content - No commercial use restrictions - Open source development approach --- ## Next Steps 1. **Review and Approve Scope**: Validate requirements and technical approach 2. **Environment Setup**: Prepare development environment with Python and MCP SDK 3. **Initial Implementation**: Begin with basic MCP server and Wikipedia API client 4. **Core Tools Development**: Implement the four primary tools with structured output 5. **Testing & Integration**: Validate with Claude Desktop and refine based on usage This scope provides a comprehensive foundation for building a production-ready Wikipedia MCP Server that enhances Claude's capabilities with real-time Wikipedia access.