AI integration

Drive Kata from an external AI agent (MCP)

Kata runs an MCP server that publishes its smell index, Fowler refactoring catalog, pending-change-set store, and governance / provenance ledger as callable tools. Any MCP-compatible agent — Claude Code, Codex, Cursor, or a custom one — can inspect smells, propose refactors, review the pending changes, and apply them, without touching your source files directly.

Transport

Kata's MCP server uses Streamable HTTP and, by default, binds to http://localhost:7345/mcp. The bind address is localhost only — nothing on the network can reach it; the CLI you configure must run on the same machine.

To change the URL (multiple simultaneous instances, a non-default port), set KATA_MCP_URLS before launching Kata:

set KATA_MCP_URLS=http://localhost:8080/mcp
Kata.App.exe

The in-app MCP host runs inside Kata.App.exe while the diagram is open. There is also a standalone binary, kata-mcp.exe, that hosts the same tools headlessly — useful for CI / batch flows. The standalone host rejects apply_change_set by default; pass --allow-headless-apply to opt in.

Tools Kata publishes

Kata's MCP server publishes ~80 tools grouped into inspection, refactoring proposals, change-set lifecycle, AI assistance, and governance. The full JSON Schema for each is served over the standard MCP list_tools handshake. Below are the tools you'll reach for first.

Inspection

• list_smells — enumerate 💩 badges currently on the diagram, filterable by typeFullName, memberSignature, and categoryName.
• get_smell_context — given a smell id from list_smells, return the target symbol's source verbatim plus enough surrounding context to make a change applyable.

Refactoring proposals — propose_*

Rather than one generic "request refactor" tool, Kata exposes each Fowler intent as its own tool — propose_extract_method, propose_rename, propose_extract_variable, propose_move_method, propose_extract_superclass, and so on, roughly 48 in total. Preconditions are checked server-side, so a proposal on a symbol that doesn't qualify comes back as an error rather than a broken diff.

Every propose_* call writes a pending change set into Kata's change-set store — the change is not applied to disk yet. This gives the agent (and you, in the app) an explicit review step.

Change-set lifecycle

• list_pending_changes — return every pending change set with its id, originating intent, and affected files.
• apply_change_set — apply a pending change set to the working tree and update the diagram incrementally. Passes through Kata's policy / quality-delta gate before writing.
• approve_change_set / discard_change_set — mark or drop a change set without applying, useful for review workflows.

AI assistance

• request_ai_smell_analysis — queue an AI analysis of a smell. Runs through the AI CLI configured in the Kata app (see AI CLI setup) and returns a change-set proposal the caller can then review.

Governance & provenance

• export_governance_report — return a signed report of applied changes suitable for audit.
• verify_provenance — verify the SHA-256 hash chain recorded under .kata/provenance/ against the working tree, so an auditor can confirm no tampering happened between apply and review.

Provenance is on by default. Kata writes one entry per applied change set; .kata/policy.yaml at the solution root controls which change kinds require a human review before apply_change_set succeeds and is hot-reloaded.

Auth

Kata's MCP server accepts local connections only. There is no bearer token because there is no network exposure — anyone able to reach localhost:7345 already has your user session.

Configure a client

Claude Code

Add Kata to Claude Code's MCP config as a Streamable HTTP server pointing at http://localhost:7345/mcp. Claude Code will pick up the ~80 tools through the standard handshake.

Codex CLI

Codex reads a similar MCP block in its config. Same URL, same handshake.

Cursor

In Cursor's settings, add an MCP server at http://localhost:7345/mcp. Cursor's agent will list Kata's tools alongside its own and route deterministic refactor asks through the propose_* family.

Any MCP-compatible tool

Open a Streamable HTTP MCP connection to http://localhost:7345/mcp. Any client that implements the MCP protocol will work — Kata's tool schemas come through list_tools.

Example round-trip

A minimal agent script that finds a Long Function smell, proposes an Extract Method refactor, and applies the resulting change set:

const smells = await mcp.call("list_smells", {
  categoryName: "Design",
});
const target = smells.find(s => s.name === "LongMethod");

await mcp.call("propose_extract_method", {
  typeFullName: target.typeFullName,
  memberSignature: target.memberSignature,
  extractedName: "ExtractedHelper",
});

const pending = await mcp.call("list_pending_changes", {});
const changeSetId = pending[pending.length - 1].id;

await mcp.call("apply_change_set", { changeSetId });

Every step is explicit: propose lands a pending change set, list surfaces it, apply writes it. The agent — or you, in the app — decides.

What crosses the MCP boundary

• The agent sees: the smell list, target symbols by FQN and member signature, requested source snippets (only when it explicitly calls get_smell_context), and pending change sets it created.
• The agent does not see: Kata's internal type index, Preferences, source it did not request, or any change set not from its own session unless it enumerates them.
• Kata never pushes data at the agent — every byte the agent receives is the result of a call it made.

Troubleshooting

Client can't reach Kata

Confirm Kata is running and that the URL matches the bind. The default is http://localhost:7345/mcp; if you set KATA_MCP_URLS, use that value instead.

propose_* returns "intent not applicable"

The intent's preconditions don't hold on the target symbol. Some intents are strict about member kind, hierarchy shape, or visibility — inspect the error message and pick a compatible intent.

apply_change_set is rejected

The change kind requires a human review under .kata/policy.yaml, or you're in the standalone kata-mcp.exe host without --allow-headless-apply. Either open the app to review, or opt in on the host command line.

Next steps

• AI CLI setup → The other half of the loop — Kata driving your CLI.
• Refactoring catalog → Which propose_* intents Kata publishes.
• Code smells → Which categories list_smells will return.
• FAQ → Data privacy and licensing questions.