# reeeeemo/ancestry-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/reeeeemo/ancestry-mcp
- Repository: https://github.com/reeeeemo/ancestry-mcp

## Overview

##### Project type and purpose
- This is a lightweight Python-based MCP (Model Context Protocol) server that exposes filesystem operations on GEDCOM (`.ged`) files to an external MCP client (e.g., Claude Desktop).
- It is not a full-stack web app but an open-source CLI-driven microservice/plugin aligning with the MCP SDK.

##### File structure
- Top-level: metadata files (`pyproject.toml`, `README.md`, `LICENSE`), a single package under `src/mcp_server_ancestry/`.
- `server.py` contains the MCP server entrypoint: parses CLI args (e.g. `--gedcom-path`), registers “tools” (list_files, rename_file, view_file) via the MCP Python SDK, and routes incoming MCP requests.
- No database or front end; all state is in the host filesystem under the supplied directory.

##### Extract insights from the README
- The server speaks MCP over STDIN/STDOUT or subprocess pipes (as per Claude Desktop plugin conventions).
- Implements three core operations against `.ged` files.
- Depends on the Model Context Protocol Python SDK and a GEDCOM‐parsing library (implied).

- External MCP Client (e.g. Claude Desktop)
- MCP Transport Layer (stdin/stdout or process‐pipe)
- Python MCP Server Process
– MCP SDK Adapter
– Command/Tool Dispatcher
– GEDCOM File Service (parsing & I/O)
- Host Filesystem (GEDCOM files directory)
- (Optional) Logging/Config

1. Client → MCP Transport Layer: sends JSON-RPC MCP requests.
2. Transport Layer → Python Server: delivers requests to `server.py`.
3. Server Dispatcher → MCP SDK Adapter: unmarshals requests into tool calls.
4. For each tool:
- → GEDCOM File Service: performs FS operations (list, rename, parse).
- → Host Filesystem: reads/writes `.ged` files.
5. Responses flow back through the same path in reverse, ending at the Client.

c. Architectural patterns & principles
- Single‐responsibility modules: Transport, Protocol Adapter, Command Handlers, File Service
- Plugin/Tool registration (extensibility) via the MCP SDK
- Minimal external dependencies, no embedded DB

d. Key technologies/frameworks
- Python 3.x
- Model Context Protocol Python SDK
- GEDCOM parsing library (inside File Service)
- Standard filesystem APIs
- CLI entrypoint via `pyproject.toml`/console_scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External system
    Client["External MCP Client<br/>(e.g. Claude Desktop)"]:::external

    %% Python Server Process Group
    subgraph "Python MCP Server Process"
        direction TB
        Transport["MCP Transport Layer<br/>(stdin/stdout JSON-RPC)"]:::io
        Adapter["MCP SDK Adapter<br/>(tool registration & protocol glue)"]:::process
        Dispatcher["Command/Tool Dispatcher<br/>(list_files, rename_file, view_file handlers)"]:::process
        FileService["GEDCOM File Service<br/>(parsing & filesystem I/O)"]:::process
    end

    %% Storage
    HostFS["Host Filesystem<br/>(GEDCOM files directory)"]:::storage

    %% Documentation & Config
    PyProj["CLI Entrypoint Configuration<br/>(console_scripts)"]:::process
    Readme["Project Documentation"]:::external
    License["License Information"]:::external

    %% Data Flows
    Client -->|"MCP JSON Request"| Transport
    Transport -->|"deliver request"| Adapter
    Adapter -->|"unmarshal request"| Dispatcher
    Dispatcher -->|"invoke tool"| FileService
    FileService -->|"fs operation"| HostFS
    HostFS -->|"file data"| FileService
    FileService -->|"tool result"| Dispatcher
    Dispatcher -->|"format response"| Adapter
    Adapter -->|"serialize response"| Transport
    Transport -->|"MCP JSON Response"| Client

    %% Side connections
    PyProj -.->|"defines CLI entrypoint"| Transport
    Readme -.->|"usage & design notes"| Adapter
    License -.->|"license details"| Adapter

    %% Click Events
    click Transport "https://github.com/reeeeemo/ancestry-mcp/blob/main/src/mcp_server_ancestry/server.py"
    click Adapter "https://github.com/reeeeemo/ancestry-mcp/blob/main/src/mcp_server_ancestry/server.py"
    click Dispatcher "https://github.com/reeeeemo/ancestry-mcp/blob/main/src/mcp_server_ancestry/server.py"
    click FileService "https://github.com/reeeeemo/ancestry-mcp/blob/main/src/mcp_server_ancestry/server.py"
    click PyProj "https://github.com/reeeeemo/ancestry-mcp/blob/main/pyproject.toml"
    click Readme "https://github.com/reeeeemo/ancestry-mcp/blob/main/README.md"
    click License "https://github.com/reeeeemo/ancestry-mcp/tree/main/LICENSE"

    %% Styles
    classDef external fill:#D0E6FA,stroke:#000,color:#000;
    classDef process fill:#D4EDDA,stroke:#000,color:#000;
    classDef storage fill:#FFE5B4,stroke:#000,color:#000;
    classDef io fill:#F0F0F0,stroke:#000,color:#000;
```
