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）以自動化測試和部署流程。