Kawa Code MCP

Team-aware memory for AI coding assistants. Track intent, record decisions, and see when a teammate is editing the same code — in real time, before commit.

@kawacode/mcp is the official Model Context Protocol (MCP) server for Kawa Code. It lets Claude Code, Cursor, and any MCP-compatible AI assistant:

• Remember what you're working on across sessions, branches, and machines — no more re-explaining the architecture every morning.
• Surface team conflicts before they happen — know when a teammate is editing the same file or function in their working copy right now, before either of you commits.
• Capture architectural decisions with their reasoning — future you (and future AI sessions) inherit the team's accumulated context instead of relitigating choices.
• Link commits to intent automatically — every commit gets the why attached, not just the diff.

Prerequisites

Required

• Node.js >= 18.0.0 — runtime for the MCP server
• Kawa Code desktop app running — kawa.mcp is a thin MCP-to-IPC adapter; all git operations, storage, and API communication happen in Kawa Code

Optional (for history inference)

• Anthropic API key — your own Claude API key, passed as a parameter to the inference tools
• GitHub CLI (gh) — enables richer data tiers (PR descriptions, review comments, issue discussions). Without gh, tiers 2 and 4 are skipped automatically

Installation

Add the MCP in your AI configuration, for example on Claude Code:

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

For Cursor AI, install the MCP with npm install -g @kawacode/mcp and add it to ~/.cursor/mcp.json.

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

Note that the MCP will not be automatically updated to future versions in this scenario. To upgrade to a newer release, run npm update -g @kawacode/mcp.

Manual Installation

For the project you want Kawa Code to run on, create a .mcp.json file in your project root (recommended for teams — commit it to git):

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

Usage

The MCP server works together with the Kawa Code application, Kawa Code IDE extensions, and AI code generators such as Cursor AI and Claude Code.

Pre-edit decision check (Claude Code hook)

Optional. When the agent is about to edit code that has prior recorded reasoning attached (an overlapping intent's blocks, or a constraint with the file in relatedFiles), the hook surfaces it before the Edit fires. Recommendation maps to action: silent (proceed), advisory context injected (review), or blocked with stderr message (investigate-upstream).

Wire it as a Claude Code PreToolUse hook in your ~/.claude/settings.json or project .claude/settings.json:

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

Override paths when blocked:

• Persistent (recommended): record a fork decision that supersedes the existing one and retry the Edit.

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

• One-off escape hatch: add force: true to the Edit tool args. The hook acks the surfaced decisions in the session cache and allows the edit. Cache resets when the Kawa Code daemon restarts.

Disable the hook for a session with KAWA_PRE_EDIT_CHECK=off.

Local telemetry (logs)

Every pre-edit check fire (and force-override) appends a JSON line to a daily-rotated file at ~/.kawa-code/logs/pre-edit-decision-check-YYYY-MM-DD.jsonl. Logs are local only — nothing leaves you

... View full README on GitHub