MCP Stark Brain (Payments)

日々の業務で Payments チームを支援するローカル MCP サーバー:

• Python マイクロサービスで使用されているアーキテクチャパターンを照会する。

• マイクロサービスの仕様（各サービスの目的と責務）を調べる。

• 支払い処理フローを理解する。

• ドキュメント検索と GCP 分析（Datastore + Cloud Logging / Log Explorer）を組み合わせて、カスタマーサクセス（CS）チケットのトリアージと調査を行う。

• ECDSA Project の認証情報を使用して、development（デフォルト）または sandbox（明示的に要求された場合のみ）で Stark Bank API を呼び出す。

starkbank/alexandria 内のドキュメントに対して RAG を実行し、あなたの秘密鍵で Stark Bank API リクエストに署名し、あなた自身の gcloud アイデンティティ（ADC）で GCP クエリを実行します。

1. 仕組み

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• ドキュメントはリモート優先（git clone は保持しない）。 サーバーは GitHub API を介してリポジトリの tarball をダウンロードし（コンテンツ全体で 1 リクエスト）、ローカルの埋め込みインデックスを構築します。ベクトルインデックスのみがローカルにキャッシュされます。

• レート制限に対応。 GitHub の予算が少なくなると、サーバーはリポジトリのクローンを作成して local モードに切り替えることを提案します（セクション 10 を参照）。

• Stark Bank API はデフォルトで development (https://development.api.starkbank.com) を使用します。sandbox は、ユーザーが明示的に要求した後に environment="sandbox" を指定してツールが呼び出された場合にのみ使用されます。本番環境は決して許可されません。

• GCP プロジェクトは呼び出しごとに指定します。 固定のプロジェクト環境変数はありません。各クエリは明示的な project を受け取るため、グローバルな gcloud config に触れることなく、同じセッション内でマイクロサービスのプロジェクトを切り替えられます。

• GCP にサービスアカウントキーは不要。 GCP アクセスは個人の ADC 認証情報を使用するため、ユーザーごとの権限と監査証跡が保持されます。

2. 前提条件

• Python 3.12（バンドルのビルド/インストールに必要）。 chromadb と fastembed（onnxruntime 経由）は、新しいインタープリター向けのビルド済み wheel をまだ確実には提供していないため、プロジェクトでは requires-python = ">=3.11,<3.13" に固定し、以下のすべてのコマンドは明示的に 3.12 を対象としています。最初にバージョンを確認せずに、システムのデフォルトの python3 を代用しないでください。

• バンドルのインストールには uv（推奨）または pipx を使用します。

• Google Cloud SDK (gcloud)。

ピン留めされた Python バージョンを uv で確認/インストールします（システムの Python には影響しません）:

uv python install 3.12

3. GitHub PAT を生成する

各開発者は 自分の PAT を生成します（共有もコミットもされません）。alexandria は starkbank 組織が所有するプライベートリポジトリであるため、どのトークンタイプが機能するかは組織のトークンポリシーによって異なります。選択する前に以下の両方のオプションを読んでください。

オプション A: fine-grained PAT（最初にこちらを試す）

1. GitHub -> Settings -> Developer settings -> Fine-grained tokens -> Generate new token の順に進みます。

2. Resource owner: starkbank。

3. Repository access: Only select repositories -> starkbank/alexandria。

4. Permissions: Repository permissions -> Contents: Read-only。

5. トークンを生成してコピーします（mcp.json で環境変数として設定します）。

6. https://github.com/settings/personal-access-tokens でステータスを確認します。 組織が承認を必要とする場合、Pending と表示され、承認されるまでリクエストはすべて 404 になります。組織の Settings -> Personal access tokens -> Pending requests で starkbank 組織のオーナーに承認を依頼するか、オプション B に進んでください。

オプション B: classic PAT（組織が fine-grained トークンを承認しない場合のフォールバック）

Classic PAT は上記の組織承認ステップの対象では ありません。そのため、組織が fine-grained トークンを制限している場合、これがより迅速な方法です:

1. GitHub -> Settings -> Developer settings -> Tokens (classic) -> Generate new token の順に進みます。

2. Scope: repo（classic トークンには、プライベートリポジトリ向けの contents のみのスコープはありません）。

3. starkbank 組織が SSO を強制している場合は、新しく作成したトークンの横にある Configure SSO をクリックして、starkbank に対して Authorize します。承認されていないトークンは、未承認の fine-grained トークンとまったく同様に starkbank リソースで 404 になります。

いずれの場合も、インストール後は、実際にトークンが機能することを確認するために diagnose_github_access ツールを実行してください（セクション 8 を参照）。

4. GCP で認証する（ADC）

gcloud auth login
gcloud auth application-default login

ここでプロジェクトを設定する必要は ありません。MCP は GCP ツールの呼び出しごとに project を受け取ります。プロジェクトの提案を得るには analyze_ticket / resolve_project を使用します。

5. Stark Bank API の認証情報（ECDSA）

API 呼び出しは、静的 API キーではなく ECDSA（secp256k1）で認証されます。公式ドキュメント: Authentication を参照してください。

1. キーペアを生成し（まだの場合）、開発環境用に Web Banking（Integrations → Project）で 公開鍵のみを登録 します。

2. 秘密鍵 PEM は自分のマシンに保管します。コミットは絶対にせず、公開鍵をこのリポジトリ内に置かないでください（MCP はリクエストに署名するために公開鍵を必要としません）。

3. Project を作成/登録した後に Web Banking に表示される Project ID をメモします。

4. 環境変数で MCP に PEM と Project ID を指定します（ステップ 6 / セクション 11 を参照）。

秘密鍵の推奨場所（リポジトリの外部）:

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

デフォルトのベース URL:

6. バンドル（wheel）をビルドする

リポジトリのルートから、インタープリターを常に明示的に Python 3.12 に固定します。裸の uv build を実行して、PATH でたまたま最初に見つかった Python に頼らないでください:

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

これにより、dist/ にインストール可能なアーティファクトが生成されます（ファイル名の正確なバージョンは pyproject.toml の version に由来し、現在は 0.2.0）:

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

.whl を開発者（または共有場所）に配布します。

uv を使用しない場合: python3.12 -m venv .venv312 で venv を作成し、アクティベートして、pip install build && python -m build -o dist を実行します。最初に python3.12 --version で確認してください。そのコマンドが見つからない場合は、続行する前に Python 3.12 をインストールしてください。異なるメジャー/マイナーバージョンでビルドしないでください。

7. IDE に MCP をインストールする

wheel を分離されたツールとしてインストールします。ここでも Python 3.12 を明示的に固定して、ツールの環境がビルド/テストされた環境と一致するようにします。バージョン番号を手動で編集する必要がないように glob を使用します（以前のビルドから残った古い wheel をインストールするリスクを回避します）:

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

これにより、mcp-stark-brain コマンドが PATH で利用可能になります。

次に、IDE の MCP 設定（例: Cursor の ~/.cursor/mcp.json またはプロジェクトの .cursor/mcp.json）にサーバーを追加します:

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

新しい MCP サーバーを認識させるために、IDE を再起動/リロードします。

Tools & MCP リストの stark-brain の横にカスタムアイコンを表示したい場合（公式の github MCP がロゴを表示するように）は、cursor-plugin/README.md を参照してください。この同じ設定を logo 付きのローカル Cursor プラグインとしてパッケージ化するオプションのラッパーがあります。純粋に見た目だけの問題なので、気にしない場合はスキップしてください。

8. インストール済みの MCP を更新する

このリポジトリが変更されるたびに（新しいツール、バグ修正、設定デフォルトの修正など）、新しいバンドルが必要です。コマンドは元のインストール方法によって異なります。間違ったコマンドを使用すると、「修正が反映されないのはなぜ？」という混乱の最も一般的な原因になるため、ステップ 6 に一致するものを選択してください:

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

次に、Cursor がサーバープロセスを実際に再生成するようにします。表示されるツールリストは、その特定の stdio サブプロセスが起動時に通知したものなので、ディスク上の再インストールだけでは更新されません:

1. まず、再インストールが実際に反映されたことを確認します（Cursor の外の通常のターミナルで）:

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. Cursor でサーバーをオフ/オンに切り替えます — これは、アプリ全体を終了せずに単一の MCP サーバーを再生成する公式にサポートされている方法です: Cmd+Shift+J -> Tools & MCP -> stark-brain を見つけます -> オフ に切り替えます。数秒待ってから、オン に切り替えます。

3. 新しいチャットを開きます。 切り替え前に開いていたチャットは、サーバーが再起動した後も古いツールリストを表示し続ける可能性があります。

4. それでもツールが古いままの場合は、Cursor の Shared Process — すべての MCP サブプロセスをホストするアプリインスタンスごとの単一のバックグラウンドプロセス（ウィンドウごとではないため、Developer: Reload Window では再起動 されません）— がメモリ内に古いサブプロセスを保持していることを意味します。アプリを完全に終了（ウィンドウを閉じるだけでなく Cmd+Q）してから再度開きます。これにより、Shared Process とそれに伴うすべての MCP サブプロセスが強制終了されます。

5. 推測ではなくプロトコルレベルで確認するには: Cmd+Shift+U -> MCP Logs ドロップダウン -> stark-brain -> tools/list レスポンスに実際に新しいツール名が含まれているか確認します。そこにもない場合、問題は Cursor のキャッシュではなくインストールされたバンドルです。ステップ 1 に戻ってください。

6. 新しいツールが表示されたら、status ツールを実行して更新が反映されたことを確認します（docs_mode、repo、ref、embed_model が期待どおりであることを確認してください）。

7. ドキュメントのコンテンツのみが変更された場合（コードは変更されていない場合）、再インストールは不要です。IDE から refresh_docs() を呼び出すだけです。

更新時には、PAT を再生成したり gcloud auth をやり直したりする必要は ありません。これらの認証情報はインストールされたバージョンとは独立しています。

9. 初回実行と使用方法

• 最初のドキュメントツール呼び出しで、サーバーは alexandria のコンテンツを取得し、ローカルインデックスを構築します（埋め込みモデルが最初にダウンロードされる間、少し時間がかかる場合があります）。

• ドキュメント変更後は refresh_docs を使用して再同期します（増分: 変更されたファイルのみが再埋め込みされます）。

• status は、ドキュメントモード、インデックス化されたファイル数、レート制限、および Stark Bank API の認証情報が設定されているかどうか（starkbank_api_configured）を報告します。

• Stark Bank API ツールはデフォルトで development になります。ユーザーが明示的に sandbox を要求した場合にのみ environment="sandbox" を渡します。

利用可能なツール:

10. リモートモードとローカルモード

• remote（デフォルト）：ドキュメントはあなたの PAT 経由で GitHub から取得されます。効率的ですが（tarball = リフレッシュあたり 1 リクエスト）、GitHub API の割り当てを消費します。

• local：自分でクローンしたディレクトリからドキュメントを読み取ります。API 使用量はゼロです。

GitHub のレート制限が上限に近づくと、サーバーは警告し、切り替えを提案します。切り替えるには：

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

次のいずれかの方法で mcp.json に設定します：

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

または、ツールを介して実行時に切り替えます：

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. 設定リファレンス（環境変数）

.env.example を参照してください。

12. トラブルシューティング

• configuration error: ALEXANDRIA_GITHUB_PAT is required — mcp.json の環境変数に PAT を設定するか、local モードに切り替えてください。

• GitHub 401 — PAT が無効または期限切れです。再生成してください。

• GitHub 404（"Repo or ref not found"）がリポジトリが存在するのに出る場合 — プライベートリポジトリでは、リソースが本当に存在しない場合も、トークンがそれを参照できない場合も GitHub は 404 を返すため、これはほとんどの場合トークン/アクセスの問題であり、ALEXANDRIA_REPO/ALEXANDRIA_REF の誤りではありません。最も一般的な原因は、組織管理者の承認がまだ保留中の fine-grained PAT です（https://github.com/settings/personal-access-tokens を確認 — "Pending" と表示されている場合は、セクション 3 で承認手順または classic PAT へのフォールバックを参照）。diagnose_github_access() を実行して、この問題を特定するライブチェックを行ってください。

• GitHub 403 / レート制限 — PAT の権限を確認するか、クローンして local モードを使用してください。

• GCP credentials not found — gcloud auth application-default login を実行してください。

• Datastore/Logging の権限エラー — アクセス権のないプロジェクトにクエリを実行しました。別の project を選択するか、アクセスをリクエストしてください。

• 初回実行時のモデルダウンロードが遅い — 埋め込みモデルは最初の使用後に STARK_BRAIN_CACHE_DIR 配下にキャッシュされます。

• 再インストール後、新しく追加したツールが表示されない — これはインストール不良ではなく、Cursor 側の古いプロセスが原因です（手順はセクション 8を参照）。実行中の MCP サブプロセスは、ディスク上の再インストールを自動的には反映しません。Tools & MCP でサーバーをオフ/オンに切り替え、新しいチャットを開き、それでも不十分な場合は、完全に終了（Cmd+Q）して Cursor を開き直してください。

• STARKBANK_PRIVATE_KEY_PATH is not set / APIツールが失敗する — mcp.json に PEM の絶対パスと STARKBANK_PROJECT_ID を設定してください（セクション 5 を参照）。status().starkbank_api_configured が true であることを確認してください。

• Stark Bank API 401 / 無効な署名 — プロジェクト ID の誤り、その環境に PEM が登録されていない、または時刻のずれが原因です。対応する Web Banking 環境（development と sandbox）に公開鍵が登録されていることを確認してください。

13. セキュリティに関する注意事項

• あなたの PAT は Authorization ヘッダーでのみ送信され、記録されることはありません。

• Stark Bank の秘密鍵はリクエスト時にディスクから読み取られ、記録されることはありません。

• サービスアカウントキーは配布されません。GCP アクセスはあなた個人の ADC アイデンティティです。

• GCP の project は呼び出しごとに渡されます。共有/ハードコードされたプロジェクトはありません。

• 本番の Stark Bank API ホストはクライアントによって拒否されます。

• .env、*.pem、keys/、およびローカルキャッシュは git の無視対象です。

14. 開発

ソースファイルは src/ 直下にフラットに配置されています（追加の src/mcp_stark_brain/ ネストはありません）。pyproject.toml のビルド設定により、これらは wheel 内で mcp_stark_brain インポートパッケージとして出荷されます（packages = ["src"] + sources = {"src" = "mcp_stark_brain"}）。そのため、エントリーポイントと内部インポートは、ディスク上のレイアウトに関係なく変更されません。

このリネームは編集可能/開発モードのインストールと互換性がありません（hatchling/pip の制限）。そのため uv sync は tool.uv.package = false で構成されています。つまり、プロジェクト自体ではなく依存関係のみをインストールします。conftest.py と scripts/smoke_test.py は devtools/bootstrap.py を使用して、テストとローカルスクリプトで import mcp_stark_brain を src/ に対して直接動作させ、インストール手順を不要にしています。

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

実際にサーバーをローカルで試すには（wheel ビルドは不要）：

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"