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包（13万+个实际存在的包）
• 配置选项（2.2万+种搞坏系统的方式）
• Home Manager设置（4千+个选项，适合高级用户）
• nix-darwin配置（1千+个苹果不想让你碰的macOS设置）
• 包版本历史，通过NixHub.io（通过提交哈希找到那个古老的Ruby 2.6）

你真正关心的工具

🔍 NixOS工具

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

📦 版本历史工具（新功能！）

• 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：异步革命（在伟大简化之后）

• 代码大幅减少 - v1.0.0移除了数千行代码，v1.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调用 因为mock是给懦夫用的（await real_courage()）
• 纯文本验证 确保没有XML泄露
• 跨平台测试 因为Windows用户也值得痛苦
• 15个测试文件 从29个减少，因为组织是一种美德

环境变量

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

故障排除

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的沙盒模式为'relaxed'而不是默认的'strict'模式时才被允许。

永久修复: 添加到你的/etc/nix/nix.conf：

sandbox = relaxed

致谢

这个项目查询了来自几个出色服务的数据：

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

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

许可证

MIT - 因为分享是关心，即使代码让人痛苦。

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

特别感谢NixOS项目，他们创造了一个既是最好的也是最糟糕的操作系统。