Quirox Telegram Bot Backend

Quirox Telegram Bot バックエンド

このプロジェクトは、Quirox Telegram Bot のバックエンドサービスを提供します。Google Sheets、Gmail（現在はコメントアウトされています）、DuckDuckGo によるウェブ検索など、さまざまなツールと連携できる AI エージェントを備えています。Model Context Protocol（MCP）を使用して、AI モデル（Google Gemini）と利用可能なツール間の通信を管理します。バックエンドは FastAPI ウェブサーバーを介して公開されます。

デモ

機能

• AI エージェント： 推論とタスクの実行に Google Gemini（Flash モデル）を使用します。
• ツール連携：
  • Google Sheets： スプレッドシートの作成、データの読み書き、シートの管理（一覧表示、コピー、名前変更）、共有を行います。helpers/ghseet.py（GoogleSheetsService 経由）を使用します。
  • ウェブ検索： DuckDuckGo を使用してウェブを検索します（helpers/search_tools.py）。
  • ウェブコンテンツの取得： URL からテキストコンテンツを取得して解析します（helpers/search_tools.py）。
  • （実験的／無効）Gmail： メールの送信、閲覧、管理用の関数が helpers/gmail_tools.py にありますが、mcp_server.py ではコメントアウトされているようです。
• MCP フレームワーク：
  • mcp_server.py：MCP サーバーを実行し、ツール（Sheets、Search、Fetch）を AI モデルに公開します。
  • mcp_client.py：MCP サーバーと通信し、ユーザーのクエリを Gemini モデルに送信し、ツール呼び出しを処理して、会話の流れを管理します。
• FastAPI インターフェース：
  • main.py：FastAPI ウェブサーバーを起動し、HTTP リクエストを介して AI エージェントとやり取りするための /chat エンドポイントを提供します。

プロジェクト構成

├── README.md # このファイル ├── .env # 環境変数（API キー、パス）— 作成が必須です ├── .gitignore # Git の無視パターン ├── requirements.txt # Python の依存関係 ├── main.py # FastAPI アプリケーションのエントリーポイント ├── mcp_client.py # Gemini および MCP サーバーと連携する MCP クライアントのロジック ├── mcp_server.py # ツールを公開する MCP サーバー ├── helpers/ # ヘルパーモジュールとツールのディレクトリ │ ├── config.py # Gemini API キーを読み込みます │ ├── gsheet_tools.py # （古い可能性がある）Google Sheets 用 MCP ツール定義 │ ├── ghseet.py # 単独で使用できる GoogleSheetsService クラス │ ├── gmail_tools.py # Gmail サービスクラスと MCP ツール定義（現在未使用） │ ├── search_tools.py # DuckDuckGo 検索およびウェブコンテンツ取得のクラス │ └── init.py ├── telegram_bot/ # （空／プレースホルダー？）Telegram Bot 固有のコード用ディレクトリ └── bot/ # （空／プレースホルダー？）別の Bot ディレクトリ候補

## Setup

### 1. Prerequisites

*   Python 3.8+
*   Access to Google Cloud Platform for Sheets/Drive API and potentially Gmail API.
*   Google Gemini API Key.

### 2. Clone the Repository

```bash
git clone <your-repository-url>
cd <repository-directory>

3. 依存関係のインストール

pip install -r requirements.txt

4. 環境変数

ルートディレクトリに .env ファイルを作成します。.env.example がある場合はコピーし、ない場合は新規作成してください。次の変数を追加します。

# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key

# Google Cloud Credentials (Choose ONE method: Service Account or OAuth)

# Method 1: Service Account (Recommended for servers)
# Path to your service account JSON key file
SERVICE_ACCOUNT_PATH=path/to/your/service_account.json
# Optional: Google Drive Folder ID to work within
DRIVE_FOLDER_ID=your_google_drive_folder_id

# Method 2: OAuth 2.0 (Requires user interaction for the first run)
# Path to your OAuth client secrets file (credentials.json)
CREDENTIALS_PATH=path/to/your/credentials.json
# Path where the OAuth token will be stored after authorization
TOKEN_PATH=token.json # Keep default unless you have a reason to change

# Method 3: Base64 Encoded Service Account Config (Alternative)
# CREDENTIALS_CONFIG=your_base64_encoded_service_account_json_string

重要：

• Google Cloud プロジェクトで Google Sheets API と Google Drive API が有効になっていることを確認してください。
• OAuth（CREDENTIALS_PATH）を使用する場合、初回に mcp_server.py（または GoogleSheetsService／GmailService を使用するコード）を実行すると、アプリケーションの認証を行うためのブラウザーウィンドウが開きます。生成された token.json が保存されます。
• サービスアカウント（SERVICE_ACCOUNT_PATH）を使用する場合は、サービスアカウントのメールアドレスに、対象の Google Sheets または Drive フォルダーで適切な権限（例：編集者）が付与されていることを確認してください。

5. Google Cloud 認証の設定

• サービスアカウント：
  1. Google Cloud Console -> IAM & Admin -> Service Accounts に移動します。
  2. サービスアカウントを作成するか、既存のものを使用します。
  3. サービスアカウントのキー（JSON 形式）を作成し、ダウンロードします。
  4. .env の SERVICE_ACCOUNT_PATH に、ダウンロードした JSON ファイルのパスを設定します。
  5. 必要に応じて、特定の Google Drive フォルダーやスプレッドシートをサービスアカウントのメールアドレスと共有します。
• OAuth 2.0：
  1. Google Cloud Console -> APIs & Services -> Credentials に移動します。
  2. タイプが「Desktop app」の「OAuth 2.0 Client ID」を作成します。
  3. クライアントシークレットの JSON ファイルをダウンロードします。
  4. ファイル名を credentials.json に変更します（または .env の CREDENTIALS_PATH を更新します）。

使い方

このアプリケーションは、並行して実行する必要がある 2 つの主要部分（MCP サーバーと、MCP クライアントを使用する FastAPI フロントエンド）で構成されています。

1. MCP サーバーを実行する

このサーバーは、AI にツール（Sheets、Search）を提供します。

python mcp_server.py

このターミナルウィンドウは開いたままにしてください。

2. FastAPI アプリケーションを実行する

チャットリクエストを待ち受けるウェブサーバーを起動します。

python main.py
# or using uvicorn directly for more options:
# uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. API を介して操作する

これで、/chat エンドポイントに POST リクエストを送信できます。

curl を使用した例：

curl -X POST "http://localhost:8000/chat" \
     -H "Content-Type: application/json" \
     -d '{"message": "Create an excel sheet named '\''Test Sheet'\'' and add the headers Name, Age, City in the first row."}'

レスポンスには、MCP サーバー経由でツールとやり取りする場合も含めて、AI が生成した最終回答が含まれます。

主要モジュール（helpers/）

• config.py：環境変数から GEMINI_API_KEY を読み込みます。
• search_tools.py：ウェブ検索を行う DuckDuckGoSearcher と、URL からコンテンツを取得する WebContentFetcher が含まれています。レート制限にも対応しています。
• ghseet.py：Google Sheets および Drive API にクラスベースのインターフェース（作成、読み取り、更新、一括更新、行／列の追加、シート一覧表示、共有など）を提供する GoogleSheetsService を実装しています。認証は内部で処理されます。
• gmail_tools.py：GoogleSheetsService と同様の構成で、Gmail の操作を行う GmailService を実装しています。メールタスク用の MCP ツール定義が含まれていますが、現在は mcp_server.py で無効になっているようです。
• gsheet_tools.py：Google Sheets 用の古い関数ベースの MCP ツール定義が含まれています。おそらく ghseet.py に置き換えられています。

依存関係

主な依存関係は次のとおりです。

• fastapi、uvicorn：ウェブサーバー用。
• mcp：Model Context Protocol ライブラリ。
• google-api-python-client、google-auth-oauthlib、google-auth：Google API ライブラリ。
• google-generativeai：Google Gemini クライアントライブラリ。
• python-dotenv：環境変数の読み込み用。
• httpx、beautifulsoup4：ウェブ検索とコンテンツ取得用。
• rich：書式付きコンソール出力用。

すべての一覧は requirements.txt を参照してください。