Heuresis

@heuresis/mcp

任意の MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、 Windsurf、カスタムエージェント）に Heuresis ワークスペースを公開する Model Context Protocol（MCP）サーバーです。このサーバーはユーザーの Heuresis アカウントにログインし、Web アプリと同じ Supabase プロジェクトに 接続して、同じ RLS に従います。Web アプリと MCP は、1 つのクラウド ワークスペースを利用する 2 つのフロントエンドです。

現在のバージョン：1.0.0-rc.13。

インストール

npm install -g @heuresis/mcp
# or on demand without installing:
npx -y @heuresis/mcp

パッケージ名とコマンド名について。 npm パッケージは @heuresis/mcp で、 インストールされるコマンドは heuresis-mcp です。サブコマンドを指定せずに npx -y @heuresis/mcp を実行すると MCP サーバーは問題なく起動しますが、 npx @heuresis/mcp login は heuresis-mcp: not found で失敗する場合が あります。npx がスコープを除いたパッケージ名（mcp）からコマンド名を 推測するため、実際のコマンド名と一致しないからです。すべての npm／OS で サブコマンドを確実に実行するには、-p を使ってバイナリを明示してください。

npx -y -p @heuresis/mcp heuresis-mcp login

クイックスタート

1. このマシンを Heuresis アカウントにリンクする

npx -y -p @heuresis/mcp heuresis-mcp login

CLI にデバイスコードと、https://heuresis.app/device?code=XXXX-XXXX 形式のワンクリック URL が表示されます。ブラウザーで開き、まだサインイン していない場合はサインインして、デバイスを確認してください。CLI は バックグラウンドでポーリングし、確認された時点で認証情報を ~/.heuresis/credentials.json に書き込みます（POSIX では chmod 600）。 以降、MCP の実行時にメッセージは表示されません。

ログインフローでは、次の 3 つの Supabase Edge Functions を利用します。 mcp-device-init、mcp-device-grant、mcp-device-poll。

マシンのリンクを解除するには、npx -y -p @heuresis/mcp heuresis-mcp logout を実行するか、Web アプリの「Settings ▸ Connected devices」を開いて リモートから取り消してください。

npx -y -p @heuresis/mcp heuresis-mcp whoami を実行すると、現在そのマシンに リンクされているアカウントを確認できます。

2. MCP クライアントを接続する

Claude Desktop。 macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、 Windows では %APPDATA%/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
  }
}

Claude Code／Cursor／Windsurf。 ワークスペースのルートに .mcp.json を配置します。

{
  "mcpServers": {
    "heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
  }
}

クライアントを再起動します。Heuresis のツールがツールメニューに表示されます。

3. CLI サブコマンド

npx -y -p @heuresis/mcp heuresis-mcp whoami   # show the linked account + device
npx -y -p @heuresis/mcp heuresis-mcp logout   # delete the credentials file
npx -y -p @heuresis/mcp heuresis-mcp --help   # all options
npx -y @heuresis/mcp --no-realtime            # boot the server with live sync off (persisted)
npx -y @heuresis/mcp --realtime               # re-enable live sync

ヘッドレスモード（CI、クラウドエージェント、一時コンテナ）

デバイスのペアリングでは、リフレッシュトークンがディスクに書き込まれます。 個人のマシンでは問題ありませんが、一時的な環境（CI ランナー、クラウド エージェントのコンテナ、「Claude Code on the web」）では維持されません。 実行ごとにファイルシステムが消去され、Supabase のリフレッシュトークンは ローテーション時に一度しか使えないため、設定に埋め込んだトークンは 最初のセッション後に使えなくなります。

このような環境では、ペアリングを省略し、アカウントのメールアドレスと パスワードを使ってサーバーが起動のたびに新たにサインインするようにします （パスワードは使用しても消費されないため、再ペアリングなしで使い続けられます）。 次の 3 つの環境変数を設定してください。

[email protected]          # your Heuresis account email
HEURESIS_PASSWORD=your-account-password # secret — store it in a secrets manager
HEURESIS_ANON_KEY=sb_publishable_...    # project anon/publishable key (public, not a secret)
# optional: HEURESIS_SUPABASE_URL=...   # defaults to the production project

HEURESIS_EMAIL と HEURESIS_PASSWORD が設定されている場合、それらは credentials.json より優先され、MCP サーバーは起動のたびに認証します。 デバイスをリンクする必要はありません。要件は次のとおりです。

• Supabase プロジェクトでメールアドレスとパスワードによるサインインが 有効になっており、アカウントにパスワードが設定されている必要があります （パスワードレス／マジックリンクのみのアカウントでは、先にパスワードを 設定する必要があります）。
• HEURESIS_PASSWORD はシークレットとして扱ってください。環境変数をユーザーに 見られる形でしか公開できない環境では、専用アカウントの使用をおすすめします。

ライブ同期

MCP がクラウドモードで起動すると、Supabase Realtime を介してワークスペースを 購読し、nodes、edges、projects、ideas の行が変更されるたびに クライアントへ通知します。Web アプリで行った編集は手動で更新しなくても エージェントの表示に反映され、MCP に接続されたクライアントからの書き込みも 同様に、ほかの接続中のクライアントへ届きます。--no-realtime を指定すると 購読を無効にできます（通知が多すぎる場合や、クライアントがすべての通知を ログに記録する場合に便利です）。この設定は ~/.heuresis/config.json に保存 されるため、フラグを指定するのは一度だけでかまいません。

ツール

合計34個のツールがあります。クラウドワークスペース用のデータツールが31個、ウェブアプリと同じアイデーションオペレーターを実行するオペレーターツールが3個です。

読み取り（10個）。 get_workspace_summary、list_projects、 get_project_graph、list_concepts、list_edges、get_subtree、 get_concept、search_concepts、find_concepts、 list_recent_decisions。ほとんどのエージェントセッションは、 get_workspace_summary または list_projects から開始します。

書き込み（21個）。 コンセプト：add_concept、update_concept、 bulk_add_concepts、set_parent、validate_concept、set_standing、 archive_concept、unarchive_concept、star_concept、 remove_concept。エッジ：link_concepts、add_kref。アイデア： create_idea、rename_idea、recolor_idea、set_idea_members、 add_to_idea、delete_idea。プロジェクト：create_project、 update_project、delete_project。すべての書き込みで public.provenance に origin='mcp' の行が記録されるため、ウェブアプリのセッションログで どのインターフェイスから変更されたかを確認できます。

オペレーターの実行（3個）。 run_operator（Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction で候補を生成）、 run_operator_and_commit（同じ処理を行い、1回の往復で結果もコミット）、 および expand_concept（再帰的な Branch。深度 × 幅 ≤ 60 に制限）。

ツールの入力形式は、ウェブアプリの対応する src/agent/tools.ts と同じです。そのため、両方のインターフェイスを使うエージェントには 一貫した仕様が提供されます。

今後の対応：find_in_files（ブラウザー内の埋め込み検索）はウェブアプリにありますが、MCP にはまだありません。

レガシー スナップショットモード（非推奨）

従来の読み取り専用スナップショットリーダーは、ユーザーがクラウド認証に移行する間、フォールバックとして引き続き動作します。 ~/.heuresis/credentials.json がなく、HEURESIS_SNAPSHOT 環境変数が設定されている場合、 サーバーはディスク上の JSON エクスポートを読み込み、従来の読み取り専用ツール一式 （get_workspace_summary、list_projects、search_concepts、 get_concept、get_subtree、get_project_graph、 list_recent_decisions）を公開します。

export HEURESIS_SNAPSHOT="/absolute/path/to/your-export.json"
npx @heuresis/mcp

この方法は非推奨であり、今後のリリースで削除されます。クラウド認証への移行期間中も、既存のセットアップを引き続き利用できるようにするためのものです。

ライセンス

AGPL-3.0-or-later.