Pihole MCP Server

🚀 Pi Hole MCP Server

This project is built to enhance the Pi-hole management experience. Leveraging natural language processing, it enables easier interaction with Pi-hole devices. It's developed with FastAPI and a Retrieval Augmented Generation (RAG) system.

🚀 Quick Start

We are building this project to enhance the Pi-hole management experience. We believe that natural language processing capabilities can make it easier for users to interact with their Pi-hole devices. We are also building this project by learning about FastAPI and the Retrieval Augmented Generation (RAG) system.

✨ Features

MCP Server Overview

The MCP Server is designed to interact with Pi-hole devices through a RESTful API built with FastAPI. It allows query-based management and retrieval of Pi-hole statistics via a Retrieval Augmented Generation (RAG) system. This service aims to enhance the Pi-hole management experience with natural language processing capabilities.

📦 Installation

1. Clone the repository:

   git clone [Your repository URL]
   cd mcp_server
   

2. Set up the virtual environment:

   python -m venv venv
   source venv/bin/activate  # Use `venv\Scripts\activate` on Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configuration:

   • Copy config.toml.example to config.toml.
   • Adjust the settings according to your Pi-hole setup, API keys, and Milvus database connection details.
   • For secret information (e.g., API keys), use the .env file.

💻 Usage Examples

Run the Server

uvicorn main:app --host 0.0.0.0 --port 8000

API Usage

• Query Endpoint: Use a POST request to /query and include the X-API-Key header. Example:

  POST /query HTTP/1.1
  Host: yourserver.com
  X-API-Key: your_api_key_here
  Content-Type: application/json
  
  {
    "query": "Block the internet for 10 minutes."
  }
  

• Feature Flags: Check the feature flag settings in config.toml, which control the available features.

📚 Documentation

• Access /docs when the server is running for detailed endpoint usage instructions.

📚 Developer README

We will use an LLM to scan API endpoints and automatically generate code. Then, we will apply patches from the last known good version and resolve the conflicts.

We will keep the previously LLM-generated code in a separate branch to ensure correct benchmarking.

💻 Development Guide

• Structure: The project uses FastAPI, and dependencies are managed through pyproject.toml or requirements.txt.
• Logging: Logging configuration is stored in logging_config.py. Ensure that logs are clear and do not contain sensitive information.
• Testing: Use pytest to write and run tests. Mocking external services (e.g., Milvus and Pi-hole) is encouraged.

Code Contribution

1. Fork the repository:

   git clone [Your fork]
   

2. Setup & Development:

   • Set up your development environment according to the installation guide above.
   • Run pip install -r requirements.txt to install dependencies.
   • Familiarize yourself with the project structure and code.

3. Contribute Code:

   • Fork the repository and clone it locally.
   • Create a feature branch for your changes.
   • Commit your changes and push them to GitHub.
   • Create a Pull Request and wait for review.

4. Development Standards:

   • Follow the PEP8 coding style guide.
   • Ensure that code comments are clear and meaningful.
   • Include relevant issue numbers (e.g., #ISSUE-NUMBER) in commit messages.

5. Run Tests:

   • Use pytest to run the test suite.
   • Resolve errors from failed tests and fix the code.

6. Generate Documentation:

   • Ensure that the documentation is clear and understandable for users at different levels.
   • Update the documentation to reflect code changes.

7. Submit Code:

   • Commit all changes.
   • Push to GitHub and create a Pull Request.

🔧 Technical Details

Error Handling

• Error Logging: Record error information for debugging and analyzing issues.
• Custom Errors: Define custom errors whenever possible to improve code maintainability and user experience.
• Exception Handling: Use appropriate exception handling mechanisms to manage runtime errors.

Documentation Update

• Ensure that all changes are reflected in the relevant documentation.
• Update the README and other documentation files to maintain information consistency.
• Keep the documentation concise and clear for users at different levels.

📚 Project Log

Maintain a detailed log of code generation sources to ensure traceability and transparency. Record the source and context of each generated code snippet.

⚠️ Security Considerations

• Follow best security practices to avoid potential security vulnerabilities.
• Conduct regular security audits, especially when handling user input and sensitive data.
• Use a secure dependency management strategy to avoid known vulnerabilities.

🛠️ Maintenance Guide

• Regularly update project documentation and code examples.
• Monitor reports in the issue tracking system and fix them promptly.
• Communicate with contributors to ensure smooth development activities.

📚 Appendix

1. Frequently Asked Questions (FAQ)

Q: How do I start using the MCP Server? A: Clone the repository, install dependencies, and run the server. Refer to the installation guide for detailed steps.

Q: How can I contribute to the project? A: Fork the repository, create a feature branch, submit your changes, and create a Pull Request.

2. Contact Information

• Project Homepage: [GitHub Link]
• Mailing List: [Email Address]
• Submit Issues: [GitHub Issues]

📄 License

[Insert project license information here, such as the MIT License or other applicable open-source licenses.]