PiHole MCP 服务器

天啊，为什么要做这个？

我们构建这个项目是为了增强 Pi-hole 设备的管理体验。我们相信自然语言处理能力可以使使用者更容易地与他们的 Pi-hole 设备进行交互。我们构建这个项目也是为了更多地了解 FastAPI 和检索增强生成 (RAG) 系统。

MCP 服务器概览

MCP 服务器旨在通过使用 FastAPI 构建的 RESTful API 与 Pi-hole 设备进行交互，从而允许通过检索增强生成 (RAG) 系统进行基于查询的管理和 Pi-hole 统计信息的检索。此服务旨在通过自然语言处理能力增强 Pi-hole 管理体验。

安装

1. 克隆仓库:

   git clone [你的仓库 URL]
   cd mcp_server
   

2. 设置虚拟环境:

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上，使用 `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 使用

• 查询端点: 使用带有 X-API-Key 标头的 POST 请求到 /query。 示例:

  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 文档，以获取详细的端点用法。

---

开发者须知

我们将使用 LLM 扫描 API 端点并自动生成代码。 然后，我们将应用来自上次已知工作版本的补丁，并解决中断问题。

我们将把以前的 LLM 生成的代码保存在一个单独的分支中，以供参考，以确保基准测试的正确性。

开发指南

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

代码贡献

1. Fork 仓库:

   git clone [你的 fork]
   

2. 设置 & 开发:

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

       pytest
       

     • 使用 linters（flake8、mypy、black、isort）确保代码风格。

3. 提交 Pull Requests:

   • 将更改推送到您的 fork，然后针对主分支打开一个 pull request。

错误处理

• 自定义并实现异常处理程序，以处理常见的错误，例如 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 生成的代码时，优先考虑安全性和效率。