Nixos

🚀 MCP-NixOS 使用文档

MCP-NixOS 项目借助 Model Context Protocol (MCP)，将大语言模型（LLM）与 NixOS、Home Manager 和 nix-darwin 等操作系统工具相连接。这使得 LLM 能够访问这些系统的资源和工具，进而提供更精准、有用的信息。

🚀 快速开始

MCP-NixOS 是一个通过 Model Context Protocol (MCP) 将大语言模型（LLM）与 NixOS、Home Manager 和 nix-darwin 等操作系统工具连接起来的项目。它允许 LLM 访问这些系统的资源和工具，从而提供更准确和有用的信息。

✨ 主要特性

支持的平台与工具

• NixOS：提供包管理、配置选项和搜索功能。
• Home Manager：提供用户配置文件和模块信息。
• nix-darwin：针对 macOS 的 Nix 补充，提供特定工具和资源。

功能概述

1. 包与配置搜索：通过 ~nixos://search/packages 和 ~home-manager://search/options 访问相关的包和配置信息。
2. 详细信息查询：使用 ~nixos://option/services.nginx 和 ~home-manager://option/programs.firefox.profiles 获取特定包或配置的详细信息。
3. 工具集成：集成如 ~nixos_search、~home_manager_search 和 ~darwin_search 等工具，直接通过 LLM 调用。

📦 安装指南

安装步骤

1. 依赖安装：
   • Python 3.8+：确保系统已安装 Python 3.8 或更高版本。
   • pip：使用以下命令安装必要的 Python 包：

pip install mcp-nixos

2. 配置文件：
   • 创建或编辑 ~/.config/mcp-nixos/config.json 文件，添加以下内容：

{
    "cache": {
        "enabled": true,
        "location": "~/.cache/mcp-nixos",
        "ttl": 3600
    },
    "server": {
        "port": 5000,
        "host": "localhost"
    }
}

- **可选配置**：

"logging": {
    "level": "INFO",
    "file": "~/.log/mcp-nixos.log"
}

3. 启动服务：使用以下命令启动 MCP-NixOS 服务器：

mcp-nixos-server start

💻 使用示例

基础用法

查询 NixOS 包

# 搜索特定包
~nixos://search/packages/firefox

# 获取 Firefox 详细信息
~nixos://option/package.python

配置 Home Manager

# 搜索配置选项
~home-manager://search/options/programs.zsh

# 获取 Git 用户名配置
~home-manager://option/programs.git.userName

使用 nix-darwin

# 搜索 macOS 工具
~darwin://search/options/services.yabai

# 获取 Dock 设置信息
~darwin://option/system.defaults.dock

📚 详细文档

代码结构

MCP-NixOS 采用模块化设计，主要包括以下几个部分：

• 缓存组件 (mcp_nixos/cache/)：节约带宽和内存的高效缓存机制。
• API 客户端 (mcp_nixos/clients/)：连接 Elasticsearch 和解析 HTML 文档的工具。
• 上下文对象 (mcp_nixos/contexts/)：维系整个系统运行的核心结构。
• 资源定义 (mcp_nixos/resources/)：定义所有平台的 MCP 资源。
• 工具实现 (mcp_nixos/tools/)：具体执行操作的实用工具。
• 实用函数 (mcp_nixos/utils/)：系统辅助功能集合。
• 主程序 (mcp_nixos/server.py)：将各模块整合在一起的枢纽。

集成与解析

MCP-NixOS 通过以下方式实现与 NixOS、Home Manager 和 nix-darwin 的集成：

1. NixOS API 接口：连接到 NixOS Elasticsearch 服务，支持多通道（不稳定、稳定/24.11）和错误处理机制。
2. HTML 文档解析器：使用 BeautifulSoup 和正则表达式从 HTML 文档中提取结构化数据。
3. 搜索引擎：基于倒排索引和关键词匹配提供高效的搜索功能。

🔧 技术细节

代码结构

MCP-NixOS 采用模块化设计，各部分分工明确：

• 缓存组件 (mcp_nixos/cache/)：具备高效的缓存机制，可节约带宽和内存。
• API 客户端 (mcp_nixos/clients/)：用于连接 Elasticsearch 和解析 HTML 文档。
• 上下文对象 (mcp_nixos/contexts/)：是维系整个系统运行的核心结构。
• 资源定义 (mcp_nixos/resources/)：定义了所有平台的 MCP 资源。
• 工具实现 (mcp_nixos/tools/)：包含具体执行操作的实用工具。
• 实用函数 (mcp_nixos/utils/)：集合了系统的辅助功能。
• 主程序 (mcp_nixos/server.py)：作为枢纽将各模块整合在一起。

集成与解析

MCP-NixOS 实现与 NixOS、Home Manager 和 nix-darwin 集成的方式如下：

1. NixOS API 接口：连接到 NixOS Elasticsearch 服务，支持多通道（不稳定、稳定/24.11），并具备错误处理机制。
2. HTML 文档解析器：运用 BeautifulSoup 和正则表达式从 HTML 文档中提取结构化数据。
3. 搜索引擎：基于倒排索引和关键词匹配，提供高效的搜索功能。

📄 许可证

MCP-NixOS 采用 MIT License，允许用户自由使用、修改和分发该项目的代码。

💡 使用建议

• 缓存管理：定期清理缓存以确保数据的最新性。
• 日志监控：关注日志文件 (~/.log/mcp-nixos.log) 以便及时发现和解决问题。
• 性能优化：根据系统负载调整服务器配置，如增加内存或优化查询算法。

🤝 开发与贡献

贡献指南

1. 问题报告：在 GitHub Issues 中提交 bug 或功能请求。
2. 代码提交：Fork 项目仓库，创建功能分支，并通过 Pull Request 提交代码。
3. 文档更新：更新或添加相关文档，确保用户和开发者都能轻松理解项目结构和使用方法。

开发环境

• 版本控制：使用 Git 管理项目源代码。
• 持续集成：配置 CI/CD 工具（如 GitHub Actions）以自动化测试和部署流程。