Blue Prince Architect Notes (MCP Server)

Blue Prince MCP - アーキテクトノート

このリポジトリには、ゲーム Blue Prince のプレイをサポートする、専用のネタバレ防止ツール、メモツール、ブレインストーミング用アシスタントとして機能するよう設計された MCP（Model Context Protocol）サーバーのコードが含まれています。

この MCP サーバーは、ローカルのメモ（.md ファイルとして保存）を管理するためのツールとリソースを提供します。ユーザーはメモを書いたり、メモから情報を検索したり、ビデオゲーム Blue Prince をプレイしながらコンパニオンの MCP クライアントとブレインストーミングしたりできます。オンラインのリソースからネタバレを受けずに、プレイヤーが見たり体験したりしたことを結び付け、思い出せるよう支援することを目的としています。

⚠️ 重要：ネタバレに配慮した使い方

この MCP サーバーは、Blue Prince のゲームプレイ体験を損なわないよう設計されています。MCP クライアント（例：Claude Desktop）と併用する場合：

• 優先する情報源：クライアントはメモの情報を優先します
• 外部情報へのアクセスを制限：クライアントは Blue Prince に関する外部知識を使用する場合がありますが、すでに発見した内容に限られます
• ネタバレ防止：外部情報は、メモに記録した内容のみが表示されるようフィルタリングされます
• 同意の確認：ネタバレの可能性がある外部情報を共有する前に、クライアントが許可を求めます
• スマートフィルタリング：自動的なネタバレ防止ルールが MCP リソースとして提供されます
• 発見を尊重：記録した体験や発見に焦点を当てます

機能

• MCP サーバー： MCP プロトコルを実装し、メモ機能をツールとリソースとして提供します。
• ローカルの保管庫に保存： ローカルの構造化されたディレクトリに、Markdown ファイルとしてメモを保存します（Obsidian と互換性があります）。
• 構造化されたメモ： あらかじめ定義されたカテゴリ（people、puzzles、rooms、items、lore、general）にメモを整理し、メタデータをインテリジェントに抽出します。
• リソースシステム： 保管庫内のすべてのファイルを AI クライアントが直接アクセスできる MCP リソースとして提供します（.obsidian/ ディレクトリは除外）。
• ネタバレに配慮した保護システム： 発見を尊重しながら、有用な情報を提供するスマートフィルタリング機能：
  • 動的なネタバレ防止ルールを MCP リソースとして自動的に提供
  • ツールの説明とサーバーメタデータを通じたクライアント側での適用
  • 発見を尊重しながら、コンテンツ作成をすべてサーバー側で検証
  • ユーザーが記録した発見に基づいて外部情報を自動的にフィルタリング
  • ネタバレの可能性がある外部情報の共有は、同意を得てから実施
  • 調査を早まって促すプロンプトを防ぐ、組み込みのコンテンツ検証機能
• インテリジェントなメモ作成と整理：
  • ✅ list_notes - 保管庫内のすべてのメモを一覧表示
  • ✅ create_note - インテリジェントなカテゴリ分類とネタバレ防止機能を備えた、構造化メモを作成
  • ✅ read_note - メタデータを含むメモの全内容を読み取り
  • ✅ update_note - 既存のメモを新しい内容で更新
  • 📋 delete_note - 今後の実装を予定
• インテリジェントなスクリーンショットの管理と分析（開発中）
  • 📋 analyze_screenshot - MCP ホストを利用して img ファイルの内容を分析
  • 📋 view_screenshot - img を表示
  • 📋 download_screenshots - Google Drive と連携してスクリーンショットをダウンロード
• CLI テストツール： 手動テストとデバッグに使える、包括的なコマンドラインインターフェイス。
• セットアップユーティリティ： 保管庫のディレクトリ構造と設定を初期化する Go プログラム。スクリーンショットの同期用に Google Drive の OAuth も設定します。
• 柔軟な設定： ファイルベースの設定と環境変数によるオーバーライドの両方をサポートします。

使い方ガイド

"Write a new note. I'm in the corridor. There is a painting of a tiger and a cupcake stand(?). Three windows. Two benches and hats."

MCP クライアントは、メモをインテリジェントに整形し、適切なタグを付けます。

今後は、次のように尋ねることができます

"Where have I seen windows before? Can you list all rooms that have windows in them?"

MCP クライアントは、あなたが窓のある部屋だと知っている部屋を探すために、すべてのメモ（あなたのメモのみ）をスキャンします。

はじめに

前提条件

• Go（バージョン 1.20 以上を推奨）
• MCP クライアント（互換性のある AI エージェントやテストツールなど）
• Git

セットアップ

1. リポジトリをクローンします：

   git clone https://github.com/myungbeans/blueprince-mcp.git
   cd blueprince-mcp
   

2. セットアップユーティリティを実行します： このプログラムは、必要な Obsidian 保管庫のディレクトリ構造を作成し、保管庫のパスで config.yaml ファイルを更新します。

   デフォルトでは、保管庫を ~/Documents/blueprince_mcp/ に作成します。

   bin/setup
   

   または、保管庫のカスタムパスを指定できます：

   bin/setup /path/to/your/custom/vault
   

   セットアップユーティリティは、保管庫内に必要なサブディレクトリ（notes/people、notes/puzzles、notes/rooms、notes/items、notes/lore、notes/general）と、meta/ および screenshots/ ディレクトリが存在することを確認します。

3. Google Drive 連携を設定します（任意）： これをデプロイしてホスティングするまでは、ローカルで実行するために Google Cloud Platform から独自の API 認証情報を取得する必要があります。 詳細については、以下のセクションを参照してください。

   認証情報を ./.credentials.json に用意したら、drive セットアップコマンドを実行します：

   bin/setup drive "YourFolderName"
   

   これにより、以下が実行されます：

   • Google Drive の OAuth 認証のためにブラウザーを開きます
   • Google Drive に指定したフォルダーを作成するか、既存のフォルダーにアクセスします
   • ファイルの表示、編集、作成、ダウンロードの権限を設定します
   • 今後使用するために認証トークンをローカルに保存します

   要件：

   • フォルダー名を指定する必要があります（ルートディレクトリは指定できません）
   • Google Drive の権限には、表示、一覧表示、編集、ディレクトリの作成、ファイルのダウンロードが含まれます
   • 認証データはすべてお使いのマシンにローカル保存されます。データの取り扱いの詳細については、プライバシーポリシーをご覧ください

4. config.yaml を確認します： セットアップユーティリティは、obsidian_vault_path を設定して config.yaml を更新します。このファイルを確認し、必要に応じて server.host や server.port などの設定を変更できます。

   # config.yaml の例
   server:
     host: "localhost"
     port: 8001
   
   obsidian_vault_path: "/Users/michael.myung/Documents/blueprince_mcp" # セットアップスクリプトによって設定されます
   backup_dir_name: ".obsidian_backup" # 保管庫内に将来バックアップを作成する場合のディレクトリ名
   

Google Cloud OAuth アプリのセットアップ

1. Google Cloud Console にアクセスします： https://console.cloud.google.com/

2. 新しいプロジェクトを作成します： まだプロジェクトがない場合は、新しいプロジェクトを作成します。

3. 必要な API を有効にします： 「API とサービス」ダッシュボードで、このプロジェクトに必要な API（Google Drive API、Gmail API など）を有効にしてください。

4. OAuth 認証情報を作成します：

   • 「API とサービス」>「認証情報」に移動します。
   • 「+ 認証情報を作成」をクリックし、「OAuth クライアント ID」を選択します。
   • アプリケーションの種類として「ウェブ アプリケーション」を選択します。
   • 「承認済みのリダイレクト URI」に http://localhost:8080（またはローカル開発サーバーで使用する URI）を追加します。
   • 「作成」をクリックします。

5. 認証情報をダウンロードします：

   • クライアント ID の作成後、ポップアップにクライアント ID とクライアントシークレットが表示されます。また、新しいクライアント ID の右側にある JSON をダウンロード アイコンをクリックして、認証情報を取得することもできます。

6. ローカルの認証情報ファイルを設定します：

   • ダウンロードしたファイルの名前は client_secret_XXXXXXXX.json になっているはずです。
   • このファイルの名前を .credentials.json に変更します。
   • この .credentials.json ファイルをプロジェクトのルートディレクトリに配置します。

   または、credentials.example.json ファイルを新しいファイル .credentials.json にコピーし、クライアント ID とクライアントシークレットを該当するフィールドに貼り付けることもできます。

ビルドと使い方

サーバーのビルド

go build -o ./bin/blueprince-mcp-server ./cmd/server/main.go

CLI ツールのビルド

go build -o ./bin/blueprince-tools ./cmd/tools/

セットアップユーティリティのビルド

go build -o ./bin/setup ./cmd/setup/main.go

サーバーの実行

ローカル開発

プロジェクトのルートディレクトリにいることを確認してください。

go run ./cmd/server/main.go

サーバーが起動し、stdio トランスポート経由の MCP 接続を待ち受けます。

環境設定

環境変数を使用して Vault のパスを上書きできます。

OBSIDIAN_VAULT_PATH=/path/to/vault go run ./cmd/server/main.go

Claude Desktop との連携

Claude Desktop でカスタム MCP サーバーを追加する手順を参照してください。

要約
必要に応じて編集し、以下を Claude Desktop の設定に追加してください。

{
  "mcpServers": {
    "blueprince-notes": {
      "command": "/path/to/blueprince-mcp/bin/blueprince-mcp-server",
      "env": {
        "GOOGLE_DRIVE_SECRETS_DIR": "/Users/yourprofile/.blueprince_mcp",
        "GOOGLE_DRIVE_SCREENSHOT_FOLDER": "Blue Prince",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "ROOT": "/path/to/repo/blueprince-mcp"
      }
    }
  }
}

/path/to の値を必ず更新してください

CLI ツールを使ったテスト

このプロジェクトには、手動テスト用の包括的な CLI が含まれています。

# List all notes
./bin/blueprince-tools list

# Create a new note
./bin/blueprince-tools create people/character.md \
  --title "Character Name" \
  --content "Character description"

# Read a note
./bin/blueprince-tools read people/character.md

# Update a note
./bin/blueprince-tools update people/character.md \
  --content "Updated character information"

# Use verbose mode for debugging
./bin/blueprince-tools list --verbose

詳しい CLI のドキュメントと使用例については、cmd/tools/README.mdを参照してください。

プロジェクト構成

blueprince-mcp/
├── runtime/
│   ├── mcp/
│   │   ├── tools/              # MCP Tool implementations
│   │   └── resources/          # MCP Resources
│   ├── models/
│   │   ├── notes/              # Note structure and schemas
│   │   ├── vault/              # Obsidian Vault constants and structure
│   │   └── storage/            # Storage interface abstractions
│   ├── storage/                # Storage implementations
│   │   └── drive/              # Google Drive implementation
│   └── utils/                  # Common utilities (logging, file ops, security)
├── cmd/
│   ├── server/main.go          # Main MCP server application
│   ├── setup/                  # Setup utilities
│   ├── tools/                  # CLI for running MCP Server Tools locally
│   └── config/                 # Configuration management
├── docs/                       # Documentation for GitHub Pages
└── bin/                        # Built binaries

現在の状況とロードマップ

✅ 完了

• コア MCP フレームワーク：
  • stdio トランスポートを使用する MCP サーバーフレームワーク
  • すべての Vault ファイルを AI クライアントに公開するリソースシステム
  • メタデータとカテゴリを含む構造化されたノートスキーマ
  • 完全な CRUD 操作：list_notes、create_note、read_note、update_note、delete_note
  • Vault ディレクトリ構成とセットアップユーティリティ
• Google Drive との連携：
  • ブラウザーを自動で開く OAuth2 認証フロー
  • Google Drive API の全権限（表示、一覧表示、編集、作成、ダウンロード）
  • ~/.blueprince_mcp/ への安全なローカルトークン保存
  • フォルダーの自動作成とアクセス検証
  • サードパーティへのデータ送信を行わない、プライバシー重視の設計
  • アーキテクチャのリファクタリング：
    • runtime/storage/drive バックエンドを使用するモジュール式ストレージインターフェース
    • Google Drive ユーティリティとパス管理の一元化
    • 認証情報の読み込みとトークン管理の共有化
    • セットアップ操作と実行時操作の明確な分離
• コード品質とテスト：
  • 主要なすべてのコンポーネントを網羅する包括的なユニットテスト
  • ストレージユーティリティのテスト（パス管理、トークン処理、設定）
  • ファイル操作のテスト（セキュリティ検証、ディレクトリ管理）
  • 認証フローのテスト（OAuth 設定、エラー処理）
  • 外部依存関係のモック実装
  • パフォーマンス検証用のベンチマークテスト
• セキュリティと信頼性：
  • 多層的なネタバレ防止システム
  • パスのセキュリティとパストラバーサルの防止
  • 入力検証とエラー処理
  • 環境変数に対応した設定管理

📋 予定

• スクリーンショット連携の強化：
  • スクリーンショットをインテリジェントに解釈し、画像のタグと説明を含むノートを作成
  • 関連画像へのスマートリンクを含むノートを埋め込む
  • 画像を MCP クライアントに返す
  • ✅ Google Drive 同期の基盤が完成 - Steam Deck -> Google Drive -> ローカル Vault 間のスクリーンショット同期に対応
  • 設定した Google Drive フォルダーからファイルを自動でダウンロードして同期

コントリビューション

コントリビューションを歓迎します！お気軽にイシューを作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳しくは LICENSE ファイルを参照してください。