#MCP Server (Agent-Native)
Expose the Krate compiler, the running dev server and the compiled site to AI agents over the Model Context Protocol with krate mcp.
krate mcp starts an MCP (Model Context
Protocol) server that exposes the Krate compiler to AI agents. The agent talks
to the real compiler - routes, AST, diagnostics, content graph - instead of
grepping a filesystem.
The server speaks JSON-RPC 2.0 over stdio and has no external dependencies.
#Setup
Register the server once in your agent/editor config. The working directory (or a trailing path argument) selects the project root.
For clients that support Streamable HTTP instead of stdio:
krate mcp --http --port 7331 --token "$KRATE_MCP_TOKEN"The HTTP endpoint is http://127.0.0.1:<port>/mcp. POST JSON-RPC requests to
it; GET opens an SSE keepalive stream. It binds to localhost by default and
requires the bearer token when one is configured. stdio remains the default.
Add read/index roots for a multi-root workspace with repeatable --root:
krate mcp --root docs=../docs --root ui=../packages/uiThe primary project remains the build and write root; extra roots are available
to search_project, list_files, read_file/read_files, find_references,
and workspace_symbols. Their paths are returned as root:path.
#Claude Desktop / Claude Code
claude_desktop_config.json:
{
"mcpServers": {
"krate": { "command": "krate", "args": ["mcp", "/abs/path/to/site"] }
}
}Omit the path to use the current working directory: "args": ["mcp"].
#Cursor / VS Code / opencode
The shape is the same, under the client's own key:
- Cursor -
.cursor/mcp.json - VS Code -
.vscode/mcp.json(under"servers") - opencode -
opencode.json
{
"mcpServers": {
"krate": { "command": "krate", "args": ["mcp"] }
}
}#Breaking change
edit_ast has been removed. Edit source directly with edit_file,
apply_patch, or batch_edit; use read_page with format: "ast" only for
inspection. Applied edits are transactional and reversible with undo.
#Tools
Krate ships 60 tools. They fall into groups, and each tool has a JSON
input schema, a description written for model tool selection, and bounded output
(limit and cursor on every list).
#Live app (the running krate dev)
| Tool | Description |
|---|---|
dev_server_status |
Is krate dev running (URL, pid, last build ok, pending build and browser errors) |
get_errors |
Build errors with KR codes and file:line:col, browser runtime errors with stacks, and server errors from the dev log; falls back to a fresh build when no dev server is running |
get_logs |
Tail of the dev server log with grep, level and since filters; secrets are redacted |
dev_server |
Start, stop or restart krate dev as a child of the MCP server (dry-run by default; needs dev in allowTasks) |
get_server_action_by_id |
Resolve a server action id to its export, file, line and endpoint |
#Page truth
| Tool | Description |
|---|---|
explain_page |
Render mode and why, layouts, component tier of every module and the rule that decided it, islands, build-time-only modules, and exact JS/CSS bytes (raw and gzip) |
why_hydrated |
Why a page ships JavaScript, with file:line evidence, the import chain to each hydrating module and concrete suggestions |
why_in_bundle |
The import chain from every route that reaches a file or npm package, and whether a server component keeps it out of the browser |
list_islands |
Client components and npm package islands, ranked by how many routes pay for them |
get_page_metadata |
Route, mode, layouts, segment pages, metadata exports and the built <head> with missing SEO basics |
get_rendered_html |
The built HTML of a route (head, body or visible text) in byte-bounded chunks |
render_preview |
Structural preview without a browser: outline, landmarks, links, images without alt, forms, text |
read_page |
A page's source, kind-tagged AST document, or rendered HTML (format selectable) |
list_routes |
Every route with source file, render mode, and dynamic params |
explain |
A route from the compiled site graph: dependencies, dependents, emitted output files |
#Project truth
| Tool | Description |
|---|---|
get_project_metadata |
Package, framework versions, Node, directories, route counts by mode, API routes, actions, middleware, build and dev server state, MCP policy |
get_config |
The resolved config as dotted keys, each tagged with its source (config file, tsconfig, default) |
list_api_routes |
API routes with language, HTTP methods read from exports, params, and Go-over-TypeScript shadowing |
list_middleware |
middleware.ts matchers (test a path with path), plus config redirects, rewrites and headers |
list_actions |
Every "use server" export with its stable id |
list_collections |
Content collections with entry counts, sample slugs and frontmatter schema |
env_check |
Declared vs used environment variables, missing, unused, secret-like KRATE_PUBLIC_ names; names only, never values |
bundle_report |
Output size by type, largest assets, per-route cost, and routes over the checks.budget limits |
compat_check |
Whether an npm package fits Krate, from its metadata and the compatibility docs |
read_content |
Content-collection entries: list a collection or read one entry |
search_docs |
Search Krate's built-in framework docs (ranked, via the docfind engine) |
#Quality and diagnostics
| Tool | Description |
|---|---|
build |
Build the site; returns diagnostics and a per-route summary |
check |
Run the quality gates (a11y/SEO/perf); builds first when needed |
audit_page |
The quality gates filtered by category, severity or route, paginated, with rule ids and hints |
get_diagnostics |
Run build/check and return structured diagnostics with file, range, code, severity, hint and a matching codemod |
explain_diagnostic |
A KR code explained: why it is reported, what to do, and whether apply_safe_fixes repairs it |
typecheck |
tsc --noEmit after generating route types, as structured file:line diagnostics (needs typecheck in allowTasks) |
run_task |
Run an allowlisted task: build, check, test, or typecheck |
upgrade |
Guided 0.4 to 0.5 upgrade: version check, krate fix codemods, script/Dockerfile/CI scan, build errors; dry-run by default |
migrate_nextjs |
Plan a Next.js to Krate migration: files, route inventory, conflicts, manual decisions; writes nothing |
page_check |
Open a route in headless Chromium: console, page errors, failed requests, timing, accessibility tree, screenshot |
browser_eval |
page_check plus an expression evaluated in the page |
#Code intelligence
| Tool | Description |
|---|---|
search_project |
Search project source/content with literal or regex queries, globs, context, and limits |
read_files |
Read several project files in one call with byte caps |
find_references |
Semantic references to a symbol from the incremental workspace index |
workspace_symbols |
Search declarations across the primary and extra workspace roots |
impact |
Show routes affected by a file, or a route's dependencies/dependents |
list_changes / get_history |
Recent MCP transactions for audit and undo |
#Editing
| Tool | Description |
|---|---|
create_page |
Create a page from a template; returns a diff (dry-run by default) |
edit_file |
Edit any project file's source directly (full replace, find+replace, expected hash/mtime); returns a diff |
apply_patch |
Apply a unified diff to one or many files atomically; returns a diff |
batch_edit |
Apply structured create/replace/delete/move operations atomically |
undo |
Undo the most recent transaction (or one by ID) |
format_file |
Format a file with the project's prettier or biome; returns a diff |
apply_fix |
Apply an explicit find/replace repair to a diagnostic finding |
apply_safe_fixes |
Preview or apply conservative codemods, optionally filtered by codes and paths |
list_files |
List project files (skips node_modules/.git/dist), with an optional glob |
read_file |
Read any project file by path (text + language, or a binary marker) |
create_file |
Create a new file (refuses to overwrite; parse-gated); returns a diff |
delete_file |
Delete a file (files only) and warn about remaining importers; preview unless apply |
move_file |
Move/rename a file and update the imports that point at it; preview unless apply |
create_component |
Scaffold a component (client/static/server, optional CSS); returns a diff |
create_content |
Create an entry in a content collection, validated against its schema; returns a diff |
edit_content |
Edit a content entry (full replace, frontmatter rewrite, or find+replace); schema-checked |
Every tool advertises annotations (read-only, additive, destructive) so clients know what to auto-approve and what to flag for confirmation.
#Live app tools
krate dev writes .krate/dev-server.json (its URL and pid) when it starts and
mirrors its console output to .krate/dev.log, one timestamped line per line of
output. The MCP server finds the running dev server through the first file and
reads its build state and recent browser errors from the loopback-only
/__krate/state endpoint, so the answers come from the process you are looking
at, not from a second build.
get_errorsreturns build errors (KR code,file:line:col, hint and the source line), runtime errors reported by open browser tabs (message and a trimmed stack), and server-side errors found in the dev log (render, middleware and API sidecar failures from the last 15 minutes,sinceMinuteschanges the window). Without a running dev server it runs a fresh build and reports build errors only, and says so. Usekindto pick one source.get_logsreads.krate/dev.logwithlines,grep,levelandsince(a duration such as10m, or an RFC 3339 time). Environment secrets and the absolute project path are removed.dev_serverstarts, stops or restartskrate devas a child of the MCP server. It is a dry-run untilapply: true, it needs"dev"inallowTasks(it runs project code), it is off inreadOnlyMode, it refuses to start a second server, and it only stops a server it started itself. The child is stopped when the MCP server exits.dev_server_statussays whether a server is up, its URL, whether the last build passed and how many errors are pending.
A typical loop: dev_server (start) -> edit with edit_file -> get_errors ->
fix -> get_errors clean. Every edit_file is reversible with undo.
#Page tools
explain_page, why_hydrated, why_in_bundle and list_islands read the page
sources with the same import resolution as the bundler (relative imports,
extensions, index files, tsconfig paths aliases) and classify every module's
component tier with the documented priority: decorator, leading directive, file
name, config lists, directories, async, then client. They need no build.
explain_page adds the exact bytes (raw and gzip) of the JS and CSS the built
page loads when the site is built. File sizes of modules are source sizes; the
bundle sizes are the per-asset ones.
why_hydrated separates component hydration from the shared runtime: a page with
no hooks, signals or handlers but a script tag is reported as loading runtime
features only. A client:visible or client:idle directive on a child does not
make the page that writes it hydrate; it defers that child.
get_rendered_html and render_preview read the built documents. They never
start a server, so they are quick and safe on large sites; render_preview gives
the outline, landmarks, links, images without alt text, forms and the opening
text, enough to check what a page says.
#Project tools
get_config flattens the resolved config into dotted keys and tags each with its
source. A value equal to the built-in default is default; one that differs came
from the config file or, for pathAliases, tsconfig. Paths are relative and keys
named like secrets are redacted.
env_check is built so a secret cannot leak: it reads .env* files only for the
variable names, scans source for process.env.X, process.env["X"] and
import.meta.env.X, and reports names with file:line. It flags variables the
code reads but nothing declares, declared variables nothing reads, secret-looking
names with the KRATE_PUBLIC_ prefix (their values are inlined into client
JavaScript), and non-public reads in client-tier code. No value is ever returned,
and a variable set in the shell counts as provided.
list_middleware compiles the matcher with the same rules as the server (a port
of the runtime matcher, lookahead included), so path answers "does this URL run
the middleware?" exactly.
bundle_report needs a build. Budgets come from checks.budget in the config
(KB per route); routes over js or route are listed.
#Quality tools
audit_page is check with filters and pagination. explain_diagnostic reads
the compiler's diagnostic registry, so every KR code in any tool output can be
explained, and it says when apply_safe_fixes can repair the code.
typecheck runs the project's own tsc --noEmit after generating the route
types and returns file, line, col, the TS code and the message; the
diagnostics about tier decorators that Krate removes at compile time are
filtered out. It needs "typecheck" in allowTasks.
upgrade walks the 0.4 to 0.5 checklist against the project: package versions
on one minor, the krate fix codemods (tsconfig baseUrl, lowercase events,
and so on), scripts, Dockerfiles and CI that use krate start, krate dev in a
container, dist/manifest.json or bin/krate, Tailwind v4 and the config
sandbox, and a build to surface errors 0.4 let through. Every step has a status
(ok, action, manual, info) and file:line evidence. With apply: true it
runs the safe codemods as one transaction that undo reverses; edits to scripts,
Dockerfiles and dependencies are listed, never made. Pass build: false to skip
the build step.
migrate_nextjs is the krate migrate nextjs plan as data. It writes nothing;
the apply step stays a CLI command because it backs up and overwrites many files.
#Browser tools
page_check and browser_eval drive the project's own Playwright install:
Krate adds no browser dependency to the binary. They need Node.js, playwright
resolvable from the project, an installed Chromium, and "browser" in
allowTasks. Without Playwright they fail with the exact install commands
(npm i -D playwright && npx playwright install chromium).
The page opens on the running dev server, or, when none is running, on a static
server over the build output (request-time pages need the dev server). Requests
to any other origin are aborted, so an expression cannot send data out of the
machine. The result has console messages, uncaught page errors, failed requests,
4xx/5xx responses, load timing, JS bytes, the number of blocked external
requests, optionally the accessibility tree (aria) and a PNG screenshot as an
image block, and for browser_eval the JSON value of the expression.
#Read tools
list_routes, read_page, read_content, search_docs, build, and check
never write source files.
read_page lets the agent choose what it needs with format (default source):
source- the raw file text, so the agent can read and edit the actual page.ast- the kind-tagged AST document (the same format JS plugins receive), withlossyTypesreporting TypeScript constructs the parser drops.html- the rendered output when the site has been built.all- source, AST, and rendered HTML together.
read_content lists a collection's entries (slug, project path, frontmatter)
when collection alone is given, or returns a single entry's raw file, parsed
frontmatter, and markdown body (plus rendered HTML for .md) when slug is
added.
search_docs searches Krate's own framework documentation - the content
that powers the docs site - which is embedded into the compiler at build time,
so it works the same from any project and offline. It is backed by the
docfind WASM engine running in-process
(the same engine Krate uses for docs search during development builds): results
are ranked, and each hit carries a short excerpt, a slug, and a resource
(krate://docs/{slug}) for reading the whole page.
limitcaps the number of hits (default 8).maxCharssizes theexcerptwindow (default 240); it only affects the excerpt, never the full text.full: trueadds acontentfield with the hit's complete cleaned text (plain text with newlines).
It does not scan the current project's content; use
read_content/krate://content for that.
#Context tools
search_project walks project source and content files, honors the policy and
ignored directories, and returns matches with surrounding context. Use regex
for patterns, glob to scope paths, and context/limit to control payload
size.
read_files is the batch form of read_file, with per-file byte caps.
get_diagnostics runs a build (and optionally check) and returns structured
entries: code, severity, file, line/column, route, message, and hint. It also
includes the build output and whether the build succeeded. A codemods array
lists conservative safe rewrites with their exact location and from/to text.
Pass codes and/or paths to apply_safe_fixes to apply only that subset
(dry-run unless apply: true).
find_references and workspace_symbols share an incremental semantic index.
The index parses TS/JS/TSX/JSX declarations, imports, exports, identifiers, and
JSX component references, so comments and string literals are not reported as
references. Files are re-indexed only when their size or mtime changes.
workspace_symbols returns declaration kind, exported state, root, path, and
location; find_references returns reference/definition/import kinds plus a
definitions list.
impact uses the compiled site graph to report dependent routes for a file or
dependencies and dependents for a route. Both index queries accept a root
filter; multi-root result paths use root:path. The primary build/write root is
unchanged by extra roots.
list_changes and get_history expose recent MCP transactions, including file
lists, timestamps, and undone state.
#File tools
The file tools let the agent discover and manage arbitrary project files (components, styles, assets), not just pages:
list_fileslists project-relative paths (skippingnode_modules,.git,dist, ...). Filter withglob(src/components/**/*.tsx), scope withdir/root, and setincludeDenied: trueto see policy-denied paths. Multi-root paths are returned asroot:path.read_filereturns a file's text with a language hint (or abinarymarker). Sensitive paths are refused (see the policy below). Userootor aroot:pathtarget for extra workspace roots.create_file,delete_file, andmove_fileround out the lifecycle.create_filerefuses to overwrite (useedit_fileto modify) and parse-gates editable source; all three default to a dry-run preview.create_componentscaffolds a component undersrc/components/<kebab-name>/:kindselectsclient(imports the runtime),static, orserver;withCss: trueadds a companion.cssfile. Continue withedit_filefor changes.
#Write tools
create_page, edit_file, apply_patch, batch_edit, create_file,
delete_file, move_file, create_component, create_content,
edit_content, apply_fix, and apply_safe_fixes default to a dry-run that returns a unified diff. Pass
"apply": true to write. This gives the agent (and you) an approval step before
anything changes on disk.
All writes go through one transaction layer: edits are validated before commit,
multi-file operations are rolled back on failure, and applied transactions can
be reversed with undo. apply_patch accepts unified diffs; batch_edit
accepts structured operations; both support per-file expectedSha256 checks.
#Permissions (.krate/mcp.json)
By default the agent may read and write any project file - pages, CSS,
components, API routes, content, docs, and config - except a small set
of sensitive paths - environment files (.env*), private keys (*.pem,
*.key, id_rsa, ...), .git/, npm/pypi/netrc credential files, and the policy
file itself. Those require an explicit allow entry. A committed policy at
.krate/mcp.json customises this:
{
"allow": ["config/public.env"],
"deny": ["src/generated/**"],
"readOnly": ["krate.config.ts"],
"writeRoots": ["src", "public"],
"maxFileBytes": 2097152,
"maxBatchFiles": 50,
"allowBinary": false,
"readOnlyMode": false,
"allowTasks": ["build", "check", "test", "typecheck", "dev", "browser"],
"auditLog": ".krate/mcp-audit.jsonl",
"rateLimit": { "requests": 120, "windowSeconds": 60 },
"allowedHosts": [],
"redact": ["my-literal-private-value"]
}allowoverrides the default-deny list (e.g. permit one checked-in.env.example).denyalways wins, even overallow.readOnlypermits reading but never writing.writeRootslimits writes to these paths. An empty list keeps the legacy project-wide behavior;["src", "public"]is a safer default for most sites.maxFileBytesandmaxBatchFilesbound memory and transaction size.allowBinarypermits binary writes; it is off by default.readOnlyModedisables every write tool,run_task,dev_server,typecheck,page_checkandbrowser_evalfor a shared or remote MCP profile.allowTasksgatesrun_taskand the tools that run project code:devenablesdev_server,typecheckenables thetypechecktool, andbrowserenablespage_checkandbrowser_eval. The default isbuildandcheck. Generated/output trees (node_modules,dist,.krate,build) are never writable.auditLogwrites redacted JSONL tool-call records. It defaults to.krate/mcp-audit.jsonl; set it to"off"to disable audit logging.rateLimitbounds HTTP requests per client address (default 120 per 60 seconds).{ "disabled": true }turns the limiter off.allowedHostslets a reverse proxy expose MCP under a public hostname. Loopback hosts are always accepted; otherHostheaders are rejected.redactlists extra literal values to mask in tool output and audit logs, in addition to environment values with secret-like names.
Every write also rejects absolute paths and traversal outside the project root,
resolving symlinks so a symlinked directory cannot redirect a write elsewhere.
Path rules are applied to a symlink's own name and to the path it resolves to,
so a link named notes.txt that points at .env is as protected as .env. The
default-deny list, deny, readOnly and the generated trees match without regard
to case (.ENV is .env on macOS and Windows); allow and writeRoots match
exactly.
#Remote operations
For a remote deployment, bind a non-loopback interface and always set a bearer token:
krate mcp --http --host 0.0.0.0 --port 7331 --token "$KRATE_MCP_TOKEN"krate mcp refuses unauthenticated binding outside loopback. The HTTP handler
also rejects cross-origin browser requests and unexpected Host headers, so a
DNS-rebinding page cannot drive a local server. Bearer tokens, secret-looking
environment values, sensitive JSON fields, and policy redact literals are
masked in tool output, errors, and audit records.
Hosted health and metrics endpoints are available alongside /mcp:
-
GET /healthz- unauthenticated liveness with uptime and active sessions. -
GET /metrics- bearer-protected Prometheus text: request, authorization, rate-limit, origin-rejection, and active-session counters. -
create_pagescaffolds a page from a template -static(default),content-list,detail, andblank(raw source override). For content-backed templates you can passcollectionand acontentEntryobject so the matching markdown entry is authored alongside the page, andwithLayout: truecreates a missing_layout.tsx. Applying a page also regenerates the generated route/content types. -
apply_patchaccepts a unified diff (---,+++,@@) for one or many files. Context must match exactly, and the whole patch is rolled back if any file fails validation or policy checks. It supports create, modify, delete, and rename operations. -
batch_editaccepts a list of structured operations (create,replace,delete,move). Each operation may includeexpectedSha256; the batch is committed as one transaction. -
undorestores the most recent applied transaction, or a transaction by ID. It refuses if affected files changed afterward unlessforce: true. -
format_fileruns the project's own prettier or biome. Krate has no formatter of its own. It loads project config, so it needs"format"inallowTasks. -
edit_fileedits the actual file. It takes aroute(a page route like/about, or a project-relative path) plus one of two modes:content- replace the entire file (creates the file when it does not exist).find+replace- a targeted in-place edit.findmust match exactly once, or passreplaceAll: true; a missing or ambiguous match returns a helpful error instead of guessing.expectedSha256orexpectedMtimerefuses stale edits.
#Compared with the Next.js MCP server
Next.js 16 serves an MCP endpoint at /_next/mcp from its dev server, and the
next-devtools-mcp package connects an agent to it. The table lists every tool
of both (checked against the
Next.js guide and the
next-devtools-mcp README) and
the Krate tool that covers it.
| Next.js | What it does | Krate |
|---|---|---|
get_errors |
Build, runtime and config errors from the dev server | get_errors (also server-log errors, KR codes and hints) |
get_logs |
Path to the dev log file | get_logs returns the lines, filtered and redacted, instead of a path |
get_page_metadata |
Render contributions of a page open in a browser | get_page_metadata, explain_page (no browser session needed) |
get_project_metadata |
Project path and dev server URL | get_project_metadata (relative paths; versions, routes, build state, policy) |
get_routes |
Routes grouped by router | list_routes, list_api_routes, list_middleware |
get_server_action_by_id |
Action id to file and export | get_server_action_by_id, list_actions |
get_compilation_issues |
Compilation issues for all routes (Turbopack only) | get_diagnostics, build, typecheck (any build) |
compile_route |
Compile one route without a request | build, get_errors (the dev server rebuilds on save) |
get_request_insights |
Request timelines and cache behaviour (experimental) | get_logs for requests and errors; no request recorder yet |
nextjs_index |
Discover running dev servers and their tools | dev_server_status, tools/list |
nextjs_call |
Call a runtime tool on a dev server | Not needed: the tools are first-class |
nextjs_docs |
Points at the docs in node_modules |
search_docs and krate://docs/{slug} run the search and return the text |
browser_eval |
Points at the agent-browser CLI |
browser_eval and page_check run the browser (Playwright) |
init, upgrade_nextjs_16, enable_cache_components (removed in 0.4.0) |
Setup and upgrade prompts, now skills | upgrade, migrate_nextjs, and the upgrade-krate and migrate-from-nextjs prompts |
What Krate adds that Next.js does not offer:
- Edits with a safety net:
edit_file,apply_patch,batch_editand the rest are dry-run by default, policy-checked, transactional and reversible withundo; Next.js has no write tools. - Why, not just what:
explain_page,why_hydrated,why_in_bundleandlist_islandsanswer why a page is dynamic or interactive and which import pulled a package in, withfile:lineevidence, because the compiler owns the tier and hydration rules. - Project truth:
get_configwith sources,env_checkwithout values,bundle_reportagainst budgets,compat_check,list_collections. - Quality and migration:
audit_page,explain_diagnosticfor every KR code,typecheck,upgrade,migrate_nextjs. - A server that works without a running app: most tools answer from sources and the build output; the live tools say when they fall back to a build.
- Policy and audit: every call is rate limited over HTTP, redacted and written
to the audit log, and tools that run project code are opt-in per
allowTasks.
#Prompts
Prompts package recurring workflows so agents reach for the right tools:
add-page- create a page the Krate way: match house style first, thencreate_pagewith the chosen template, and confirm viabuild/check.publish-content- author a new entry into a typed content collection viacreate_content(schema-validated) and wire it into a page.fix-checks- run the quality gates, then fix the worst findings withapply_fixorapply_patch.repair-diagnostics- diagnose build/check failures, apply safe codemods first (apply_safe_fixes, filtered by the diagnostics' codes), then minimal manual repairs, and verify withget_diagnosticsandrun_task.refactor- map references and impact, propose a multi-file diff, then apply it and verify.audit-dependencies- report unused or risky dependencies without changing files.scaffold-component- create a component that matches nearby house style.explore- summarize the project from routes, config, and outstanding checks.debug-running-app- start or find the dev server, readget_errorsandget_logs, explain each KR code, repair, and confirm clean.diagnose-page-explain_page,why_hydrated,why_in_bundleandaudit_pagefor one route, then the smallest changes as a dry-run diff.upgrade-krate- the guided 0.4 to 0.5 upgrade withupgrade, safe codemods first.migrate-from-nextjs- plan withmigrate_nextjs, check packages withcompat_check, verify after the CLI apply.performance-review-bundle_report,list_islandsand per-route explanations, ranked fixes, no edits.
Prompt quality is evaluated in internal/mcp/prompt_eval_test.go. The suite
checks every registered prompt, required arguments, optional defaults, absence
of unresolved placeholders, required tool sequence, and safety constraints such
as dry-run-before-apply and read-only dependency audits. Add a case there
whenever a prompt is added or its workflow changes.
#Protocol
- Structured results: tools that return JSON also include
structuredContent, so clients can consume diagnostics and listings without parsing the text block. - HTTP transport:
krate mcp --httpexposes Streamable HTTP at/mcp(POST requests, GET SSE). Authentication is bearer-token based;/healthzand/metricsprovide liveness and Prometheus observability. - Progress: requests with
_meta.progressTokenreceivenotifications/progressduring build, check, diagnostics, and search. - Pagination:
list_files,search_project,workspace_symbols,list_changes,get_history, and every list from the live-app, page, project and quality tools (get_errors,list_api_routes,list_actions,list_islands,bundle_report,audit_page,get_config, ...) returnnextCursorwhen more results exist. Text-returning tools (get_logs,get_rendered_html) are bounded bylinesandmaxBytesand reporttruncatedornextOffset. - Subscriptions: clients can
resources/subscribeandresources/unsubscribe; write transactions emitnotifications/resources/updatedfor manifest, routes, graph, and content. - Version negotiation:
initializehandlesprotocolVersionnegotiation, supporting2024-11-05through2025-11-25. - Cancellation:
notifications/cancelledaborts a pending request; the server responds with error code-32800(Request Cancelled) when appropriate. Long-runningbuild/checkcalls observe the cancellation context. - Instructions:
initializeincludes agent-facing instructions that describe the tool set, the dry-run convention, and Krate's pages/layout/ content conventions. - Notifications (
notifications/initialized,exit) never produce a response.
#Example session: debugging a running app
dev_server_status- nothing running, sodev_server { action: "start" }(dry-run), then again with"apply": true.get_errors-KR7115insrc/pages/pricing.tsx:12:1;explain_diagnostic { code: "KR7115" }explains the decorator rule.edit_filethe fix (dry-run diff, thenapply), wait for the rebuild, andget_errorsagain:buildOk: true.why_hydrated { route: "/pricing" }shows the page still ships 48 KB of JavaScript because of oneuseState; move it into a small client component andexplain_pageshows the new total.
#Example session: adding a page
An agent asked to add a pricing page can:
list_routes- see existing routes and their source files.read_pageon a similar page (format: "source") - learn component and styling conventions.create_page { route: "/pricing" }- receive a diff.- You approve, then the agent calls it again with
"apply": true. build- surface diagnostics in the same turn.check- fix any accessibility or SEO findings withedit_file.
Because the server holds the compiler in-process, each step is fast and the agent never has to invoke a shell.
For how the server is implemented (no SDK dependency, stdout discipline, path anchoring), see Contributing -> Architecture.
Last updated: 2026-11-17
Contributors: Noinkin