MCP-NixOS 使用文档

项目概述

MCP-NixOS 是一个通过 Model Context Protocol (MCP) 将大语言模型（LLM）与 NixOS、Home Manager 和 nix-darwin 等操作系统工具连接起来的项目。它允许 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: 提供包管理、配置选项和搜索功能。
• 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 调用。

使用示例

查询 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. 搜索引擎: 基于倒排索引和关键词匹配提供高效的搜索功能。

使用注意事项

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

开发与贡献

贡献指南

1. 问题报告:

   • 在 GitHub Issues 中提交 bug 或功能请求。

2. 代码提交:

   • Fork 项目仓库，创建功能分支，并通过 Pull Request 提交代码。

3. 文档更新:

   • 更新或添加相关文档，确保用户和开发者都能轻松理解项目结构和使用方法。

开发环境

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

项目许可

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

通过以上文档，您可以轻松上手 MCP-NixOS，并将其集成到您的开发环境中，提升与大语言模型交互的能力。如需进一步了解或遇到问题，请参考项目官方文档或联系社区支持。