Kawa Code MCP

Install

Config snippet generator goes here (5 client tabs)

README

# kawa.mcp

Reference implementation of the Kawa Code MCP protocol.

## Overview

The Kawa Code MCP server provides the communication layer used by
Kawa Code to record and align development intent between
developers and AI systems.

It enables:

• Persistent AI reasoning context
• Intent tracking during development workflows
• Alignment between human and AI decisions over time

This repository contains the reference implementation of the
Kawa MCP server used by Kawa Code tools.

This MCP server enables AI coding assistants to understand what you're working on and maintain context across sessions. It connects to the Kawa Code desktop application to provide:

- **Intent tracking**: Create and manage development intents with decision history
- **Team collaboration**: See what teammates are working on, detect conflicts
- **Decision recording**: Track architectural decisions and trade-offs with constraint validation
- **Code block assignment**: Associate code changes with intents for better commit history

## Usage

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

## Key Features

- **Context Persistence**: Never lose track of what you were working on across AI sessions
- **Smart Context Retrieval**: Relevance-based context loading - only fetch what's needed for the current task
- **Zero-Knowledge Encryption**: Code blocks encrypted client-side before cloud sync, API cannot decrypt
- **Team Conflict Detection**: Know when teammates are working on the same files/lines
- **Decision Tracking**: Record architectural decisions with constraint validation and conflict detection
- **Commit Integration**: Link all code changes to intent context for better git history
- **Cross-Platform**: Works with Claude Code and Cursor AI via MCP protocol

## Prerequisites

### Required

- **Node.js >= 18.0.0** — runtime for the MCP server
- **[Kawa Code](https://codeawareness.com/product) desktop app running** — kawa.mcp is a thin MCP-to-IPC adapter; all git operations, storage, and API communication happen in Kawa Code
- **Active Kawa Code account** — for cloud sync and team features

### Optional (for history inference)

- **Anthropic API key** — your own Claude API key, passed as a parameter to the inference tools
- **[GitHub CLI (`gh`)](https://cli.github.com/)** — enables richer data tiers (PR descriptions, review comments, issue discussions). Without `gh`, tiers 2 and 4 are skipped automatically

## Installation

```bash
# Clone the repository (if not already cloned)
cd /path/to/kawa.mcp

# Install dependencies
npm install

# Build the TypeScript source
npm run build
```

## Quick Start

1. **Start Kawa Code**: Launch the Kawa Code desktop app and log in
2. **Configure MCP**: Add kawa.mcp to your AI assistant's MCP configuration (see Configuration section)
3. **Restart AI**: Restart Claude Code or Cursor to load the MCP server
4. **Test connection**: The server will try to connect to Kawa Code on startup
5. **Start coding**: Use `check_active_intent` to begin tracking your work

## Setting Up CLAUDE.md

For Claude Code to use the MCP tools effectively, your project needs a `CLAUDE.md` file that tells Claude *when* to call the tools and provides your repository coordinates.

Copy the example template into your project root and fill in the placeholders:

```bash
cp /path/to/kawa.mcp/CLAUDE.md.example /path/to/your-project/CLAUDE.md
```

Or just merge the example with your own content.
See [`CLAUDE.md.example`](./CLAUDE.md.example) for the full template with optional sections for monorepos, code style, and architecture.

## Configuration

### Claude Code

Create a `.mcp.json` file in your project root (recommended for teams — commit it to git):

```json
{
  "mcpServers": {
    "kawa-intents": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/kawa.mcp/build/index.js"]
    }
  }
}
```

Or add it at user level (available across all your projects):

```bash
claude mcp add --transport stdio kawa-intents --scope user -- node /absolute/path/to/kawa.mcp/build/index.js
```

### Cursor AI

Add to your Cursor MCP configuration (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kawa-intents": {
      "command": "node",
      "args": ["/absolute/path/to/kawa.mcp/build/index.js"]
    }
  }
}
```

**Important:** Use absolute paths, not relative paths or `~` shortcuts.

## Available Tools

### Context & Discovery

| Tool                   | Description                             |
|------------------------|-----------------------------------------|
| `get_relevant_context` | Get context relevant to a specific task |

### Intent Management

| Tool                         | Description                                                |
|------------------------------|------------------------------------------------------------|
| `check_active_intent`        | Check if there's an active intent before starting new work |
| `create_and_