# ndaelman-hu/parse-patrol architecture

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

- Interactive diagram: https://gitdiagram.com/ndaelman-hu/parse-patrol
- Repository: https://github.com/ndaelman-hu/parse-patrol

## Overview

##### Project type and purpose
- This is a Python-based tooling framework (“parse-patrol”) for Materials Science/Chemistry that exposes multiple parsing tools as MCP (Model Context Protocol) JSON-RPC servers.
- It provides a unified “entrypoint” MCP server (`src/parse_patrol/__main__.py`) which dynamically loads or proxies to individual parser servers (cclib, custom_gaussian, nomad, iodata_parser, etc.).
- Intended for IDE-integrated LLM agents (e.g., VS Code Copilot “Agent” mode) to invoke slash-commands, run parsing pipelines, and inspect results.

##### File structure
- Top-level directories:
- src/ : Python packages
– parse_patrol/  → central MCP server aggregator
– cclib/, custom_gaussian/, iodata_parser/, nomad/ → each its own MCP server entrypoint
- .vscode/ : IDE configuration, mcp.json template listing all servers
- .pipelines/ : example agent-generated scripts + test data
- .resources/ : schema docs (semantic & structure definitions)
- .data/ : real or downloaded data to parse (e.g., NOMAD downloads)
- tests/ : reference files for automated parser tests
- assets/ : images/videos (demo, documentation)
- Key config files:
- pyproject.toml & uv.lock → Python dependencies & virtual-env management via `uv`
- .vscode/mcp.json → registers each MCP server under a unique command

##### README for additional insights
- Describes:
- Supported servers (cclib, custom_gaussian; planned: openbabel, nomad-lab)
- Development & testing workflow (uv sync, uv run, MCP inspector)
- How to register new parsers (add server under src/parsers and wire into parse_patrol)
- Emphasizes:
- Microservice-style pattern: one MCP server per parser tool
- A unified interface for agents via the central parse_patrol server

a. Main components
1. IDE/Agent Client
- VS Code w/ Copilot “Agent” mode
- MCP inspector (browser UI)
2. MCP Server Layer
- Central aggregator (`parse_patrol`)
- Individual parser servers: cclib, custom_gaussian, nomad, iodata_parser
3. Data & Resources
- .data/ (downloaded data files)
- .pipelines/data/ (test inputs for pipelines)
- .resources/ (schema docs)
4. Pipelines & Tests
- .pipelines/scripts/ (agent-generated pipelines)
- tests/ (automated parser tests)
5. Dependency Manager
- `uv` tool / Python venv (pyproject.toml, uv.lock)
b. Relationships & interactions
- IDE/Agent → sends JSON-RPC requests over MCP protocol → central aggregator
- Aggregator → routes requests to appropriate parser server → runs parsing logic
- Parser server → reads input files from .data/ or .pipelines/data/ → returns parsed output
- Agent pipelines (.pipelines/scripts) may orchestrate multiple servers in sequence
- Tests → directly invoke servers (via uv run mcp dev) for CI
c. Architectural patterns & principles
- Microservice/plugin pattern: each parser is an independent MCP server
- Unified façade: `parse_patrol` acts as API gateway for all parsers
- JSON-RPC transport: decouples client (IDE/Agent) from Python implementation
- Modular resources: separate schema documentation and test data
d. Key technologies/frameworks
- Python (packages under src/)
- Model Context Protocol (MCP) / JSON-RPC
- uv (development tool for dependency sync & script execution)
- VS Code MCP extension for server management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% IDE/Agent Layer
    subgraph "IDE/Agent Layer"
        IDE_Agent["IDE/Agent Client<br/>(VS Code Copilot + MCP Inspector)"]:::frontend
        VscodeConf[".vscode/<br/>(MCP server registration)"]:::resource
    end

    %% MCP Server Layer
    subgraph "MCP Server Layer"
        Gateway["parse_patrol<br/>(MCP Gateway)"]:::service
        PPkg["parse_patrol Package"]:::service
        CCLib["cclib Server<br/>(MCP)"]:::service
        Gaussian["custom_gaussian Server<br/>(MCP)"]:::service
        Nomad["nomad Server<br/>(MCP)"]:::service
        Iodata["iodata_parser Server<br/>(MCP)"]:::service
    end

    %% Data & Resources
    subgraph "Data & Resources"
        Data_DS[".data/"]:::data
        Pipeline_Data[".pipelines/data/gaussian/"]:::data
        Resources[".resources/"]:::resource
        Schema1["semantic-schema.md"]:::resource
        Schema2["structure-schema.md"]:::resource
        Assets["assets/"]:::data
    end

    %% Pipelines & Tests
    subgraph "Pipelines & Tests"
        Script["example_gaussian_parser.py"]:::tool
        Tests["tests/"]:::tool
    end

    %% Dependency Manager
    subgraph "Dependency Manager"
        PyProj["pyproject.toml"]:::tool
        Lock["uv.lock"]:::tool
    end

    %% Connections
    IDE_Agent -->|"JSON-RPC over MCP"| Gateway
    VscodeConf -->|registers| Gateway

    Gateway -->|aggregates| CCLib
    Gateway -->|aggregates| Gaussian
    Gateway -->|aggregates| Nomad
    Gateway -->|aggregates| Iodata

    CCLib -->|reads/writes| Data_DS
    Gaussian -->|reads/writes| Pipeline_Data
    Nomad -->|reads/writes| Data_DS
    Iodata -->|reads/writes| Data_DS

    Script -->|orchestrates via MCP| Gateway
    Tests -->|CI invokes| CCLib
    Tests -->|CI invokes| Gaussian

    Resources -->|schemas| CCLib
    Resources -->|schemas| Gaussian
    Resources -->|schemas| Nomad
    Resources -->|schemas| Iodata

    Assets -->|demo media| IDE_Agent

    PyProj -->|defines deps| Gateway
    Lock -->|locks env| Gateway

    %% Click Events
    click Gateway "https://github.com/ndaelman-hu/parse-patrol/blob/main/src/parse_patrol/__main__.py"
    click PPkg "https://github.com/ndaelman-hu/parse-patrol/tree/main/src/parse_patrol/"
    click CCLib "https://github.com/ndaelman-hu/parse-patrol/blob/main/src/cclib/__main__.py"
    click Gaussian "https://github.com/ndaelman-hu/parse-patrol/blob/main/src/custom_gaussian/__main__.py"
    click Nomad "https://github.com/ndaelman-hu/parse-patrol/blob/main/src/nomad/__main__.py"
    click Iodata "https://github.com/ndaelman-hu/parse-patrol/blob/main/src/iodata_parser/__main__.py"
    click VscodeConf "https://github.com/ndaelman-hu/parse-patrol/tree/main/.vscode/"
    click Data_DS "https://github.com/ndaelman-hu/parse-patrol/tree/main/.data/"
    click Pipeline_Data "https://github.com/ndaelman-hu/parse-patrol/tree/main/.pipelines/data/gaussian/"
    click Script "https://github.com/ndaelman-hu/parse-patrol/blob/main/.pipelines/scripts/example_gaussian_parser.py"
    click Schema1 "https://github.com/ndaelman-hu/parse-patrol/blob/main/.resources/semantic-schema.md"
    click Schema2 "https://github.com/ndaelman-hu/parse-patrol/blob/main/.resources/structure-schema.md"
    click Tests "https://github.com/ndaelman-hu/parse-patrol/tree/main/tests/"
    click PyProj "https://github.com/ndaelman-hu/parse-patrol/blob/main/pyproject.toml"
    click Lock "https://github.com/ndaelman-hu/parse-patrol/blob/main/uv.lock"
    click Assets "https://github.com/ndaelman-hu/parse-patrol/tree/main/assets/"

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef data fill:#98FB98,stroke:#333,stroke-width:1px
    classDef resource fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tool fill:#FFD700,stroke:#333,stroke-width:1px
```
