PiHole MCP Server

PiHole MCP Server

いったい、なぜ？

Pi-hole デバイスの管理をより快適にするために、このプロジェクトを開発しています。自然言語処理機能によって、ユーザーが Pi-hole デバイスをより簡単に操作できるようになると考えています。また、FastAPI と Retrieval-Augmented Generation（RAG）システムについて学ぶことも、このプロジェクトの目的です。

MCP サーバーの概要

MCP サーバーは、FastAPI で構築した RESTful API を使用して Pi-hole デバイスとやり取りし、Retrieval-Augmented Generation（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 の使用方法

• クエリエンドポイント： X-API-Key を含むヘッダーを指定して、/query に POST リクエストを送信します。例：

  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

LLM を使用して API エンドポイントをスキャンし、コードを自動生成する予定です。その後、最後に動作していたバージョンのパッチを適用し、不具合を一つずつ解消していきます。

ベンチマークの正確性を確保するため、以前に LLM が生成したコードは、参照用として別のブランチに保持します。

開発ガイドライン

• 構成： このプロジェクトでは 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. gameplan.md に基づいて、aider を使用し、特定の機能や問題のコードを生成します

6. 生成されたコードと以前の LLM バージョンとの差分を確認します

7. 「Working」からパッチを適用して、問題を整理します

8. $$$$ 利益

9. 統合テスト：

   • 完全な統合テストを実行し、新しいコードが期待どおりに動作することを確認します。

10. ドキュメントの更新：

    • ユーザー向けと開発者向けの両方のドキュメントを更新し、新機能、修正、変更内容を記録します。

ポリシーに関する注意事項：

• 人間によるレビューを行わずに、LLM が生成したコードを直接コミットすることは避けてください。
• トレーサビリティを確保するため、生成されたコードの出所を記録してください。
• LLM が生成したコードをレビューしてパッチを適用する際は、セキュリティと効率を優先してください。