Kawa Code

Kawa Code MCP

AI コーディングアシスタント向けのチーム対応メモリです。意図を追跡し、決定事項を記録し、チームメイトが同じコードを編集していることをコミット前にリアルタイムで確認できます。

@kawacode/mcp は、Kawa Code の公式 Model Context Protocol（MCP）サーバーです。Claude Code、Cursor、および MCP 互換のあらゆる AI アシスタントで、次のことができます。

• セッション、ブランチ、マシンをまたいで、作業中の内容を記憶します。毎朝、アーキテクチャを説明し直す必要はありません。
• チーム内の競合を事前に検知します。コミットする前に、チームメイトが作業コピーで同じファイルや関数を今まさに編集していることを把握できます。
• アーキテクチャ上の決定と、その理由を記録します。将来の自分（および将来の AI セッション）は、選択を再び議論することなく、チームに蓄積されたコンテキストを引き継げます。
• コミットと意図を自動的に関連付けます。すべてのコミットに、差分だけでなく、その理由も記録されます。

前提条件

必須

• Node.js >= 18.0.0 — MCP サーバーのランタイム
• Kawa Code デスクトップアプリが起動していること — kawa.mcp は MCP と IPC 間の薄いアダプターです。すべての git 操作、ストレージ、API 通信は Kawa Code 内で行われます。

任意（履歴の推定用）

• Anthropic API キー — ご自身の Claude API キーを、推定ツールのパラメーターとして渡します。
• GitHub CLI (gh) — より豊富なデータ階層（PR の説明、レビューコメント、Issue の議論）が利用できます。gh がない場合、階層 2 と 4 は自動的にスキップされます。

インストール

AI の設定に MCP を追加します。たとえば Claude Code では、次のようにします。

claude mcp add -s user kawa-intents -- npx -y @kawacode/mcp

Cursor AI では、npm install -g @kawacode/mcp で MCP をインストールし、~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "kawa-intents": {
      "command": "kawacode-mcp"
    }
  }
}

この方法では、MCP は今後のバージョンに自動更新されないことに注意してください。 新しいリリースにアップグレードするには、npm update -g @kawacode/mcp を実行します。

手動インストール

Kawa Code を実行するプロジェクトのルートに .mcp.json ファイルを作成します（チームでの利用を推奨します。git にコミットしてください）。

{
  "mcpServers": {
    "kawa-intents": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kawacode/mcp"]
    }
  }
}

使用方法

MCP サーバーは、Kawa Code アプリケーション、Kawa Code IDE 拡張機能、および Cursor AI や Claude Code などの AI コード生成ツールと連携します。

編集前の決定事項チェック（Claude Code フック）

任意です。エージェントが、過去に記録された理由が関連付けられているコード（重複する意図のブロック、または relatedFiles にファイルが含まれる制約）を編集しようとすると、Edit が実行される前にフックがその情報を表示します。推奨内容はアクションに対応します。silent（続行）、advisory context injected（確認用のコンテキストを挿入）、または stderr メッセージでブロック（investigate-upstream）です。

~/.claude/settings.json またはプロジェクトの .claude/settings.json で、Claude Code の PreToolUse フックとして設定します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx -y -p @kawacode/mcp kawacode-on-pre-edit" }
        ]
      }
    ]
  }
}

ブロックされた場合のパスを上書きする方法：

• 永続的（推奨）： 既存の決定に優先する分岐決定を記録してから、Edit を再試行します。

  record_decision(type: "fork", supersedes: ["<surfaced-decision-id>"], rationale: "...")
  

• 一度限りの回避策： Edit ツールの引数に force: true を追加します。フックは表示した決定事項をセッションキャッシュに記録し、編集を許可します。キャッシュは Kawa Code デーモンの再起動時にリセットされます。

セッション中にフックを無効にするには、KAWA_PRE_EDIT_CHECK=off を設定します。

ローカルテレメトリー（ログ）

編集前チェックが実行されるたび（および強制上書き時）、JSON の行が日ごとにローテーションされるファイル ~/.kawa-code/logs/pre-edit-decision-check-YYYY-MM-DD.jsonl に追加されます。ログはローカルのみに保存され、マシンの外部に送信されることはありません。デフォルトでは直近 30 日分を保持し、合計 100 MB を上限とします（古いファイルから削除されます）。

各行には、何が実行され、なぜ実行され、何が除外されたかが記録されます。推奨しきい値の調整や、時間の経過に伴う誤検知の発見に役立ちます。

テレメトリーを無効にするには、KAWA_PRE_EDIT_TELEMETRY=off を設定します。

主な機能

• リアルタイムのチーム競合検出 — チームメイトが作業コピー内の同じファイルや行を編集していると、どちらかがコミットする前に確認できます。ほとんどのバージョン管理ツールではマージ競合が起きてから表示されますが、Kawa ならその前に確認できます。
• セッションをまたいだ AI メモリ — AI アシスタントは、日をまたいでも、ブランチやマシンが変わっても、前回の続きから作業できます。毎朝、アーキテクチャを説明し直す必要はありません。
• 理由を含む意思決定の履歴 — 分岐点、トレードオフ、採用しなかったアプローチと、その 理由 を記録できます。後続のセッションやチームメイトは、その経緯を再検討するのではなく、コンテキストを引き継げます。
• コミット ↔ 意図の関連付け — すべてのコミットが、その原動力となった意図に自動的に関連付けられます。git log では何が変わったかがわかり、Kawa ではその理由がわかります。
• スマートなコンテキスト取得 — 関連性に基づいて読み込み、現在のタスクに必要な情報だけを取得します。
• ゼロ知識暗号化 — 同期前に、コードブロックをクライアント側で暗号化します。Kawa クラウドがチームのコードを復号することはできません。
• クロスプラットフォーム — Claude Code、Cursor、および MCP 対応の AI アシスタントで動作します。

コードベースを移行または書き換えていますか？意思決定を引き継ぎましょう

コードベースを新しい言語に移植したり、新しいリポジトリで再構築したりすると、コードは移りますが、その 理由 は通常引き継がれません。ソースリポジトリの意思決定履歴には、廃止されたアプローチを廃止した理由、重要な制約、セキュリティ上の落とし穴が記録されています。Kawa Code を使えば、その履歴を移行時の第一級の入力情報として活用できます。

意思決定はリポジトリごとに管理されるため、新しいリポジトリに古いリポジトリの履歴が自動的に表示されることはありません。移植する際に、スライスごとに引き継いでください。これが 想起・移植ワークフロー です。

1. 各スライスの移植前に想起します。 移植するサブシステムの説明（主要なファイル名を含めてください）を指定し、ソース リポジトリに対して get_relevant_context を呼び出します。これにより、そのサブシステムを形作った分岐点、制約、トレードオフ、発見事項が表示されます。
2. 重要なものを掘り下げます。 想起によって返されるのは要約です。重要な情報を含む結果について get_decision_detail を呼び出し、根拠と結果の詳細を確認します。
3. スタックをまたいで移植可能か、スタック固有かを分類します。 ドメイン上の知見は移植できます。プロトコル契約、コストやスケールの根拠、セキュリティ上の発見事項、「X を試して廃止した」という警告などです。古いスタックの仕組みは移植できません。ビルドツールの癖、ランタイムの回避策、ライブラリ固有の修正などです。移植するのは、スタックをまたいで使えるものだけです。
4. 移植可能なものを record_decision で 移植先 リポジトリに再記録し、要約または根拠に出典を記載します（例：[transplanted from <source-repo> <decision-id>]）。一連の経緯を共有する意思決定は、ひとつの記録にまとめます。
5. 移植した内容を、移植作業とテストに反映します。 移植した耐久性の根拠は、書き換え後もその特性が保たれていることを証明するテストにします。廃止したアプローチに関する警告は、新しいスタックで同じものが再導入されないようにします。

こうして得られる効果は積み重なります。移植時に決着済みの議論を蒸し返したり、古いバグを忠実に再現したりせずに済みます。動機となったコードがずっと前に削除されていても、否定的な知見 は残ります。また、切り替え時に新しいリポジトリは空の状態ではなく、厳選された意思決定の記録を備えた状態でスタートできます。

CLAUDE.md テンプレート には、このワークフローの簡潔なバージョンが含まれているため、Kawa Code のウェルカムフローでセットアップされたエージェントは自動的にこれに従います。

開発

# Watch mode (auto-rebuild on file changes)
npm run dev

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

# Run the MCP server directly
npm start

MCP サーバーのテスト

AI アシスタントに統合せずに MCP サーバーをテストするには、次の手順に従います。

1. プロジェクトをビルドします：npm run build
2. サーバーを実行します：npm start
3. サーバーは stdio（標準入出力）経由で通信します
4. stdin 経由で MCP プロトコルメッセージを送信し、ツールの機能をテストできます

開発のヒント

• 開発中に自動で再ビルドするには npm run dev を使用します
• サーバーのログは stderr で確認してください（stdout は MCP プロトコル用です）
• テストを行う前に Kawa Code が起動していることを確認してください

アーキテクチャ

Claude Code / Cursor AI
    ↓ MCP Protocol (stdio)
kawa.mcp (this server)
    ↓ Huginn IPC (Unix socket / Named pipe)
Kawa Code Desktop App
    └─ HTTP Client
        ↓ REST + SSE
    Kawa API (cloud)
        └─ Team sync & zero-knowledge encryption

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md と CLA.md をお読みください。

ライセンス

このプロジェクトのソースコードは、Kawa Code Source Available License のもとで公開されています。

個人利用または社内利用の範囲で、ソフトウェアを実行および変更できます。

詳しくは、LICENSEをご覧ください。