# riemannzeta/patent_mcp_server architecture

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

- Interactive diagram: https://gitdiagram.com/riemannzeta/patent_mcp_server
- Repository: https://github.com/riemannzeta/patent_mcp_server

## Overview

##### Project type and purpose
- This is a backend‐only service (“Patent MCP Server”) implementing the Model Context Protocol (MCP).
- It exposes an MCP endpoint over stdio, allowing a client (Claude Desktop or any MCP client) to issue patent‐related requests.
- Internally, it wraps two external USPTO APIs: the Patent Public Search (“ppubs.uspto.gov”) and the Open Data Portal (“api.uspto.gov”).

##### File structure
- Top level:
- setup.py, pyproject.toml, UV config for packaging and dependency management
- src/patent_mcp_server – main Python package
- json/ & pdfs/ – sample data and PDF artifacts
- test/ – unit tests and stored responses
- src/patent_mcp_server:
- __main__.py – entry point wiring into FastMCP server
- patents.py – core MCP handlers that map incoming method calls to logic
- uspto/api_uspto_gov.py & ppubs_uspto_gov.py – thin clients for the two USPTO endpoints
- util/logging.py – shared logging setup
- json/search_query.json – sample request schema
- test/ exercises every MCP method, validating against stored JSON and PDF responses.

##### README for insights
- Confirms stdio transport for MCP protocol.
- Lists available methods (ppubs_search_patents, get_app_metadata, etc.).
- Clarifies dependencies on Claude Desktop (client) and on a PATENTS_MCP_SERVER_ODP_API_KEY.
- Explains role of UV for launching the server: “uv run patent-mcp-server”.

a. Main components
- Client (Claude Desktop or any MCP client)
- MCP Server Process
- Internal modules: Request Router, Handler Layer, API Clients, Logging Utility
- External USPTO services: Public Search API and Open Data Portal API
- Local resources: sample JSON, PDF cache
b. Relationships & data flow
1. Client → (stdio JSON‐RPC) → MCP Server
2. Router in __main__.py dispatches to handlers in patents.py
3. Handler invokes one of two API client modules
4. API client issues HTTP request to USPTO endpoint
5. Response flows back to handler → Router → Client over stdio
6. Logging utility records both incoming requests and external API calls
7. Tests simulate this flow using local test data
c. Architectural patterns & design principles
- Layered architecture: Transport → Routing → Business logic → External adapters
- Single‐responsibility modules: each USPTO API lives in its own adapter
- Configuration via environment (.env) and UV for reproducible environments
d. Key technologies & frameworks
- Python 3.x, FastMCP server library
- UV for dependency/version management
- Requests or HTTPX (inside API client modules)
- pytest or built‐in test runner for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Claude Desktop<br/>(MCP Client)"]:::client

    %% MCP Server Container
    subgraph "MCP Server" 
        direction TB
        Router["Request Router<br/>(__main__.py)"]:::internal
        Handlers["Handler Layer<br/>(patents.py)"]:::internal
        Logger["Logging Utility<br/>(logging.py)"]:::internal
        subgraph "USPTO Adapters"
            direction TB
            PpubsClient["Public Search Adapter<br/>(ppubs_uspto_gov.py)"]:::internal
            OdpClient["Open Data Portal Adapter<br/>(api_uspto_gov.py)"]:::internal
        end
        Schema["Sample Request Schema<br/>(search_query.json)"]:::local
    end

    %% External USPTO Services
    subgraph "External USPTO Services"
        direction TB
        USPTO1["Patent Public Search API"]:::external
        USPTO2["Open Data Portal API"]:::external
    end

    %% Local Resources & Tests
    subgraph "Local Resources & Tests"
        direction TB
        JSONCache["Local JSON Test Data"]:::local
        PDFCache["Local PDF Artifacts"]:::local
        Tests["Unit Tests<br/>(test_patents.py)"]:::local
        Results["Stored Test Responses"]:::local
    end

    %% Packaging & Docs
    Packaging["setup.py<br/>pyproject.toml"]:::docs
    README["README.md"]:::docs

    %% Data Flows
    Client -->|"JSON-RPC over STDIO"| Router
    Router -->|dispatch| Handlers
    Handlers -->|invoke| PpubsClient
    Handlers -->|invoke| OdpClient
    PpubsClient -->|"HTTP(S) call"| USPTO1
    OdpClient -->|"HTTP(S) call"| USPTO2
    USPTO1 -->|"JSON response"| PpubsClient
    USPTO2 -->|"JSON/PDF response"| OdpClient
    PpubsClient -->|return data| Handlers
    OdpClient -->|return data| Handlers
    Handlers -->|route response| Router
    Router -->|"JSON-RPC response"| Client
    Router -->|logs| Logger
    Handlers -->|logs| Logger
    PpubsClient -->|logs| Logger
    OdpClient -->|logs| Logger

    %% Tests using local resources
    Tests -.->|use| Router
    Tests -.->|use| Handlers
    Tests -->|validate against| JSONCache
    Tests -->|validate against| PDFCache
    Tests -->|validate outputs| Results

    %% Packaging & Docs usage
    Router -.->|configured by| Packaging
    Router -.->|documented in| README

    %% Click Events
    click Router "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/__main__.py"
    click Handlers "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/patents.py"
    click PpubsClient "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/uspto/ppubs_uspto_gov.py"
    click OdpClient "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/uspto/api_uspto_gov.py"
    click Logger "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/util/logging.py"
    click Schema "https://github.com/riemannzeta/patent_mcp_server/blob/main/src/patent_mcp_server/json/search_query.json"
    click JSONCache "https://github.com/riemannzeta/patent_mcp_server/tree/main/json/"
    click PDFCache "https://github.com/riemannzeta/patent_mcp_server/tree/main/pdfs/"
    click Tests "https://github.com/riemannzeta/patent_mcp_server/blob/main/test/test_patents.py"
    click Results "https://github.com/riemannzeta/patent_mcp_server/tree/main/test/test_results/"
    click Packaging "https://github.com/riemannzeta/patent_mcp_server/blob/main/setup.py"
    click Packaging "https://github.com/riemannzeta/patent_mcp_server/blob/main/pyproject.toml"
    click README "https://github.com/riemannzeta/patent_mcp_server/blob/main/README.md"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef external fill:#c4f0c5,stroke:#000,stroke-width:1px
    classDef local fill:#ffe5b4,stroke:#000,stroke-width:1px
    classDef client fill:#f0f0f0,stroke:#000,stroke-width:1px
    classDef docs fill:#e2e2e2,stroke:#000,stroke-width:1px
```
