Nixos

🚀 MCP-NixOS Documentation

MCP-NixOS is a project that connects large language models (LLMs) with operating system tools such as NixOS, Home Manager, and nix-darwin through the Model Context Protocol (MCP). It enables LLMs to access the resources and tools of these systems, thereby providing more accurate and useful information.

🚀 Quick Start

📦 Installation

1. Install Dependencies:

   • Python 3.8+: Ensure that Python 3.8 or a higher version is installed on your system.
   • pip: Install the necessary Python packages using the following command:

     pip install mcp-nixos
     

2. Configuration File:

   • Create or edit the ~/.config/mcp-nixos/config.json file and add the following content:

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

   • Optional Configuration:

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

3. Start the Service:

   • Start the MCP-NixOS server using the following command:

     mcp-nixos-server start
     

✨ Features

Supported Platforms and Tools

• NixOS: Provides package management, configuration options, and search functions.
• Home Manager: Offers user configuration files and module information.
• nix-darwin: A Nix supplement for macOS, providing specific tools and resources.

Feature Overview

1. Package and Configuration Search:

   • Access relevant package and configuration information through ~nixos://search/packages and ~home-manager://search/options.

2. Detailed Information Query:

   • Use ~nixos://option/services.nginx and ~home-manager://option/programs.firefox.profiles to obtain detailed information about specific packages or configurations.

3. Tool Integration:

   • Integrate tools such as ~nixos_search, ~home_manager_search, and ~darwin_search, which can be directly invoked by the LLM.

💻 Usage Examples

Query NixOS Packages

# Search for a specific package
~nixos://search/packages/firefox

# Get detailed information about Firefox
~nixos://option/package.python

Configure Home Manager

# Search for configuration options
~home-manager://search/options/programs.zsh

# Get the Git username configuration
~home-manager://option/programs.git.userName

Use nix-darwin

# Search for macOS tools
~darwin://search/options/services.yabai

# Get Dock settings information
~darwin://option/system.defaults.dock

🔧 Technical Details

Code Structure

MCP-NixOS adopts a modular design, mainly including the following parts:

• Cache Component (mcp_nixos/cache/): An efficient caching mechanism to save bandwidth and memory.
• API Client (mcp_nixos/clients/): Tools for connecting to Elasticsearch and parsing HTML documents.
• Context Object (mcp_nixos/contexts/): The core structure that maintains the operation of the entire system.
• Resource Definition (mcp_nixos/resources/): Defines MCP resources for all platforms.
• Tool Implementation (mcp_nixos/tools/): Practical tools for performing specific operations.
• Utility Functions (mcp_nixos/utils/): A collection of system auxiliary functions.
• Main Program (mcp_nixos/server.py): The hub that integrates all modules.

Integration and Parsing

MCP-NixOS integrates with NixOS, Home Manager, and nix-darwin in the following ways:

1. NixOS API Interface: Connects to the NixOS Elasticsearch service, supporting multiple channels (unstable, stable/24.11) and an error handling mechanism.
2. HTML Document Parser: Uses BeautifulSoup and regular expressions to extract structured data from HTML documents.
3. Search Engine: Provides an efficient search function based on inverted indexing and keyword matching.

📄 Usage Notes

⚠️ Important Note

• Cache Management: Regularly clean the cache to ensure data freshness.
• Log Monitoring: Pay attention to the log file (~/.log/mcp-nixos.log) to promptly detect and resolve issues.
• Performance Optimization: Adjust the server configuration according to the system load, such as increasing memory or optimizing the query algorithm.

🛠️ Development and Contribution

Contribution Guidelines

1. Issue Reporting:

   • Submit bugs or feature requests in GitHub Issues.

2. Code Submission:

   • Fork the project repository, create a feature branch, and submit your code through a Pull Request.

3. Documentation Update:

   • Update or add relevant documentation to ensure that both users and developers can easily understand the project structure and usage.

Development Environment

• Version Control: Use Git to manage the project source code.
• Continuous Integration: Configure CI/CD tools (such as GitHub Actions) to automate the testing and deployment process.

📄 License

MCP-NixOS is licensed under the MIT License, allowing users to freely use, modify, and distribute the project code.

With the above documentation, you can easily get started with MCP-NixOS and integrate it into your development environment to enhance your interaction with large language models. If you need further information or encounter any problems, please refer to the official project documentation or contact the community support.