AI Integration

Dokkimi ships with a full MCP server and auto-configures your AI agent on install. No setup required.

MCP server

Dokkimi includes a Model Context Protocol (MCP) server that gives your AI agent direct access to Dokkimi's capabilities as native tool calls. When you install Dokkimi, it automatically registers the MCP server with Claude Code, Cursor, and GitHub Copilot — your agent can validate, run, and debug tests without shelling out to the CLI.

The MCP server exposes these tool groups:

Authoring

Tool	Description
`get_reference`	Look up any section of the Dokkimi spec (item types, assertion operators, config fields). The agent calls this before writing definitions to get the exact field names and constraints.
`validate_file`	Validate a definition or fragment file against the schema. Returns structured errors and warnings.
`list_definitions`	List all runnable definition files in the project.
`list_fragments`	List all shared fragment files.
`resolve_definition`	Resolve a definition file — expand `$ref` references, interpolate `${{VAR}}` variables, and return the fully resolved output.

Running

Tool	Description
`run_tests`	Run test definitions by name, path, or pattern. Returns pass/fail summary with run ID.
`watch_run`	Stream live status updates from an in-progress run.
`stop`	Stop a running test.

Debugging

Tool	Description
`get_run_summary`	Get a high-level summary of the last run — pass/fail counts, timing, container statuses.
`get_failures`	Get detailed failure information — which assertions failed, expected vs actual values.
`get_step_detail`	Drill into a specific test step — the request sent, response received, and each assertion result.
`get_traffic`	Retrieve captured HTTP traffic between services — full request/response bodies, headers, and timing.
`diff_traffic`	Compare traffic between two runs to identify what changed.
`get_console_logs`	Retrieve stdout/stderr logs from any service container.
`get_db_logs`	Retrieve intercepted database queries and their results.
`get_container_status`	Check the status of each container in the namespace (running, healthy, exited, etc.).
`dump_results`	Export the entire run as structured JSON — the same output as `dokkimi dump`.
`diagnose`	Automated diagnosis of a failed run — analyzes logs, traffic, and assertions to suggest likely causes.

Management

Tool	Description
`status`	Check if Dokkimi is running, and list active or recent instances.
`get_run_history`	List past runs with their results.
`doctor`	Diagnose installation issues (Docker, images, config).
`clean`	Remove orphaned containers and networks.
`init`	Scaffold a new `.dokkimi/` project.

What this means in practice

Instead of writing a definition, switching to the terminal, running dokkimi validate, reading the output, going back to the editor, and iterating — your AI agent does this in a single loop:

Calls get_reference to look up the spec for the item type it needs
Writes the definition file
Calls validate_file to check for errors
Calls run_tests to execute the tests
If a test fails, calls get_failures and get_traffic to diagnose
Fixes the issue and re-runs — all without leaving the conversation

Auto-registration

When you install Dokkimi, it automatically configures itself with every supported AI tool:

Tool	What gets configured
Claude Code	MCP server in `~/.claude.json`, context in `~/.claude/CLAUDE.md`
Cursor	MCP server in `~/.cursor/mcp.json`, rules in `~/.cursor/rules/dokkimi.md`
GitHub Copilot	Context in `~/.github/copilot-instructions.md`

The complete Dokkimi specification is written to ~/.dokkimi/dokkimi-instructions.md and referenced from each tool's context. This means your agent knows the full definition format, all assertion operators, and every CLI command — without you pointing it to docs.

Writing tests with AI

Just describe what you want to test. Your AI assistant already has the full Dokkimi spec in context:

# In your AI assistant:
"Write a Dokkimi test definition that tests the checkout flow.
I have an API gateway (port 3000), an order service (port 3001),
and a Postgres database. Mock Stripe for payment processing."

The AI will generate a valid definition file with the correct item types, connection strings, mock configuration, and assertion blocks — no need to tell it where to find the docs.

Debugging with AI

When a test fails, your AI agent can use the MCP tools to diagnose the issue directly:

# The agent calls these MCP tools automatically:
get_failures      → sees which assertions failed and why
get_traffic       → traces the HTTP calls between services
get_console_logs  → checks service logs for errors
get_db_logs       → reviews database queries

# Or exports everything at once:
dump_results      → full structured JSON snapshot of the run

The agent gets the same visibility you'd get from dokkimi inspect — captured HTTP traffic, console logs, assertion results, database queries — but can process it programmatically and suggest fixes.

Tips for AI-assisted workflows

Let the agent validate as it writes. The agent can call validate_file after every edit to catch schema errors before running tests.
Save dumps from CI. Add dokkimi dump --failed -o artifacts/failures.json to your CI failure handler so dump files are always available for debugging.
Include your service code. When debugging, share the relevant endpoint handler code alongside the dump. The dump shows what happened; your code shows why.
Use get_reference liberally. If the agent seems uncertain about field names or operators, telling it to "check the Dokkimi reference" triggers a get_reference call that gives it the exact spec.

← Getting Started Project Structure →