MCP-NixOS - 因为你的 AI 助手不应该胡编乱造软件包

⚠️ 积极开发中: 这个软件包正在积极开发中。就像我的职业选择一样，它在不断发展。

📢 已重命名: 这个软件包在 0.2.0 版本中从 nixmcp 重命名为 mcp-nixos。请相应地更新你的引用，或者继续活在过去——你自己选择。

这到底是个什么玩意儿？

MCP-NixOS 是一个模型上下文协议服务器，它可以阻止你的 AI 助手胡编乱造关于 NixOS 的信息。因为让我们面对现实吧——唯一比混淆 NixOS 文档更糟糕的事情是 AI 自信地胡说八道。

它提供对以下内容的实时访问：

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

快速开始：为那些慢性不耐烦的人准备的

听着，我们都知道你只会浏览一下这个 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 (24h)
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 获取软件包和系统选项
  • 多个频道：unstable（为勇敢者准备的），stable（为无聊者准备的），以及特定版本
  • 详细的软件包元数据，告诉你除了如何让它工作之外的一切
• Home Manager: 通过解析文档获取用户配置选项
  • 你将花费周末配置的程序、服务和设置
  • 分层路径，当你想要变得极其具体时
• nix-darwin: 为 "顺便说一句，我使用 NixOS" 的 Apple 用户准备的 macOS 配置
  • Apple 从未打算让你接触的系统默认设置、服务和设置
  • 以新的和令人兴奋的方式破坏你的 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 示例，当你假装知道你在做什么时
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 示例，为家庭配置爱好者准备的
home_manager_search(query="programs.git")
home_manager_info(name="programs.firefox.enable")
home_manager_options_by_prefix(option_prefix="programs.git")

# nix-darwin 示例，为受虐狂 Mac 用户准备的
darwin_search(query="system.defaults.dock")
darwin_info(name="services.yabai.enable")
darwin_options_by_prefix(option_prefix="system.defaults")

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

安装它（选择你的毒药）

# 选项 1：像个普通人一样用 pip 安装
pip install mcp-nixos

# 选项 2：用 uv 安装，因为你太酷了，不屑用 pip
uv pip install mcp-nixos

# 选项 3：直接用 uvx 运行（推荐给真正开悟的人）
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 unstable（为大胆者准备的）
• stable: 当前稳定版本（为规避风险者准备的）
• 24.11: 特定版本参考（为有历史倾向的人准备的）

开发：为那些不满足于仅仅使用东西的人准备的

依赖项（因为没有什么可以独立存在了）

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

# 为勇敢者安装开发依赖项
pip install -e ".[dev]"

# 或者用 uv（推荐给开悟的人）
uv pip install -e ".[dev]"

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

# 进入开发 shell 并查看可用命令
nix develop && menu

# 普通人的常用命令
run         # 启动服务器（以及你进入疯狂的旅程）
run-tests   # 运行带有覆盖率的测试（暴露缺陷）
lint        # 格式化和 lint 代码（修复你造成的混乱）
publish     # 构建并发布到 PyPI（分享你的痛苦）

测试（是的，我们实际上会这样做）

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

# 运行带有覆盖率的测试（默认且推荐）
run-tests

# 运行没有覆盖率的测试（为那些喜欢幸福的无知的人准备的）
run-tests --no-coverage

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

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

配置完成后，在你的提示中使用带有 MCP 兼容模型的 MCP-NixOS：

# 为困惑的人准备的 NixOS 资源
~nixos://package/python
~nixos://option/services.nginx
~nixos://search/packages/firefox

# 为家庭挑战者准备的 Home Manager 资源
~home-manager://search/options/programs.git
~home-manager://option/programs.firefox.profiles

# 为 Apple 上瘾者准备的 nix-darwin 资源
~darwin://search/options/system.defaults.dock

# 为工具爱好者准备的 NixOS 工具
~nixos_search(query="postgresql", type="options")
~nixos_info(name="firefox", type="package", channel="unstable")

# 为家庭改善准备的 Home Manager 工具
~home_manager_search(query="programs.zsh")
~home_manager_info(name="programs.git.userName")

# 为 Mac 受虐狂准备的 nix-darwin 工具
~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：

• 多频道支持（unstable、stable/24.11）
• 针对特定字段的搜索提升，以获得更好的相关性
• 期望最坏的情况但希望最好的错误处理（我的人生写照）

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

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

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

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

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

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

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

什么是模型上下文协议？

为那些直接跳到结尾的人准备的

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

许可证

MIT（因为我不是怪物）

NixOS 雪花标志的使用归功于 NixOS 项目。有关详细信息，请参阅署名信息。

---

由 James Brink 创建，自称恐怖修补匠，他以某种方式设法使事情正常工作，尽管他自己也做不到。