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-to-IPC 适配器；所有 git 操作、存储和 API 通信都由 Kawa Code 处理

可选（用于历史推断）

• Anthropic API 密钥——你自己的 Claude API 密钥，作为参数传递给推断工具
• GitHub CLI (gh)——启用更丰富的数据层（PR 描述、审查评论、问题讨论）。如果没有 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 hook）

可选。当 Agent 即将编辑附有先前记录理由的代码时（与意图重叠的代码块，或 relatedFiles 中包含该文件的约束），hook 会在 Edit 执行前显示这些理由。建议会映射到相应操作：静默（继续）、注入建议性上下文（审查），或通过 stderr 消息阻止操作（investigate-upstream）。

在你的 ~/.claude/settings.json 或项目的 .claude/settings.json 中，将其配置为 Claude Code 的 PreToolUse hook：

{
  "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。hook 会在会话缓存中确认已显示的决策，并允许编辑。Kawa Code 守护进程重启时，缓存会重置。

使用 KAWA_PRE_EDIT_CHECK=off 可在当前会话中禁用 hook。

本地遥测（日志）

每次触发编辑前检查（以及强制覆盖）都会向按日轮换的文件追加一行 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 欢迎流程设置的 Agent 会自动遵循它。

开发

# 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 服务

若要在未将 MCP 服务集成到 AI 助手的情况下进行测试：

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。