PiHole MCP Server

PiHole MCP 服务器

天啊，为什么？

我们正在构建这个项目，以改善 Pi-hole 设备的管理体验。我们相信，自然语言处理能力可以让用户更轻松地与 Pi-hole 设备交互。我们也在借此项目进一步了解 FastAPI 和检索增强生成（RAG）系统。

MCP 服务器概览

MCP 服务器旨在通过基于 FastAPI 构建的 RESTful API 与 Pi-hole 设备交互，并借助检索增强生成（RAG）系统，基于查询管理 Pi-hole 设备并获取其统计信息。此服务旨在通过自然语言处理能力改善 Pi-hole 的管理体验。

安装

1. 克隆代码库：

   git clone [your repository URL]
   cd mcp_server
   

2. 设置虚拟环境：

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 配置：

   • 将 config.toml.example 复制为 config.toml。
   • 根据你的 Pi-hole 设置、API 密钥和 Milvus 数据库连接详细信息调整配置。
   • 对于 API 密钥等机密信息，请使用 .env 文件：

运行服务器

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

API 用法

• **查询端点：**使用 POST 请求访问 /query，并在标头中包含 X-API-Key。示例：

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

• **功能标志：**查看 config.toml 中的功能标志设置，了解哪些功能可用。

文档

• 服务器运行时，请参阅 /docs 中的 API 文档，了解端点的详细用法。

---

开发者 README

我们将使用大模型扫描 API 端点并自动生成代码。然后，我们会应用来自最近一个已知可用版本的补丁，并逐步修复问题。

我们会将大模型之前生成的代码保存在单独的分支中以供参考，确保基准测试正确。

开发指南

• **结构：**项目使用 FastAPI，并通过 pyproject.toml 或 requirements.txt 管理依赖项。
• **日志记录：**日志配置存储在 logging_config.py 中。请确保日志清晰，且不包含敏感信息。
• **测试：**使用 pytest 编写和运行测试。建议对 Milvus 和 Pi-hole 等外部服务进行模拟。

代码贡献

1. 派生代码库：

   git clone [your fork]
   

2. 设置与开发：

   • 按照上方的安装指南设置开发环境。
   • 提交前：
     • 运行测试：

       pytest
       

     • 使用代码检查工具（flake8、mypy、black、isort）确保代码风格一致。

3. 提交拉取请求：

   • 将更改推送到你的派生代码库，然后针对 main 分支发起拉取请求。

错误处理

• 针对 PiholeConnectionError 或 RagIntentNotFoundError 等常见错误，自定义并实现异常处理程序。

文档

• 功能或依赖项发生变化时，更新 README.md。
• 及时更新 todo.md，记录开发任务。

---

使用 LLM 和补丁制定构建策略

概述：

• 我们使用 LLM（语言模型）生成初始代码库，或为新功能和错误修复提供解决方案，然后通过人工代码审查和应用补丁进一步完善。

流程：

1. 在 containers 目录中启动 pihole

2. cd prompts/; ./run_plan.sh

3. 创建新分支，以便比较 gameplan.md 并找出实质性差异

4. 使用 gameplan.md 为 aider.md 生成各个提示词

5. 使用 aider，根据 gameplan.md 为特定功能或问题生成代码

6. 对比生成的代码与之前的 LLM 版本，处理差异

7. 应用来自 "Working" 的补丁来清理混乱

8. $$$$ 盈利

9. 集成测试：

   • 运行完整的集成测试，确保新代码按预期工作。

10. 更新文档：

    • 记录新功能、修复或变更，并更新用户文档和开发者文档。

策略说明：

• 绝不未经人工审查就直接提交 LLM 生成的代码。
• 记录生成代码的来源，以便追溯。
• 审查和修补 LLM 生成的代码时，优先考虑安全性和效率。