MCP-NixOS - 因为你的 AI 助手不应该对软件包产生幻觉

⚠️ 活跃开发中: 该包正处于活跃开发阶段。就像我的职业选择一样，它在不断进化。

📢 重命名: 从版本 0.2.0 开始，该包已从 nixmcp 重命名为 mcp-nixos。请相应地更新您的引用，或者继续活在过去——由您选择。

这到底是个什么东西？

MCP-NixOS 是一个模型上下文协议服务器，可以防止你的 AI 助手编造关于 NixOS 的内容。因为坦白说，比令人困惑的 NixOS 文档更糟糕的事情就是 AI 自信地对它进行臆想。

它提供了实时访问以下内容的功能：

• NixOS 软件包（是的，那些实际存在的）
• 系统选项（你将花费数小时配置的那些）
• Home Manager 设置（当系统级混乱还不够时）
• nix-darwin macOS 配置（因为苹果用户也需要复杂性）

快速开始：给那些急性子

我们都知道你只会草草浏览这个 README，然后在事情不工作时抱怨。这里是最基本的入门步骤：

{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": ["mcp-nixos"]
    }
  }
}

好了。现在你的 AI 助手可以提供关于 NixOS 的正确信息，而不是臆想 2019 年的软件包名称了。不用谢我。

环境变量（针对控制狂）

变量	描述	默认值
MCP_NIXOS_LOG_LEVEL	你想了解多少关于失败的信息	INFO
MCP_NIXOS_LOG_FILE	记录这些失败的地方	（无处记录—你的秘密很安全）
MCP_NIXOS_CACHE_DIR	存储你将忘记的内容的地方	操作系统特定的缓存位置*
MCP_NIXOS_CACHE_TTL	缓存失效前的时间（以秒为单位）	86400 (24小时)
MCP_NIXOS_CLEANUP_ORPHANS	启动时是否清理孤儿 MCP 进程	false
KEEP_TEST_CACHE	保留测试缓存目录用于调试（仅限开发）	false
ELASTICSEARCH_URL	NixOS Elasticsearch API URL	https://search.nixos.org/backend

*默认缓存位置（你的 GB 将悄悄消失的地方）:

• Linux: ~/.cache/mcp_nixos/（因为 ~/.cache 还不够乱）
• macOS: ~/Library/Caches/mcp_nixos/（藏在一个你永远不会去查看的地方）
• Windows: %LOCALAPPDATA%\mcp_nixos\Cache\（迷失在 Windows 目录的深渊中）

可能实际有效的功能

• NixOS 资源：通过 Elasticsearch API 获取包和系统选项
  • 多个渠道：不稳定版（适用于勇敢者）、稳定版（适用于无聊者）和特定版本
  • 详细的包元数据，告诉你除如何让它工作之外的一切信息
• Home Manager：通过解析文档获取用户配置选项
  • 程序、服务和设置，你会花整个周末来配置它们
  • 当你需要变得极其具体时使用的分层路径
• nix-darwin：为那些“顺便说一下我用 NixOS”的 Apple 用户提供的 macOS 配置
  • 系统默认值、服务和设置，苹果公司从未打算让你触碰
  • 以新的和令人兴奋的方式破坏你的 Mac！
• 智能缓存：因为没有人愿意等待 Elasticsearch 查询
  • 减少网络请求并提高启动时间
  • 一旦缓存后即可离线工作（非常适合下一次互联网中断时使用）
• 丰富的搜索：找到你需要的东西或差不多的东西
  • 惊人地不糟糕的快速内存搜索引擎
  • 当你不确定自己在找什么时的相关选项

MCP 资源与工具：你不知道自己需要的强大工具

NixOS：让你同时感到聪明又愚蠢的操作系统

资源：

• nixos://package/{name} - 找到你确定存在的那个包
• nixos://search/packages/{query} - 搜索可能存在的包
• nixos://search/options/{query} - 搜索你可能会误配置的系统选项
• nixos://option/{name} - 获取你仍然会搞砸的选项信息
• nixos://search/programs/{name} - 查找提供程序的包
• nixos://packages/stats - 统计数据，用来向你的极客朋友炫耀

工具：

• nixos_search(query, type, channel) - 你最常使用的搜索函数
• nixos_info(name, type, channel) - 获取包或选项的详细信息
• nixos_stats(channel) - 获取没人问过的 NixOS 统计数据

渠道：

• unstable（默认）- 生活在边缘地带，没有什么是稳定的，包括你的理智
• stable（24.11）- 对于那些喜欢按计划崩溃的人
• 旧版本 - 当你想念早期失败的时候

Home Manager：因为全系统配置还不够复杂

资源：

• home-manager://search/options/{query} - 搜索用户配置选项
• home-manager://option/{name} - 你会截图保存以备后用的选项详情
• home-manager://options/prefix/{prefix} - 指定前缀下的所有选项
• home-manager://options/{category} - 类别选项（程序、服务等）

工具：

• home_manager_search(query) - 搜索配置选项
• home_manager_info(name) - 获取带有实际解释的选项详情
• home_manager_options_by_prefix(option_prefix) - 通过前缀获取选项
• home_manager_list_options() - 当选项太多时列出所有选项类别

nix-darwin: 为那些渴望痛苦的 Mac 用户

资源：

• darwin://search/options/{query} - 搜索 macOS 选项
• darwin://option/{name} - 为您的 Apple 设备获取选项详情
• darwin://options/prefix/{prefix} - 获取某个前缀下的所有选项
• darwin://options/{category} - 类别选项（系统、服务等）

工具：

• darwin_search(query) - 搜索 macOS 配置选项
• darwin_info(name) - 获取 Apple 不想让你知道的选项详情
• darwin_options_by_prefix(option_prefix) - 通过前缀获取选项
• darwin_list_options() - 列出所有选项类别

工具使用示例（可直接复制粘贴）

# NixOS examples for when you're pretending to know what you're doing
nixos_search(query="firefox", type="packages", channel="unstable")
nixos_search(query="postgresql", type="options", channel="stable")
nixos_info(name="firefox", type="package")
nixos_info(name="services.postgresql.enable", type="option")

# Home Manager examples for the domestic configuration enthusiasts
home_manager_search(query="programs.git")
home_manager_info(name="programs.firefox.enable")
home_manager_options_by_prefix(option_prefix="programs.git")

# nix-darwin examples for the masochistic Mac users
darwin_search(query="system.defaults.dock")
darwin_info(name="services.yabai.enable")
darwin_options_by_prefix(option_prefix="system.defaults")

安装与配置：你可能会跳过的部分

安装它（选择你喜欢的方式）

# Option 1: Install with pip like a normie
pip install mcp-nixos

# Option 2: Install with uv because you're too cool for pip
uv pip install mcp-nixos

# Option 3: Run directly with uvx (recommended for the truly enlightened)
uvx --install-deps mcp-nixos

配置它（这部分你肯定会搞砸）

在你的 MCP 配置文件中添加（例如 ~/.config/claude/config.json）：

{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": ["mcp-nixos"]
    }
  }
}

对于使用源代码进行开发（适合喜欢自找麻烦的人）：

{
  "mcpServers": {
    "nixos": {
      "command": "uv",
      "args": ["run", "-m", "mcp_nixos.__main__"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

缓存与渠道：魔法发生的地方，也是文件消失的地方

缓存系统：

• 默认位置，你会在5分钟后忘记
• 存储 HTML 内容、序列化数据和搜索索引
• 一旦缓存，可以离线工作（唯一一个你会真正欣赏的功能）

NixOS 渠道：

• unstable: 最新的 NixOS 不稳定版本（适用于冒险者）
• stable: 当前稳定版本（适用于风险厌恶者）
• 24.11: 特定版本引用（适用于历史爱好者）

开发：对于那些不满足于仅仅使用东西的人来说

依赖项（因为现在没有什么是独立存在的了）

这个项目使用 pyproject.toml，因为我们不是野兽。

# Install development dependencies for the brave
pip install -e ".[dev]"

# Or with uv (recommended for the enlightened)
uv pip install -e ".[dev]"

使用 Nix（当然有一个 Nix 开发环境）

# Enter dev shell and see available commands
nix develop && menu

# Common commands for common folk
run         # Start the server (and your journey into madness)
run-tests   # Run tests with coverage (expose the flaws)
lint        # Format and lint code (fix the mess you made)
publish     # Build and publish to PyPI (share your pain)

测试（是的，我们真的这样做）

测试使用真实的 Elasticsearch API 调用而不是模拟，因为我们不怕现实世界：

# Run tests with coverage (default and recommended)
run-tests

# Run tests without coverage (for those who prefer blissful ignorance)
run-tests --no-coverage

代码覆盖率在 Codecov 上跟踪（我们在那里假装关心 100% 的覆盖率）。

与 LLM 一起使用：这次练习的全部意义

配置完成后，使用 MCP-NixOS 与支持 MCP 的模型进行提示：

# NixOS resources for the confused
~nixos://package/python
~nixos://option/services.nginx
~nixos://search/packages/firefox

# Home Manager resources for the domestically challenged
~home-manager://search/options/programs.git
~home-manager://option/programs.firefox.profiles

# nix-darwin resources for the Apple addicted
~darwin://search/options/system.defaults.dock

# NixOS tools for the tool-inclined
~nixos_search(query="postgresql", type="options")
~nixos_info(name="firefox", type="package", channel="unstable")

# Home Manager tools for home improvement
~home_manager_search(query="programs.zsh")
~home_manager_info(name="programs.git.userName")

# nix-darwin tools for the Mac masochists
~darwin_search(query="services.yabai")
~darwin_info(name="system.defaults.dock.autohide")

LLM 将通过 MCP 服务器获取信息，并可能最终给你正确的信息。

实现细节：纸牌屋揭秘

代码架构：我们是如何让它工作的（尽管困难重重）

MCP-NixOS 组织成模块化结构，尽管困难重重，但仍然设法工作：

• mcp_nixos/cache/ - 缓存组件，节省你的带宽并保持理智
• mcp_nixos/clients/ - 与Elasticsearch通信并解析HTML文档的API客户端
• mcp_nixos/contexts/ - 上下文对象，防止一切分崩离析
• mcp_nixos/resources/ - 所有平台的MCP资源定义
• mcp_nixos/tools/ - 实际工作的MCP工具实现
• mcp_nixos/utils/ - 工具函数，因为我们不是野蛮人
• mcp_nixos/server.py - 将这个纸牌屋粘合在一起的胶水

NixOS API集成：外部连接

通过以下方式连接到NixOS Elasticsearch API：

• 多通道支持（不稳定、稳定/24.11）
• 针对特定字段的搜索提升以提高相关性
• 错误处理，期望最坏的情况但希望最好的结果（我的生活故事）

HTML文档解析器：梦想破灭之地

对于Home Manager和nix-darwin选项，我们在HTML解析方面犯下了罪行：

1. 文档解析器：通过BeautifulSoup咒语、正则表达式黑魔法以及连续72小时盯着格式错误的HTML所产生的决心，提取结构化数据。

2. 搜索引擎：拼凑而成：

   • 倒排索引用于快速文本搜索（当它不崩溃时）
   • 前缀树用于层次查找（凌晨3点时似乎是个好主意）
   • 结果评分基于一种最好描述为“基于感觉排序”的算法

3. 缓存系统：因为解析一次HTML已经够痛苦了：

   • 存储HTML内容、处理过的数据结构和搜索索引
   • 使用特定于平台的缓存位置，所以你不必为此操心
   • 实现基于TTL的过期机制以在需要时刷新内容
   • 当事情不可避免地出错时优雅地回退（不像我的人际关系）

什么是模型上下文协议？

对于那些直接跳到最后的人

模型上下文协议 (MCP) 是一个开放协议，使用JSON消息通过stdin/stdout将大语言模型连接到外部数据和工具。该项目实现了MCP，使AI助手能够访问NixOS、Home Manager和nix-darwin资源，这样它们终于可以停止对你操作系统的胡编乱造了。

许可证

MIT（因为我不是怪物）

NixOS雪花标志归功于NixOS项目。有关详细信息，请参见归属信息。

---

由James Brink创建，自称恐怖的修补匠，尽管他自己也能让事情运作起来。