Skip to content

Latest commit

 

History

History
59 lines (40 loc) · 2.84 KB

ARCHITECTURE.md

File metadata and controls

59 lines (40 loc) · 2.84 KB

Architecture Overview

This document describes the high-level architecture and data flow of the Wikipedia MCP server.

Components

  • CLI (wikipedia_mcp/__main__.py): Parses runtime configuration, validates auth/transport options, configures logging, and launches the server.
  • Auth Config (wikipedia_mcp/auth_config.py): Validates --auth-* options and environment fallbacks into a transport auth config.
  • Server (wikipedia_mcp/server.py): Builds FastMCP, wires tool/resource handlers, configures JWT auth provider, and exposes static bearer middleware for network transports.
  • Schemas (wikipedia_mcp/schemas.py): Pydantic output models used to generate explicit MCP outputSchema definitions.
  • Wikipedia Client (wikipedia_mcp/wikipedia_client.py): Handles Wikipedia API interaction, language/country mapping, variants, retries, and JSON/error normalization.
  • Tests (tests/): Coverage for CLI behavior, tool schemas, auth modes, language/country handling, and compatibility contracts.

Data Flow

  1. A request arrives through MCP tool invocation or resource read.
  2. FastMCP dispatches to a registered handler in server.py.
  3. Handler calls WikipediaClient methods.
  4. Client performs API/library operations and normalizes errors.
  5. Handler returns structured output aligned with explicit outputSchema.

Transport Model

  • stdio (default): local integrations and desktop clients.
  • http / streamable-http: preferred network deployment transport (endpoint path default /mcp).
  • sse: legacy compatibility transport.

Auth Model

Auth is only applied to network transports:

  • none: no request auth.
  • static: exact bearer token enforced by ASGI middleware.
  • jwt: FastMCP BearerAuthProvider validates JWT using public key or JWKS.

This is separate from --access-token, which is used for outbound Wikipedia API requests.

Tool Surface

  • Canonical tools are preserved (search_wikipedia, get_article, etc.).
  • Each canonical tool also has a discoverability alias prefixed with wikipedia_.
  • Tools include MCP annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint).

Error Handling

  • HTTP calls to Wikipedia use bounded retry/backoff on retryable failures.
  • Non-JSON or malformed responses are normalized into actionable error payloads.
  • Connectivity/search/coordinates surface safe fallback outputs instead of uncaught exceptions.

Security Notes

  • For exposed network transports, prefer http + --auth-mode static|jwt and private-network/reverse-proxy controls.
  • Avoid logging secrets or bearer tokens.

Extensibility

  • Add new MCP tools in server.py and register matching alias + annotations.
  • Add/extend output models in schemas.py to keep contracts explicit.
  • Extend WikipediaClient with focused methods and keep protocol-facing adaptation in server handlers.