Twining MCP Server

問題点

あなたはClaude Codeと2時間かけてアーキテクチャの意思決定を行います。MongoDBではなくPostgreSQLを選択し、認証にはJWTを採用し、決済モジュールに競合状態があることをフラグ立てします。そしてセッションが終了します。

翌日、新しいセッションを開始します。Claudeは何が起こったのか全く知りません。意思決定は消え、警告は消え、根拠も消えています。あなたはすべてを再説明しなければなりません。さらに悪いことに、Claudeが昨日の選択と矛盾する提案を黙って行うことさえあります。

これは複数のエージェントがいるとさらに悪化します。エージェントAはRESTを採用し、エージェントBは同じサービスにgRPCを選択します。どちらも相手の存在を知りません。コードがコンパイルできなくなった時に初めて気づくことになります。

コンテキストウィンドウは一時的なものです。プロジェクトの意思決定までそうあるべきではありません。

Twiningによる解決策

Twiningは、AIエージェントに永続的なプロジェクトメモリを提供するMCPサーバーです。意思決定はコンテキストのリセットを生き延び、新しいセッションは情報が共有された状態で開始されます。マルチエージェント作業は調整されたまま維持されます。

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

行ったことを自然言語で記録する:

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twiningはあなたの意思決定を構造化されたレコードに解析し、根拠、却下された代替案、ドメインを自動的に抽出します。ツール呼び出しは1回だけ、フォーム入力は不要です。

新しいセッションを開始し、即座に状況を把握する:

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twiningはすべての意思決定、警告、発見事項をタスクとの関連性に基づいてスコアリングし、優先順位に従ってトークンバジェットを埋めます。必要なコンテキストだけを正確に取得できます。情報の洪水や再説明は不要です。

なぜそうなっているのかを尋ねる:

twining_why({ scope: "src/auth/middleware.ts" })

任意のファイルに対する完全な意思決定チェーンを返します。何が決定され、いつ、なぜ、どの代替案が却下され、どのコミットで実装されたかがわかります。

なぜCLAUDE.mdでは不十分なのか？

CLAUDE.mdは静的です。一度書いて手動で更新する必要があります。意思決定が「発生したその時」に記録されず、根拠や代替案を追跡できず、エージェント間の競合を検出できず、トークンバジェット内でコンテキストを選択的に組み立てることもできません。

Twiningは動的です。すべての twining_decide 呼び出しが構造化された意思決定を記録します。すべての twining_post が発見事項や警告を共有します。すべての twining_assemble が関連性をスコアリングし、現在のタスクに必要なものを正確に提供します。.twining/ ディレクトリは、あなたのプロジェクトの生きた組織的記憶となります。

なぜオーケストレーターではないのか？

オーケストレーター（エージェントスウォームや階層型コーディネーターなど）は、「タスクを割り当てる」ことで作業をルーティングします。Twiningは「状態を共有する」ことで調整します。この違いは重要です：

• オーケストレーターは、調整コンテキストを自身のコンテキストウィンドウ内に保持します。これはウィンドウが埋まるにつれて劣化する単一障害点です。

• Twiningのブラックボードは、調整状態をエージェントのウィンドウ外に永続化し、情報損失なしにコンテキストのリセットを生き延びます。

エージェントはブラックボードを読むことで自律的に作業を選択します。中央のボトルネックはありません。コンテキストを落とすリレーもありません。すべてのエージェントが、他のすべてのエージェントの意思決定と警告を直接確認できます。

インストール

プラグインインストール（推奨）

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

MCPサーバー、スキル、ライフサイクルフック、およびコミット前の強制チェックが含まれます。2つのゲート：作業前の twining_assemble とコミット前の twining_record。フックがこれら両方を自動的に強制します。

チーム向け自動インストール

リポジトリの .claude/settings.json にこれをコミットすると、チームメンバー全員がクローン時にTwiningを取得できます：

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

チームメンバーがリポジトリフォルダを信頼すると、Claude Codeは自動的にマーケットプレイスとプラグインをインストールします。

MCPのみのインストール

Claude Code以外のクライアント（Cursor、Windsurfなど）の場合：

claude mcp add twining -- npx -y twining-mcp --project .

または .mcp.json に追加します：

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

MCPサーバーの指示は、初期化レスポンスに自動的に含まれます。

手動インストールからのアップグレード

以前にTwiningを手動で設定していた場合は、プラグインに切り替えてください：

1. 手動MCPサーバーを削除: claude mcp remove twining

2. プラグインをインストール: /plugin marketplace add daveangulo/twining-mcp を実行し、次に /plugin install twining@twining-marketplace

3. クリーンアップ: .claude/settings.json からTwiningフックを削除、存在する場合は .claude/agents/twining-aware.md を削除、CLAUDE.md からTwiningセクションを削除（現在はスキルが処理します）

4. 保持: .twining/ ディレクトリ（すべての状態が保持されます）

5. 検証: /twining:status

最大限に活用するために

プラグインはスキルを通じてエージェントの指示を自動的に処理します。MCPのみのインストールパスの場合は、エージェントが自動的に使用するようにプロジェクトの CLAUDE.md にTwiningの指示を追加してください。コピー可能なテンプレートについては docs/CLAUDE_TEMPLATE.md を参照してください。

ダッシュボード

http://localhost:24282 でWebダッシュボードが自動的に起動します。意思決定、ブラックボードエントリ、ナレッジグラフ、エージェントの状態を閲覧できます。TWINING_DASHBOARD_PORT で設定可能です。

内容物

コアツール（常に利用可能）

これらはエージェントがすべてのセッションで使用するツールです：

twining_record は、「RedisではなくMemcachedを選択 — 永続性が必要」といった自然言語の意思決定を受け入れ、根拠、却下された代替案、推論されたドメインを含む構造化されたレコードに自動的に解析します。また、前提条件、制約、影響を受けるファイル、依存関係チェーンなど、意思決定ストアが高忠実度のコンテキストを組み立てるために必要なすべてを受け入れます。

拡張ツール（full_surface: true で利用可能）

高度なワークフロー向け — 詳細な意思決定管理、グラフ探索、マルチエージェント調整：

.twining/config.yml で有効にします：

tools:
  full_surface: true

仕組み

すべての状態は .twining/ 内にプレーンファイルとして存在します。ブラックボードにはJSONL、意思決定、グラフ、エージェント、引き継ぎにはJSONを使用します。すべてが jq でクエリ可能、grep 可能、gitで差分確認可能です。データベースもクラウドもアカウントも不要です。

アーキテクチャ層:

• ストレージ — 同時アクセスのためのロックを備えたファイルベースのストア

• エンジン — 意思決定追跡、ブラックボード、グラフ探索、トークンバジェットを用いたコンテキスト組み立て、エージェント調整

• 埋め込み — @huggingface/transformers を介したローカルの all-MiniLM-L6-v2。遅延読み込みされ、キーワードフォールバックを備えています。埋め込みの問題でサーバーが起動しないことはありません。

• ダッシュボード — cytoscape.jsグラフ可視化とvis-timelineを備えた読み取り専用Web UI

• ツール — Zodで検証されたMCPツール定義。ツールサーフェスと1対1でマッピング

完全な仕様については TWINING-DESIGN-SPEC.md を参照してください。

FAQ

TwiningはClaude Codeを遅くしますか？ いいえ。ローカルのMCPサーバーであり、ツール呼び出しはローカルファイルの読み書きです。セマンティック検索は初回使用時に遅延読み込みされます。

Cursor、Windsurf、その他のMCPクライアントで使用できますか？ はい。Twiningは標準的なMCPサーバーです。あらゆるMCPホストが接続可能です。

データはどこに行きますか？ すべての調整状態は .twining/ 内にローカルに保存されます。ツール呼び出しのメトリクスは .twining/metrics.jsonl（gitignore対象）にローカル保存されます。オプションで匿名テレメトリを有効にできます。以下の Analytics を参照してください。

Twiningはエージェントオーケストレーターですか？ いいえ。これは調整状態レイヤーです。エージェントが何をなぜ決定したかをキャプチャし、その知識を将来のエージェントが利用できるようにします。オーケストレーター、エージェントチーム、またはスタンドアロンセッションと併用してください。

分析

Twiningには、提供する価値を理解するための3層の分析システムが含まれています。

インサイトダッシュボードタブ

Webダッシュボードには、以下を表示する Insights タブが含まれています：

• 価値メトリクス — 盲目的な意思決定の防止率、警告の承認、tested_by グラフ関係によるテストカバレッジ、コミットの追跡可能性、意思決定ライフサイクル、ナレッジグラフ統計、エージェント調整メトリクス

• ツール使用状況 — 呼び出し回数、エラー率、ツールごとの平均/P95レイテンシ

• エラーの内訳 — ツールおよびエラーコードごとにグループ化されたエラー

すべての価値メトリクスは既存の .twining/ データから計算されるため、新しいデータ収集は不要です。

ツール呼び出しメトリクス

すべてのMCPツール呼び出しは、タイミングと成功/エラー追跡で自動的に計測されます。メトリクスは .twining/metrics.jsonl（gitignore対象 — アーキテクチャデータではなく運用データ）にローカル保存されます。

ローカルメトリクスの収集を無効にするには、.twining/config.yml で以下を設定します：

analytics:
  metrics:
    enabled: false

オプトインテレメトリ

匿名化された集計使用データは、Twiningの改善を支援するためにPostHogに送信される場合があります。デフォルトでは無効です。 有効にするには、.twining/config.yml に以下を追加します：

analytics:
  telemetry:
    enabled: true

以上です。PostHogプロジェクトキーはソースコードに組み込まれています。独自のPostHogインスタンスを実行している場合は、posthog_api_key と posthog_host で上書きできます。

送信される内容: ツール名、呼び出し時間、成功/失敗のブール値、サーバーバージョン、OS、アーキテクチャ。

送信されない内容: ファイルパス、意思決定の内容、エージェント名、エラーメッセージ、ツール引数、環境変数。

プライバシー保護:

• DO_NOT_TRACK=1 環境変数は常に設定を上書きします

• CI=true は自動的にテレメトリを無効にします

• IDはホスト名 + プロジェクトルートのSHA-256ハッシュです（生のパスではありません）

• ネットワーク障害はサイレントに処理されます（再試行なし）

• posthog-node はオプションの依存関係であり、インストールされていない場合は正常に動作を停止します

開発

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

Node.js >= 18 が必要です。

CI/CD

2つのGitHub Actionsワークフローがビルド検証と公開を自動化します：

CI (.github/workflows/ci.yml) — すべてのPRおよび main へのプッシュで実行：

• Node 18、20、22でビルドとテストを実行

• 同じブランチに新しいプッシュが到着したときに進行中の実行をキャンセル

公開 (.github/workflows/publish.yml) — v* タグのプッシュで実行：

• 公開パッケージ用に POSTHOG_API_KEY を組み込んでビルド

• 防御的プログラミングとして完全なテストスイートを実行

• サプライチェーン証明のために --provenance を付けてnpmに公開

• 自動生成されたリリースノートでGitHubリリースを作成

• ドライ