motif

Motif MCP サーバー

Claude Code、Cursor、Claude Desktop、および任意の MCP ホストから利用できるサーバーです。 エージェント環境で作業するデザイナーやリサーチャーは、「これらのトランスクリプトを統合して」と指示するだけで、CLI が出力するものと同じ、出典が示され批評による検証済みの結果を得られます。各ツールは synth/engine.py を呼び出すだけで、ループ、プロンプト、設定は CLI および FigJam プラグインと共有され、重複して実装されることはありません。

ツール

ツール	入力	出力
motif_synthesize	transcripts_dir または files、question、condition（A/B/C）、max_iterations	実行 ID、insights JSON、レポート Markdown、異論のある insight ID、コスト
motif_critique	insights（JSON）または document（Markdown／文章）；run_id または transcripts_dir；任意の transcripts、question	判定 JSON（pass、failures、notes、skipped_rules）、ルール別および insight 別の要約、構造化された insights、独自の実行 ID
motif_receipts	turn_ids；run_id または transcripts_dir	ターンの原文、話者、その話者がインタビュアーかどうか；missing
motif_board	run_id、columns、origin_x、origin_y	FigJam レイアウト JSON ＋ insight ごとに 1 つの use_figma スクリプト。ホストが Figma の MCP サーバー経由で実行します
motif_runs_get	run_id、include	メタ情報、メモ、反復ごとの判定；任意で insights、レポート、呼び出しごとのトークン数／所要時間

失敗時の動作：判定がない、統合結果が空、ドキュメントを解析できない、実行が存在しない、または指定されたターン ID がすべて存在しない場合は、いずれも MCP ツールエラーを返します。空の結果を成功として返すことはありません。

進捗：エンジンの進捗行（取り込んだ各トランスクリプト、各モデル呼び出し、各批評の反復）はすべて、MCP ログ通知と進捗通知の両方として送信されます。ホストがログレベルを設定している場合に限り、MCP ログ通知を受け取れます。進捗トークンを渡した場合（Claude Code は渡します）は、進捗通知を受け取れます。stdout はプロトコル専用です。それ以外の内容が書き込まれることはありません。

インストール（ローカルモード）

PyPI から、Python 3.10 以降の任意の環境にインストールします。

pip install "etot-motif[mcp]"
which motif-mcp                # the server entry point; hosts need this absolute path

インストール手順なしで使う場合は、uv を利用できます。コマンドは uvx --from "etot-motif[mcp]" motif-mcp です。この方法でインストールしたサーバーは、パッケージに含まれる設定を使用し、実行ログを ~/.motif/runs に書き込みます（MOTIF_RUNS_DIR で変更できます）。

Motif のチェックアウトから利用する場合：

git clone https://github.com/sleepycobalt/motif.git
cd motif
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp]"
echo "ANTHROPIC_API_KEY=your-key-here" > .env
ls .venv/bin/motif-mcp        # the server entry point

サーバーは環境変数またはリポジトリの .env から ANTHROPIC_API_KEY を読み込み、実行ログをリポジトリ内の runs/ に書き込みます（MOTIF_RUNS_DIR で変更できます）。また、パッケージに含まれる synth/synth.yaml へのシンボリックリンクである config/synth.yaml を使用します（MOTIF_CONFIG で変更できます）。 以下の各ホストには .venv/bin/motif-mcp の絶対パスが必要です。ホストは、シェルの PATH を引き継がずにサーバーを起動します。

Claude Code

claude mcp add motif -- /ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp

必要に応じてスキルをインストールすると、Claude Code がワークフロー（receipts で出典を検証する、異論のある insights に注意する、FigJam に送信する）を把握できるようになります。

mkdir -p ~/.claude/skills/motif
cp /ABSOLUTE/PATH/TO/motif/surfaces/mcp/skills/motif/SKILL.md ~/.claude/skills/motif/SKILL.md

その後、新しい Claude Code セッションで次を実行します。

/mcp                                   # motif should show as connected
synthesise ./data/raw/Dataset-2 with motif and open the report

Claude Code は motif_synthesize を呼び出してエンジンの進捗をストリーミングし、その後 motif_receipts を呼び出して任意の引用を検証したり、motif_board を呼び出して Figma の MCP サーバー経由で実行結果を FigJam ボードに送信したりできます。

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "motif": {
      "command": "/ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp",
      "env": { "ANTHROPIC_API_KEY": "your-key-here" }
    }
  }
}

Cursor を再起動すると、5 つの motif_* ツールが MCP ツールの一覧に表示されます。

Claude Desktop

設定ファイルを開く（Claude メニュー → Settings → Developer → Edit Config）か、直接編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "motif": {
      "command": "/ABSOLUTE/PATH/TO/motif/.venv/bin/motif-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here",
        "MOTIF_RUNS_DIR": "/ABSOLUTE/PATH/TO/motif/runs"
      }
    }
  }
}

Claude Desktop を終了して再度開くと、チャットボックスのツールアイコンの下にツールが表示されます。Claude Desktop はディスク上のファイルを開けないため、返信でレポートの Markdown を求めるか、実行ディレクトリから読み取ってください。

リモートモード

MOTIF_REMOTE_URL を設定すると、同じ5つのツールがエンジンをローカルで実行する代わりに、ホストされた Motif サービス（surfaces/hosted/）に処理を転送します。サーバー自体以外に Python 依存関係は不要で、同じ結果が得られます。ANTHROPIC_API_KEY は各ジョブとともに転送され、そのジョブでのみ使用されます。 リモートモードでは、ツールの run_id はホストされたジョブ ID です。ジョブ完了後1時間有効で、motif_receipts、motif_board、motif_runs_get に渡します。ホストされたエンジンはロガーの redact=True で実行されます。プロンプトと応答の本文は長さと SHA-256 として保存され、コーパスのスナップショットは作成されず、ジョブのアップロードファイルは有効期限に削除されます。MOTIF_REMOTE_TOKEN を設定すると有料プランが選択されますが、まだ有効化されていません。

claude mcp add motif -e MOTIF_REMOTE_URL=https://motif-hosted.fly.dev -e ANTHROPIC_API_KEY=your-key-here -- motif-mcp

Figma の MCP サーバー経由でのボード出力

motif_board はレイアウトとスクリプトを返します。Figma には接続しません。ホスト（Figma の MCP サーバーで認証された Claude Code）が、FigJam ボードの URL に対して use_figma を使って各スクリプトを実行し、get_figjam で結果を読み取ります。実際のボードで検証済みです（2026-09-04、docs/exhibits/step-zero/、docs/exhibits/board-r5/）。

リスティング

listing.md には、MCP サーバーを登録するディレクトリ向けの説明が記載されています。server.json は公式 MCP レジストリ用のマニフェストです（パッケージを PyPI に公開した後に公開してください）。

テスト

.venv/bin/python -m pytest -q tests               # offline: stubbed model, spawns the server over stdio
.venv/bin/python scripts/critique_acceptance.py   # spends API budget: critic vs eval2 human scoring