Google Docs MCP Server

# Google Docs MCP Server Google Docs APIと連携するMCP（Model Context Protocol）サーバーです。AI システムがGoogle Docsを直接操作できるインターフェースを提供します。 ## 機能 このMCPサーバーが提供するツール： - **read_google_document** - Google Docsドキュメントの読み取り - **create_google_document** - 新しいGoogle Docsドキュメントの作成 - **update_google_document** - 既存のGoogle Docsドキュメントの更新 - **search_google_documents** - Google Docsドキュメントの検索 ## アーキテクチャの特徴 - **依存性注入コンテナ** - ServiceContainerによるサービス管理 - **階層化エラーハンドリング** - 統一されたエラー処理システム - **自動ツール登録** - 設定ベースのツール管理 - **完全なTypeScript** - 型安全性と開発効率の向上 ## 技術スタック - **Runtime**: [Node.js](https://nodejs.org/) (v14以上) - **Language**: [TypeScript](https://www.typescriptlang.org/) (ES2020/ESM) - **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) v1.10.2 - **Google APIs**: [googleapis](https://github.com/googleapis/google-api-nodejs-client) v148.0.0 - **Configuration**: [dotenv](https://github.com/motdotla/dotenv) + [zod](https://github.com/colinhacks/zod) validation ## セットアップ ### 1. プロジェクトの準備 ```bash git clone <repository-url> cd docs-mcp npm install ``` ### 2. Google Cloud Platform の設定 1. [Google Cloud Console](https://console.cloud.google.com/) でプロジェクトを作成 2. 以下のAPIを有効化： - Google Docs API - Google Drive API 3. OAuth 2.0 クライアントIDを作成し、認証情報をダウンロード 4. `credentials.json` としてプロジェクトルートに配置 ### 3. 環境設定（オプション） `.env` ファイルで設定をカスタマイズできます： ```env # アプリケーション環境 (development, production, test) NODE_ENV=development # ログ設定 (ERROR, WARN, INFO, DEBUG, TRACE) LOG_LEVEL=INFO LOG_USE_STDERR=true # サーバー情報 SERVER_NAME=google-docs-mcp-server SERVER_VERSION=1.0.0 # 認証ファイルパス（カスタマイズ可能） CREDENTIALS_PATH=./credentials.json TOKEN_PATH=./token.json ``` ### 4. 初回認証 ```bash npm run dev ``` ターミナルに表示される認証URLにアクセスし、Googleアカウントで認証してください。認証後に取得したコードをターミナルに入力すると `token.json` が生成されます。 ## 開発コマンド ```bash # 開発サーバー（hot reload） npm run dev # プロダクションビルド npm run build # ビルド後の実行 npm start # MCP デバッグモード npm run mcp # コード品質チェック npm run lint ``` **ビルドプロセス**: TypeScript コンパイル → 実行権限設定 → 認証ファイル複製 ## MCP クライアント設定 ### Cursor での設定 `.cursor/mcp.json` に追加： ```json { "mcpServers": { "google-docs": { "command": "node", "args": ["/absolute/path/to/docs-mcp/dist/index.js"] } } } ``` ### Claude Desktop での設定 `claude_desktop_config.json` に追加： ```json { "mcpServers": { "google-docs": { "command": "node", "args": ["/absolute/path/to/docs-mcp/dist/index.js"] } } } ``` **注意**: ビルド後の `dist/index.js` を指定してください。 ## 提供ツール ### read_google_document Google Docs ドキュメントの内容を読み取ります。 **パラメータ**: - `documentId` (string): 読み取るドキュメントのID ### create_google_document 新しい Google Docs ドキュメントを作成します。 **パラメータ**: - `title` (string): ドキュメントタイトル - `content` (string, オプション): 初期内容 ### update_google_document 既存の Google Docs ドキュメントを更新します。 **パラメータ**: - `documentId` (string): 更新するドキュメントのID - `content` (string): 追加または更新するコンテンツ - `startPosition` (number, オプション): 更新開始位置 - `endPosition` (number, オプション): 更新終了位置 ### search_google_documents Google Docs ドキュメントを検索します。 **パラメータ**: - `query` (string): 検索クエリ - `maxResults` (number, オプション): 最大結果数（デフォルト: 10） ## プログラムでの利用例 MCP SDK を使用した TypeScript/JavaScript での利用： ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; async function main() { const client = new Client({ name: "google-docs-client", version: "1.0.0" }); const transport = new StdioClientTransport({ command: "node", args: ["/absolute/path/to/docs-mcp/dist/index.js"] }); await client.connect(transport); // ドキュメント検索 const searchResult = await client.callTool({ name: "search_google_documents", arguments: { query: "会議資料", maxResults: 5 } }); // 新規ドキュメント作成 const createResult = await client.callTool({ name: "create_google_document", arguments: { title: "新しいドキュメント", content: "初期コンテンツ" } }); await client.disconnect(); } main().catch(console.error); ``` ## アーキテクチャ詳細 ### コアコンポーネント - **ServiceContainer** (`src/core/container.ts`) - 依存性注入とサービスライフサイクル管理 - **GoogleDocsMcpServer** (`src/mcp/server.ts`) - MCP サーバーの管理と初期化 - **ToolRegistry** (`src/mcp/registry.ts`) - ツールの自動登録システム - **BaseMcpTool** (`src/mcp/tools/base.ts`) - 全ツールの共通基底クラス ### サービス層 - **AuthService** (`src/services/authService.ts`) - Google OAuth2 認証管理 - **GoogleDocsService** (`src/services/googleDocsService.ts`) - Google Docs/Drive API操作 ### 設定システム - **統一設定管理** (`src/config/index.ts`) - 環境変数とデフォルト値の統合 - **型安全な設定** - Zod による設定値の検証 - **階層化ログシステム** (`src/utils/logger.ts`) - モジュール別ログ出力 ## トラブルシューティング ### MCP クライアント接続エラー 1. **ビルドの確認**: `npm run build` が成功しているか 2. **パス設定**: 設定ファイルで `dist/index.js` への絶対パスを指定 3. **権限設定**: `chmod 755 dist/index.js` で実行権限を確認 4. **手動テスト**: `npm run mcp` でサーバーが起動するか確認 ### Google 認証エラー 1. **認証ファイル**: `credentials.json` がプロジェクトルートに存在するか 2. **API有効化**: Google Cloud Console で必要なAPIが有効か 3. **トークン再作成**: `token.json` を削除して再認証 4. **スコープ確認**: Docs API と Drive API の権限が設定されているか ### 開発時のデバッグ ```bash # 詳細ログでデバッグ実行 LOG_LEVEL=DEBUG npm run dev # MCP通信のデバッグ npm run mcp ``` ## 拡張ガイド ### 新しいツールの追加 1. `src/mcp/tools/` に新しいツールクラスを作成 2. `BaseMcpTool` を継承して実装 3. `ToolRegistry.registerDefaultTools()` に追加 ### サービスの拡張 1. `src/core/interfaces.ts` でインターフェースを定義 2. `src/services/` に実装クラスを作成 3. `ServiceContainer` に追加 ## 注意事項 - 初回実行時の Google 認証が必要 - Google Cloud Platform の API 使用料金が発生する可能性 - MCP クライアントでは絶対パスでの指定が必要 ## ライセンス MIT License