内容
# nix-mcp
一款适用于Nix生态系统的快速、低占用资源的MCP服务器，使用Go编写。它是[mcp-nixos](https://github.com/utensils/mcp-nixos)的直接替代实现，提供相同的双工具界面和输出，但作为单个静态二进制文件（~数十MB RSS，而非~150MB Python运行时）。
- **stdio和HTTP**传输方式 — 独立使用或在代理后面使用。
- **MCP根目录**（包括`X-Mcp-Root` HTTP头），因此一个HTTP实例可以为多个客户端/工作树提供服务；`flake-inputs`从调用客户端的根目录解析flake目录。
- **实时数据**：查询search.nixos.org（Elasticsearch）、NixHub、FlakeHub、cache.nixos.org、NixOS维基、nix.dev、Noogle以及Home Manager / nix-darwin / Nixvim选项文档 — 比`nix search`更快、更及时。
- **无运行时依赖**，除了`nix`本身，并且仅适用于`flake-inputs`（它会调用`nix flake archive`）；其他所有内容都是纯Go编写的。
## 安装
Nix（二进制缓存位于`nix.stubbe.dev`）：
```sh
nix run github:stubbedev/nix-mcp
```
Go:
```sh
go install github.com/stubbedev/nix-mcp@latest
```
## 使用
stdio（默认）：
```sh
nix-mcp
```
HTTP（多客户端；一个共享服务器）：
```sh
nix-mcp --http # 127.0.0.1:8765/mcp
# 或： nix-mcp --http=0.0.0.0:9000 --http-path=/mcp
```
在代理后面，固定每个请求的workspace根目录，以便`flake-inputs`指向正确的项目：
```
X-Mcp-Root: /path/to/flake-project
```
MCP客户端配置示例（stdio）：
```json
{
"mcpServers": {
"nix": {
"command": "nix-mcp"
}
}
}
```
## 配置
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `NIX_MCP_HTTP` | — | 启用HTTP，默认为`127.0.0.1:8765`。 |
| `NIX_MCP_HTTP_ADDR` | — | 在此地址上启用HTTP（或使用`--http`）。 |
| `NIX_MCP_HTTP_PATH` | `/mcp` | HTTP端点路径（`--http-path`）。 |
| `NIX_MCP_TOKEN` | — | 如果设置，HTTP客户端必须将其作为`Authorization: Bearer <token>`（或`X-Mcp-Token`）发送。stdio忽略此设置。 |
为了与Python `mcp-nixos`服务兼容，`MCP_NIXOS_TRANSPORT=http` / `MCP_NIXOS_HOST` / `MCP_NIXOS_PORT` / `MCP_NIXOS_PATH`环境变量也受到支持。
## 工具
暴露了两个工具（无限制 — 始终可用）：
- **`nix`** — 统一的`action`调度器：
- `action=search` — 关键字搜索。`source`可以是`nixos`（默认）、`home-manager`、`darwin`、`flakes`、`flakehub`、`nixvim`、`wiki`、`nix-dev`、`noogle`、`nixhub`之一。对于`source=nixos`，`type`可以是`packages`/`options`/`programs`/`flakes`。
- `action=info` — 详细查询，针对精确的名称（软件包/选项，HM/darwin/nixvim选项，flakehub `org/project`，维基页面，nix.dev页面，noogle函数，nixhub软件包）。
- `action=stats` — 按来源统计。
- `action=browse` — 按前缀浏览选项树（`home-manager`、`darwin`、`nixvim`、`noogle`）。
- `action=channels` — 列出具有索引/分支修订的NixOS通道。
- `action=flake-inputs` — 对flake的输入进行`type=list|ls|read`操作（使用客户端根目录/ `source`路径；需要`nix`在PATH中）。
- `action=cache` — 软件包在多个系统上的二进制缓存状态。
- `action=store` — 绝对`/nix/store/`路径的`type=ls|read`操作。
- **`nix_versions`** — 来自NixHub的软件包版本历史记录（哪个nixpkgs提交提供了版本X，属性路径，平台，日期）。
### 来源状态
相比上游的`mcp-nixos`（其对这些来源的爬虫已损坏）：
- **flakes** — 搜索索引生成（`latest-N-group-manual`）现在在运行时发现，而不是硬编码，因此flake搜索/统计数据再次可用（上游的索引数据目前很稀疏，但查询是正确的）。
- **home-manager** / **nixvim** — 这些上游替换了他们的可抓取文档，格式为无法查询的端点（分页mdBook HTML / 二进制WASM解码索引）。这些来源返回一个明确的“不可用”消息，而不是静默的空结果。**nixos**和**darwin**选项搜索未受影响且可用。
## 开发
```sh
just build # 编译
just test # 运行测试
just lint # 格式化 + 检查 + golangci-lint
just check # CI运行的所有检查
```
使用`just release-patch|minor|major`（标签`vX.Y.Z`）进行发布，这会触发多架构二进制构建、nix缓存推送和GitHub发布。
## 许可证
MIT
