# utensils/mcp-nixos architecture

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

- Interactive diagram: https://gitdiagram.com/utensils/mcp-nixos
- Repository: https://github.com/utensils/mcp-nixos

## Overview

##### Project Type and Purpose
- MCP-NixOS is primarily a stateless, async Python “Model Context Protocol” (MCP) server that supplies accurate NixOS package/configuration data to AI assistants.
- It also includes a companion static website (Next.js + Tailwind) for documentation and demos.
- There is no internal database or cache—data comes in real time from external services (search.nixos.org, NixHub.io).

##### File Structure
Top-level directories:
- mcp_nixos/
– Core Python package and server implementation (async FastMCP 2.x).
- tests/
– Extensive pytest suite validating CLI, HTTP handlers, data formatting, integration with real APIs.
- website/
– Next.js TypeScript app for docs, deployed via Netlify/Windsurf.
- .github/workflows/
– CI, code review, deployment pipelines for PyPI, Flakehub, website.
- Dockerfile, flake.nix, .envrc
– Build and dev-environment definitions (Docker, Nix flake).
- .claude/
– Agent and command definitions for self-hosting via Claude.

##### README for Additional Insights
- Stack: Python 3.11+, AsyncIO, FastMCP 2.x, ElasticSearch endpoint (search.nixos.org), HTTP clients.
- No persistent storage—stateless.
- External dependencies: NixOS API, NixHub API.
- CLI wrappers: uvx, nix run, docker run.
- Website stack: Next.js, React, Tailwind, Netlify.

##### Main Components and Their Relationships
a. MCP Server (Python)
- FastMCP 2.x engine exposes stdin/stdout protocol or HTTP if wrapped.
- Handlers implement: `nixos_search`, `nixos_info`, `nixos_stats`, `nixhub_package_versions`, etc.
- Async HTTP client calls out to:
– search.nixos.org ElasticSearch API
– NixHub.io REST endpoints
- Response formatting: plain text or JSON for AI clients.
b. Clients/Invocation Layers
- uvx CLI shim → stdin/stdout to server
- nix run wrapper → spawns Python server
- docker container → encapsulated Python server
c. Documentation Website (Next.js)
- Static pages (docs, usage, about) deployed to Netlify
- Components for code samples, navigation
d. CI/CD Pipelines
- GitHub Actions for: testing (pytest), linting (ruff), type checks (mypy), publishing to PyPI, deploying website, flake registry.

##### Architectural Patterns and Design Principles
- Micro-service style: single responsibility (MCP server) plus static site.
- Stateless API server: no disk caches, no DB, all data fetched per request.
- Async first: all handlers `await` HTTP calls.
- Separation of concerns: library code (mcp_nixos/) vs. CLI wrappers vs. docs site.
- Infrastructure as code: Dockerfile, Nix flake, GitHub workflows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        CLI["uvx CLI / IDE Plugin"]:::runtime
        ProtocolConfig["Protocol Config (.mcp.json)"]:::infra
    end

    %% Invocation Layers
    subgraph "Invocation Layers"
        nixrun["nix run (flake.nix)"]:::infra
        docker["Docker Container (Dockerfile)"]:::infra
    end

    %% MCP-NixOS Server
    subgraph "MCP-NixOS Server (Python FastMCP)" 
        MPServer["FastMCP Server\n(Python 3.11, AsyncIO)"]:::runtime
        server_py["server.py"]:::runtime
        init_py["__init__.py"]:::runtime
        pyproject["pyproject.toml"]:::infra
    end

    %% External APIs
    subgraph "External APIs" 
        NixOSAPI["search.nixos.org ElasticSearch API"]:::external
        NixHubAPI["NixHub.io REST API"]:::external
    end

    %% Documentation Site
    subgraph "Documentation Site (Next.js + Tailwind)"
        Site["Static Docs Site"]:::docs
        page_ts["app/page.tsx"]:::docs
        docs_html["app/docs/claude.html"]:::docs
        usage["app/usage/page.tsx"]:::docs
        about["app/about/page.tsx"]:::docs
        components["components/"]:::docs
        public["public/"]:::docs
        netlify["netlify.toml"]:::infra
        nextconf["next.config.js"]:::infra
        tailwind["tailwind.config.js"]:::infra
    end

    %% Test Suite
    subgraph "Test Suite (pytest)"
        tests_suite["tests/"]:::infra
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines (GitHub Actions)"
        CI["GitHub Actions"]:::infra
        ci_yml["ci.yml"]:::infra
        publish_yml["publish.yml"]:::infra
        deploy_site["deploy-website.yml"]:::infra
        deploy_flakehub["deploy-flakehub.yml"]:::infra
        claude_cr["claude-code-review.yml"]:::infra
        claude_yml["claude.yml"]:::infra
    end

    %% Interactions
    CLI -->|"stdin/stdout MCP Protocol"| MPServer
    ProtocolConfig -->|configures| MPServer
    nixrun -->|launches| MPServer
    docker -->|containers| MPServer

    MPServer -->|"HTTPS request"| NixOSAPI
    MPServer -->|"HTTPS request"| NixHubAPI

    tests_suite -->|validates| MPServer

    CI -->|test & lint| tests_suite
    CI -->|publish| pyproject
    CI -->|deploy| deploy_site
    CI -->|deploy| deploy_flakehub

    CI -->|triggers| CI
    CI -->|code-review| claude_cr
    CI -->|agent workflows| claude_yml

    %% Styles
    classDef runtime fill:#e0ffd4,stroke:#339933,stroke-width:1px
    classDef external fill:#d4e0ff,stroke:#333399,stroke-width:1px
    classDef infra fill:#ffe0b3,stroke:#cc6600,stroke-width:1px
    classDef docs fill:#f0d4ff,stroke:#993399,stroke-width:1px

    %% Click Events
    click server_py "https://github.com/utensils/mcp-nixos/blob/main/mcp_nixos/server.py"
    click init_py "https://github.com/utensils/mcp-nixos/blob/main/mcp_nixos/__init__.py"
    click pyproject "https://github.com/utensils/mcp-nixos/blob/main/pyproject.toml"
    click ProtocolConfig "https://github.com/utensils/mcp-nixos/blob/main/.mcp.json"
    click nixrun "https://github.com/utensils/mcp-nixos/blob/main/flake.nix"
    click docker "https://github.com/utensils/mcp-nixos/tree/main/Dockerfile"
    click tests_suite "https://github.com/utensils/mcp-nixos/tree/main/tests/"
    click page_ts "https://github.com/utensils/mcp-nixos/blob/main/website/app/page.tsx"
    click docs_html "https://github.com/utensils/mcp-nixos/blob/main/website/app/docs/claude.html"
    click usage "https://github.com/utensils/mcp-nixos/blob/main/website/app/usage/page.tsx"
    click about "https://github.com/utensils/mcp-nixos/blob/main/website/app/about/page.tsx"
    click components "https://github.com/utensils/mcp-nixos/tree/main/website/components/"
    click public "https://github.com/utensils/mcp-nixos/tree/main/website/public/"
    click netlify "https://github.com/utensils/mcp-nixos/blob/main/website/netlify.toml"
    click nextconf "https://github.com/utensils/mcp-nixos/blob/main/website/next.config.js"
    click tailwind "https://github.com/utensils/mcp-nixos/blob/main/website/tailwind.config.js"
    click ci_yml "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/ci.yml"
    click publish_yml "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/publish.yml"
    click deploy_site "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/deploy-website.yml"
    click deploy_flakehub "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/deploy-flakehub.yml"
    click claude_cr "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/claude-code-review.yml"
    click claude_yml "https://github.com/utensils/mcp-nixos/blob/main/.github/workflows/claude.yml"
```
