# hottechstack/polars-docs-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/hottechstack/polars-docs-mcp
- Repository: https://github.com/hottechstack/polars-docs-mcp

## Overview

##### Project type and purpose
- This is an open‑source “Micro‑service Command Protocol” (MCP) tool written in Python.
- It exposes a small HTTP/CLI server (via the `uv` runner) that introspects the Polars library at runtime to answer API‑lookup requests.
- There is no web frontend; the primary “client” is any LLM or tool that speaks the MCP protocol (e.g., Claude Desktop).

##### File structure
Top level:
- polarsdocsfinder.py – the single Python entrypoint implementing the MCP server and documentation‑search functions
- pyproject.toml – Python project configuration (dependencies, entrypoints)
- resources/ – static assets (screenshots for docs/testing)
- README.md, LICENSE, .gitignore, .python‑version, uv.lock – project metadata and lockfile
There are no separate frontend/backend directories; the entire logic lives in the one script.

##### Key insights from README
- Uses Python 3.11+ introspection to “reflectively discover” every public Polars symbol.
- Exposes three endpoints:
· list_polars_components()
· search_polars_docs()
· verify_polars_api()
- Integrates with `uv run polarsdocsfinder.py` under the Model Context Protocol (MCP).

a. MCP Client (e.g., Claude Desktop)
b. MCP Configuration (JSON snippet in README)
c. MCP Server runner (`uv` CLI)
d. Python MCP Server (`polarsdocsfinder.py`)
e. Polars Library (external dependency, installed via pip)
f. Output JSON payloads

##### Relationships and interactions
1. The MCP Client (LLM or CLI inspector) sends an HTTP or stdio request (via MCP protocol) to the MCP Server.
2. The MCP Server is launched by the `uv` runner on the host.
3. `polarsdocsfinder.py` receives the request, introspects Polars to implement the requested function, then returns a JSON response.
4. The client consumes and displays the structured JSON (signatures, descriptions).

##### Architectural patterns and design principles
- Microservice / single‑responsibility: one script that does one job.
- Reflective introspection instead of web‑scraping or database caching.
- Plug‑and‑play via MCP: any tool speaking the protocol can mount this service.
- Minimal dependencies (Polars + standard library + MCP infra).

##### Technologies, frameworks, libraries
- Python 3.11
- Polars library (data‑frame API)
- Model Context Protocol (MCP) / uv CLI runner
- JSON for payloads

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External/System Components
    client["MCP Client<br/>(Claude Desktop or Inspector)"]:::external
    library["Polars Library"]:::external
    response["JSON Response"]:::external

    %% Invocation/Runtime Components
    config["MCP Configuration (JSON)"]:::invocation
    uv["uv Runner"]:::invocation

    %% Core Logic
    server["Python MCP Server<br/>(polarsdocsfinder.py)"]:::core

    %% Connections
    client -->|"list_polars_components()<br/>search_polars_docs()<br/>verify_polars_api()"| uv
    config -->|"used by"| uv
    uv -->|"launch service"| server
    server -->|"reflective introspection"| library
    server -->|"JSON payload"| response
    response -->|"return to client"| client

    %% Click Events
    click server "https://github.com/hottechstack/polars-docs-mcp/blob/main/polarsdocsfinder.py"
    click config "https://github.com/hottechstack/polars-docs-mcp/blob/main/README.md"
    click uv "https://github.com/hottechstack/polars-docs-mcp/blob/main/uv.lock"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef invocation fill:#90EE90,stroke:#000,stroke-width:1px
    classDef core fill:#FFA500,stroke:#000,stroke-width:1px
```
