MCP server

kapi exposes its format-aware content engine as an MCP (Model Context Protocol) server — the content layer your AI assistant drives. This lets AI tools like Claude, GitHub Copilot, Cursor, Windsurf, and other MCP-compatible agents parse files, count words, run translation flows, check brand voice, and look up terminology — all through structured tool calls.

For the agent-skills path (Claude Code calling the kapi CLI), see Use the Kapi Agent Skills. The two can be used together.

Quick Start

Start the MCP server:

kapi mcp

This launches a JSON-RPC server on stdio. You don't run it manually — your AI tool starts it as a subprocess.

Setup

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "kapi": {
      "command": "kapi",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. Kapi tools will appear in the tool picker.

Claude Code

Add to your project's .mcp.json file (or create it at the repository root):

{
  "mcpServers": {
    "kapi": {
      "command": "kapi",
      "args": ["mcp"]
    }
  }
}

Claude Code will automatically discover and connect to the kapi MCP server.

VS Code (GitHub Copilot / Copilot Chat)

Add to your VS Code settings (.vscode/settings.json or user settings):

{
  "mcp": {
    "servers": {
      "kapi": {
        "command": "kapi",
        "args": ["mcp"]
      }
    }
  }
}

Or add to .vscode/mcp.json in your project:

{
  "servers": {
    "kapi": {
      "command": "kapi",
      "args": ["mcp"]
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "kapi": {
      "command": "kapi",
      "args": ["mcp"]
    }
  }
}

Windsurf

Add to your Windsurf MCP config (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "kapi": {
      "command": "kapi",
      "args": ["mcp"]
    }
  }
}

tips

If kapi is not in your $PATH, use the full path to the binary (e.g. /usr/local/bin/kapi or $HOME/go/bin/kapi).

Available Tools

Once connected, your AI assistant can call these tools:

Tool	What it does
list_formats	List all supported file formats with extensions and capabilities
detect_format	Detect a file's format from its path
extract_content	Read a file's blocks (id, content_hash, placeholder source_text, word_count) — the read leg
apply_edits	Apply a typed change-set (content + asset edits) — the write leg, no provider
stats	Content metrics per file and in total — blocks, words, characters, segments, by-role
run_flow	Run a processing flow (pseudo-translate, QA check, etc.)
pseudo_translate	Pseudo-translate a file to test translation readiness
list_flows	List available processing flows
list_tools	List available processing tools
brand_guide	Render a brand voice guide from a starter pack or profile YAML
brand_check	Score text against a brand voice profile (rule-based)
brand_rewrite	Rewrite text to fix forbidden/competitor terms
check_file	Verify a file's content against the checkset; returns a kapi.check/v1 Report with per-block locations
check_text	Verify a text snippet against the content checkset; returns a kapi.check/v1 Report
term_lookup	Look up a term in a local terms store
tm_search	Search a local content memory

Example Conversations

"How many words need translating?"

Ask your AI assistant:

How many translatable words are in src/locales/en.json?

The assistant calls stats with the file path and returns a structured answer with word, block, character, and segment counts.

"What formats can you handle?"

What file formats does kapi support?

The assistant calls list_formats and returns a table of formats with their extensions, MIME types, and read/write support.

"Extract the content from this file"

Show me the translatable strings in messages.json

The assistant calls extract_content, parses the file, and returns each translatable block with its ID, content hash, source text (inline codes as <x id="…"/> placeholders), and word count.

"Edit the content, then check it"

Tighten the intro paragraph in report.docx, keeping it on brand

The assistant reads the blocks with extract_content, rewrites the text itself (no second model), sends the change back through apply_edits (the byte-faithful round-trip, drift- and inline-code-guarded), then calls check_file to confirm the gate passes — looping until it does.

"Pseudo-translate for QA testing"

Pseudo-translate src/locales/en.json so I can test for UI truncation

The assistant calls pseudo_translate, generates a pseudo-translated file with expanded characters, and tells you where the output was written.

"Run a QA check"

Run quality checks on my French translation at src/locales/fr.json

The assistant calls run_flow with flow_name: "qa" and returns the output file path.

Tool Reference

extract_content

Parse a file into translatable content blocks — the read leg of the edit loop. Each block carries its id, content_hash (canonical identity / drift anchor), source_text with inline codes rendered as <x id="…"/> placeholders, and word_count. Pair with apply_edits to round-trip an edit faithfully.

Parameter	Type	Required	Description
path	string	yes	File path to parse
format	string	no	Override automatic format detection
source_lang	string	no	Source language (default: en)

apply_edits

Apply a typed change-set — the one write verb. Content edits land through the byte-faithful round-trip (drift-guarded by content_hash, inline-code-guarded); asset edits (term, tm, brand, recipe) are written to their committed source and compiled into the cache. No AI provider is used.

Parameter	Type	Required	Description
changeset	array	yes	Typed entries (kind: content / term / tm / brand / recipe)

run_flow

Execute a processing flow on a file.

Parameter	Type	Required	Description
flow_name	string	yes	Flow name: pseudo-translate, qa, recycle, translate-qa
path	string	yes	Input file path
source_lang	string	no	Source language (default: en)
target_lang	string	yes*	Target language (*optional for pseudo-translate, defaults to qps)
output_path	string	no	Output file path (default: auto-generated as <base>_<lang><ext>)

stats

Per-file and total content metrics — blocks (translatable and not), words, characters (with and without spaces, plus the unique-character inventory), segments when available, and a by-role breakdown. The same JSON kapi stats --json emits.

Parameter	Type	Required	Description
files	array	yes	Paths of the files to summarize
format	string	no	Input format override applied to every file (default: auto-detect)

detect_format

Parameter	Type	Required	Description
path	string	yes	File path to detect

pseudo_translate

Shorthand for run_flow with pseudo-translate.

Parameter	Type	Required	Description
path	string	yes	File path to pseudo-translate
target_lang	string	no	Target language (default: qps)
output_path	string	no	Output path (default: auto-generated)

How It Works

Kapi MCP uses the same infrastructure as the CLI commands — FormatRegistry for format detection, Executor for pipeline orchestration, and the same built-in tools. The MCP server simply exposes these as typed, discoverable tools over the Model Context Protocol stdio transport.

No server process, ports, or authentication needed. Your AI tool launches kapi mcp as a child process, communicates over stdin/stdout, and shuts it down when the session ends.

merknad

LLM-backed tools like translate need API keys and run from the CLI, not over MCP: kapi translate -i file.json --target-lang fr. The brand_check, brand_rewrite, term_lookup, and tm_search tools above are rule-based and need no key.

Related

• Use the Kapi Agent Skills — the agent-skills path.
• kapi CLI overview
• Run command
• Formats