How utensils/mcp-nixos works
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.