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

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

📢 重命名：本软件包从版本0.2.0开始由nixmcp更名为mcp-nixos。请相应更新你的引用，或者选择继续活在过去——随你便。

这到底是什么鬼东西？

MCP-NixOS是一个模型上下文协议服务器，专门阻止你的AI助手对NixOS胡编乱造。让我们面对现实吧——比混乱的NixOS文档更糟糕的，就是一个AI自信满满地对其产生幻觉。

它提供实时访问：

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

快速开始：为慢性子急脾气准备

听着，我们都知道你只会草草浏览这份README然后在事情不work时抱怨。以下是启动的最低要求：

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

好了。现在你的AI助手终于能提供关于NixOS的正确信息，而不是从2019年的软件包名称开始产生幻觉了。不客气。

环境变量（给控制狂们）

*默认缓存位置(你的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顺便说一句"的苹果用户准备的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} - 你的苹果设备的选项详情
• darwin://options/prefix/{prefix} - 某个前缀下的所有选项
• darwin://options/{category} - 分类选项(系统、服务等)

工具：

• darwin_search(query) - 搜索macOS配置选项
• darwin_info(name) - 获取苹果不想让你知道的选项详情
• 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调用而不是mock因为我们不害怕现实世界：

# 运行含覆盖率的测试(默认推荐)
run-tests

# 运行不含覆盖率的测试(给那些喜欢快乐无知的人)
run-tests --no-coverage

代码覆盖率追踪在Codecov(我们假装关心100%覆盖率的地方)。

与LLM一起使用：这整个练习的重点

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

# 给困惑者的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

# 给苹果上瘾者的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雪花logo使用归属NixOS项目。详见归属信息。

由James Brink创建，自封为恐怖修补匠，不知怎么地居然能让东西工作。