# zzaebok/mcp-wikidata architecture

> Architecture diagram of the GitHub repository zzaebok/mcp-wikidata, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zzaebok/mcp-wikidata
- Repository: https://github.com/zzaebok/mcp-wikidata

## Overview

##### Project Type and Purpose
- This is a Python-based microservice (a backend server) which implements the Model Context Protocol (MCP) to expose Wikidata search and query operations.
- It includes a minimal client example for demonstration.

##### File Structure
- Top‐level files and dirs:
- Dockerfile, pyproject.toml, smithery.yaml, uv.lock – packaging, dependency, and deployment config
- src/server.py – the MCP server entrypoint and tool-implementation module
- src/client.py – a sample client using the MCP server (via langchain-mcp-adapters)
- No separate “frontend” suggests a pure backend service, with an optional CLI/demo client.

##### README for Extra Insight
- Describes four core tools (search_entity, search_property, get_properties, execute_sparql, plus get_metadata)
- Shows an example call flow: HumanMessage → AIMessage (tool_call) → ToolMessage → … → AIMessage
- Mentions external SPARQL endpoint (Wikidata), and installation via Smithery or uv.

##### Main Components & Boundaries
- Client Layer (src/client.py): issues MCP requests over HTTP (or whichever transport uv exposes)
- Transport Layer (UV Runner): uv.Run serves as the process manager / HTTP server
- MCP Server Core (src/server.py):
- Request handler (parses incoming MCP messages)
- Tool executor (dispatches to the appropriate function)
- Tool Implementations:
- search_entity, search_property, get_properties, execute_sparql, get_metadata
- External Services:
- Wikidata HTTP API (Search endpoints)
- Wikidata SPARQL endpoint
- Ops & Packaging:
- Docker container (Dockerfile)
- Dependency config (pyproject.toml, smithery.yaml)
- Lockfile (uv.lock)

##### Relationships & Data Flows
- Client → MCP Server: sends LLM‐mediated tool_call messages
- MCP Server → Tool implementations (in-proc calls)
- Tool implementations → External Wikidata APIs (HTTP requests) → return JSON
- MCP Server → Client: returns ToolMessage or final AIMessage
- Optionally, external LLM service (via langchain adapters) orchestrates tool calls

##### Architectural Patterns
- Layered: Transport → Protocol handler → Business logic → External I/O
- Microservice: single responsibility – just Wikidata queries via MCP
- Plugin-style: each tool is a discrete function, making it extensible

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["MCP Client Example\nsrc/client.py"]:::client
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        UVRunner["uv.Run HTTP Server\nuv.lock"]:::transport
    end

    %% Server Core Layer
    subgraph "MCP Server Core"
        direction TB
        Server["Protocol Handler & Tool Dispatcher\nsrc/server.py"]:::server
    end

    %% Tool Modules Layer
    subgraph "Tool Modules"
        direction TB
        SearchEntity["search_entity()"]:::tool
        SearchProperty["search_property()"]:::tool
        GetProperties["get_properties()"]:::tool
        ExecuteSPARQL["execute_sparql()"]:::tool
        GetMetadata["get_metadata()"]:::tool
    end

    %% External Services Layer
    subgraph "External Wikidata APIs"
        direction TB
        WDSearch["Wikidata HTTP Search Endpoint"]:::external
        WDSparql["Wikidata SPARQL Endpoint"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infra & Deployment"
        direction TB
        Docker["Docker Container\nDockerfile"]:::infra
        PyProj["Dependency Config\npyproject.toml"]:::infra
        Smithery["Deployment Orchestration\nsmithery.yaml"]:::infra
        Readme["Project Metadata\nREADME.md\nLICENSE"]:::infra
        GitIgnore[".gitignore\n.python-version"]:::infra
    end

    %% Connections
    Client -->|"MCP JSON over HTTP"| UVRunner
    UVRunner -->|"forward request"| Server
    Server -->|"dispatch to"| SearchEntity
    Server -->|"dispatch to"| SearchProperty
    Server -->|"dispatch to"| GetProperties
    Server -->|"dispatch to"| ExecuteSPARQL
    Server -->|"dispatch to"| GetMetadata

    SearchEntity -->|"HTTP GET JSON"| WDSearch
    SearchProperty -->|"HTTP GET JSON"| WDSearch
    GetProperties -->|"HTTP GET JSON"| WDSearch
    ExecuteSPARQL -->|"HTTP GET SPARQL"| WDSparql
    GetMetadata -->|"HTTP GET JSON"| WDSearch

    WDSearch -->|"JSON response"| Server
    WDSparql -->|"SPARQL response"| Server
    Server -->|"MCP ToolMessage"| UVRunner
    UVRunner -->|"HTTP response"| Client

    %% Infra connections
    Docker --> UVRunner
    Docker --> Server
    Docker --> Client
    PyProj --> Docker
    Smithery --> Docker
    Readme --> PyProj
    GitIgnore --> Docker

    %% Click Events
    click Client "https://github.com/zzaebok/mcp-wikidata/blob/master/src/client.py"
    click Server "https://github.com/zzaebok/mcp-wikidata/blob/master/src/server.py"
    click UVRunner "https://github.com/zzaebok/mcp-wikidata/blob/master/uv.lock"
    click Docker "https://github.com/zzaebok/mcp-wikidata/tree/master/Dockerfile"
    click PyProj "https://github.com/zzaebok/mcp-wikidata/blob/master/pyproject.toml"
    click Smithery "https://github.com/zzaebok/mcp-wikidata/blob/master/smithery.yaml"
    click Readme "https://github.com/zzaebok/mcp-wikidata/blob/master/README.md"
    click Readme "https://github.com/zzaebok/mcp-wikidata/tree/master/LICENSE"
    click GitIgnore "https://github.com/zzaebok/mcp-wikidata/blob/master/.gitignore"
    click GitIgnore "https://github.com/zzaebok/mcp-wikidata/blob/master/.python-version"

    %% Styles
    classDef client fill:#e0ffe0,stroke:#006400,color:#006400
    classDef transport fill:#ffe0b2,stroke:#bf360c,color:#bf360c
    classDef server fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef tool fill:#e1bee7,stroke:#4a148c,color:#4a148c,stroke-dasharray: 5 5
    classDef external fill:#ffcdd2,stroke:#b71c1c,color:#b71c1c,stroke-dasharray: 2 2
    classDef infra fill:#fff9c4,stroke:#f57f17,color:#f57f17
```
