MCP-NixOS - 因为你的AI助手不应该对包进行幻想

🎉 重构完成: 版本1.0.0是一个完全重写的版本，极大地简化了所有内容。我们移除了所有的复杂缓存、抽象和“企业”模式。因为有时候少即是多，而多只是炫耀。

🚀 异步更新: 版本1.0.1迁移到了FastMCP 2.x以实现现代异步特性。因为谁不喜欢在一切中添加await呢？

快速开始（因为你现在就想用它）

🚨 不需要Nix/NixOS！ 这个工具可以在任何系统上运行 - Windows、macOS、Linux。你只是查询Web API。

选项1：使用uvx（推荐给大多数用户）

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

选项2：使用Nix（针对Nix用户）

{
  "mcpServers": {
    "nixos": {
      "command": "nix",
      "args": ["run", "github:utensils/mcp-nixos", "--"]
    }
  }
}

选项3：使用Docker（容器爱好者）

{
  "mcpServers": {
    "nixos": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"]
    }
  }
}

就这样。你的AI助手现在可以访问真实的NixOS数据，而不是编造信息。不客气。

这是什么？

MCP-NixOS是一个模型上下文协议服务器，它为你的AI助手提供准确、实时的信息：

• NixOS包（超过130K实际存在的包）
• 配置选项（超过22K种方式来破坏你的系统）
• Home Manager设置（超过4K个高级用户的选项）
• nix-darwin配置（超过1K个Apple不想让你触碰的macOS设置）
• 通过NixHub.io的包版本历史

你真正关心的工具

🔍 NixOS工具

• nixos_search(query, type, channel) - 搜索包、选项或程序
• nixos_info(name, type, channel) - 获取包或选项的详细信息
• nixos_stats(channel) - 包和选项的数量统计
• nixos_channels() - 列出所有可用的通道
• nixos_flakes_search(query) - 搜索社区flakes
• nixos_flakes_stats() - flakes生态系统统计数据

📦 版本历史工具（新！）

• nixhub_package_versions(package, limit) - 获取带有提交哈希的版本历史
• nixhub_find_version(package, version) - 智能搜索特定版本

🏠 Home Manager工具

• home_manager_search(query) - 搜索用户配置选项
• home_manager_info(name) - 获取选项详情（附带建议！）
• home_manager_stats() - 查看可用选项
• home_manager_list_options() - 浏览所有131个类别
• home_manager_options_by_prefix(prefix) - 按前缀探索选项

🍎 Darwin工具

• darwin_search(query) - 搜索macOS选项
• darwin_info(name) - 获取选项详情
• darwin_stats() - macOS配置统计数据
• darwin_list_options() - 浏览所有21个类别
• darwin_options_by_prefix(prefix) - 探索macOS选项

安装选项

记住：你不需要安装Nix/NixOS！ 这个工具可以在任何Python运行的地方运行。

对于普通人类（Windows/Mac/Linux）

# 直接运行uvx（无需安装）
uvx mcp-nixos

# 或者全局安装
pip install mcp-nixos
uv pip install mcp-nixos

对于Nix用户（你知道你是谁）

# 无需安装运行
nix run github:utensils/mcp-nixos

# 安装到profile
nix profile install github:utensils/mcp-nixos

值得一提的功能

🚀 版本1.0.1：异步革命（在大简化之后）

• 代码量大幅减少 - 版本1.0.0删除了几千行代码，版本1.0.1使其异步化
• 100%功能 - 所有功能仍然有效，现在有更多的await
• 0%缓存损坏 - 因为我们完全移除了缓存（仍然没有！）
• 无状态操作 - 没有文件需要清理（异步不会改变这一点）
• 直接API访问 - 没有抽象废话（但现在的异步是废话）
• 现代MCP - FastMCP 2.x因为旧的MCP太同步了

📊 你得到什么

• 实时数据 - 始终最新，永不陈旧
• 纯文本输出 - 适合人和AI阅读
• 智能建议 - 当你打错选项名时帮助你
• 跨平台 - 在Linux、macOS甚至Windows上都能运行
• 无需配置 - 它就是工作™

🎯 关键改进

• 动态通道解析 - stable始终指向当前稳定版
• 增强的错误消息 - 当出现问题时实际上有帮助
• 去重flake结果 - 没有多余的重复垃圾
• 版本感知搜索 - 找到你需要的那个旧Ruby版本
• 分类浏览 - 系统地探索选项

开发者指南（勇敢的人）

本地开发设置

想在Claude Code或其他MCP客户端中测试你的更改？在项目目录中创建一个.mcp.json文件：

{
  "mcpServers": {
    "nixos": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/hackerman/Projects/mcp-nixos",
        "mcp-nixos"
      ]
    }
  }
}

将/home/hackerman/Projects/mcp-nixos替换为你实际的项目路径（包括Windows用户，如C:\Users\CoolDev\...）。

这个.mcp.json文件：

• 自动激活当你从项目目录启动Claude Code时
• 使用你的本地代码而不是已安装的包
• 启用实时测试 - 更改后只需重启Claude Code
• 已经加入.gitignore所以你不会意外提交你的路径

使用Nix（祝福之路）

nix develop
menu  # 显示所有可用命令

# 常见任务
run        # 启动服务器（现在有了FastMCP！）
run-tests  # 运行所有测试（现在异步！）
lint       # 格式化并检查代码（ruff取代了black/flake8）
typecheck  # 检查类型（mypy仍然评判你）
build      # 构建包
publish    # 上传到PyPI（需要凭据）

不使用Nix（痛苦之路）

# 安装开发依赖
uv pip install -e ".[dev]"  # 或者 pip install -e ".[dev]"

# 本地运行服务器
uv run mcp-nixos  # 或者 python -m mcp_nixos.server

# 开发命令
pytest tests/          # 现在有了asyncio特性
ruff format mcp_nixos/ # black是2023年的产物
ruff check mcp_nixos/  # flake8是老古董
mypy mcp_nixos/        # 依然非常挑剔

# 构建和发布
python -m build        # 构建分发包
twine upload dist/*    # 上传到PyPI

测试哲学

• 367个测试实际测试内容（现在异步因为为什么不做）
• 真实API调用因为模拟是胆小鬼的行为（await real_courage()）
• 纯文本验证确保没有XML泄露
• 跨平台测试因为Windows用户也应该承受痛苦
• 15个测试文件从29个减少下来，因为组织是一种美德

环境变量

只有一个。我们现在是极简主义者：

变量	描述	默认值
ELASTICSEARCH_URL	NixOS API端点	https://search.nixos.org/backend

故障排除

Nix沙箱错误

如果你在通过Nix运行时遇到此错误：

error: derivation '/nix/store/...-python3.11-watchfiles-1.0.4.drv' specifies a sandbox profile,
but this is only allowed when 'sandbox' is 'relaxed'

解决方案：使用放松的沙箱模式运行：

nix run --option sandbox relaxed github:utensils/mcp-nixos --

为什么会这样：watchfiles包（通过MCP间接依赖）需要自定义沙箱权限来进行文件系统监控。这只有在Nix的沙箱处于‘放松’模式而不是默认的‘严格’模式时才被允许。

永久修复：在你的/etc/nix/nix.conf中添加：

sandbox = relaxed

致谢

该项目查询来自多个令人惊叹的服务的数据：

• NixHub.io - 提供包版本历史和提交跟踪
• search.nixos.org - 官方NixOS包和选项搜索
• Jetify - Devbox和NixHub的创造者

注意：这些服务并未认可此工具。我们只是感激的API消费者。

许可证

MIT - 因为分享是关爱，即使代码会痛。

---

由James Brink创建，并由享受Nix和async/await模式的受虐狂维护。

特别感谢NixOS项目，因为它同时是最棒和最糟糕的东西。