# Using Kerno MCP ### Start your local environment **Tool:** `kerno_start_environment` This kicks off a **background job** that prepares Docker-style configuration for **one** application in your project and brings the dependent services up (databases, caches, the service itself, and whatever else Kerno infers). It returns immediately with a job id and a log location; the work itself often takes **several minutes** and can run longer than a single chat round-trip, so your assistant should check progress using the job tool rather than expecting an instant “done.” #### Example prompts You can ask in plain language; the assistant should map that to the right tool calls (including listing applications first if needed). * *“Use Kerno to start the local environment for our main API. List applications if you’re not sure which one, then start the environment for the backend service that serves HTTP.”* * *“Spin up Kerno’s Docker stack for the `payments` service module in this workspace and tell me when it’s healthy or if something failed.”* * *“I need a full local backend for development—use Kerno start environment on the supported app that matches our Node API (not the worker-only package).”* #### What “application” means and how to choose one Kerno **scans your repository** and splits what it finds into **applications**: units it can treat as a service boundary (typically something that exposes HTTP or is the “main” backend you run locally). You will see: * **Supported** applications — Kerno can generate and run a local stack for these. * **Unsupported** entries — Kerno explains why (for example not yet compatible); you cannot drive `kerno_start_environment` for those in the same way. Each supported application has an **id** and a **name**. For `kerno_start_environment` you must pass **one** of them as **`app`**: * Use the **name** when it clearly matches what you mean (“api”, “backend”, a package folder name). * Use the **id** when two modules look similar or when listing endpoints or tests complains about ambiguity—**id** is the stable, unambiguous choice. If you are unsure, ask your assistant to run **`kerno_get_applications`** first and pick the supported row that matches the service you want running locally. **Tip:** Only **one** start-environment job runs per workspace + application at a time. Wait for that job to finish before asking to bring the same stack up again or to use other compose actions for that app. *** ### List applications and HTTP routes **`kerno_get_applications`** — Run this early. It analyzes the workspace and returns the application list, a workspace identifier, and a suggested next step. **`kerno_list_endpoints`** — After you know your applications, this lists **HTTP routes** Kerno discovered (grouped by where they are implemented in code). It also shows which routes already have **saved scenario tests**. You must pass a **scope** (see below); use **all** when you want every route for the apps you care about. Use the **same scope** here as you plan for baseline capture or validation so you see exactly the routes that will be included. *** ### Baseline tests (capture behaviour) **Tool:** `kerno_capture_baseline` Use this when you want Kerno to **create or refresh** integration-style HTTP tests and store **baselines** (reference behaviour) for endpoints. It runs as a **long background job** and should only be used once the local environment for the relevant application is **up and healthy**. #### Scopes — what you can ask for The **scope** tells Kerno **how much of the API** to cover in this run. Pick the smallest scope that matches your goal:
ScopeWhat it means for you
allCover every HTTP endpoint Kerno has analyzed (optionally limited to one application if you pass app). Use when onboarding a service or establishing baselines across the whole API.
file: your/path/to/handler.tsOnly endpoints implemented in that source file (path is relative to the project root, in the same form Kerno shows when listing endpoints). Use when you changed one handler file and want tests only for that area.
endpoint: METHOD pathA single route, for example endpoint:POST /api/orders. Use for a tight loop on one API change.
If Kerno reports that the target is **ambiguous** (the same route exists in more than one module), pass **`app`** using the application **id** from `kerno_get_applications`. Optional **`user_message`** lets you add plain-language hints (for example “focus on error responses for invalid payloads”) that flow into Kerno’s planning step. **Practical flow:** After code or API changes, prefer **validation** first; if tests are missing or hopelessly out of date, run **baseline capture** again with the same scope rather than manually editing generated test files. *** ### Validation (re-run tests against the running stack) **Tool:** `kerno_validate` This **runs existing** HTTP scenario tests against your **live** local stack and checks them against saved baselines when they exist. It is the right tool right after you change handlers or response shapes. Scopes overlap with baseline capture, with one extra option:
ScopeWhat it means for you
allRun scenarios for every analyzed endpoint (optionally one app).
changedOnly endpoints touched by your current git changes (compared to the last commit). Ideal for “did my PR break anything?” without running the entire suite.
file: pathOnly endpoints tied to that source file.
endpoint: METHOD pathOnly that route.
If listing endpoints shows **no tests** for routes in scope, run **`kerno_capture_baseline`** for that scope first (with the environment healthy). *** ### Following background jobs **Tool:** `kerno_job` Long operations (`kerno_start_environment`, `kerno_capture_baseline`, `kerno_validate`) return a **job id**. Use `kerno_job` to see status, read progress, and learn when the job **succeeded or failed**. Chat clients often limit how long a single tool call can wait; your assistant may need to check the job a few times or follow the log path Kerno provides, rather than blocking on one call until completion. When a job finishes, treat that job id as **done**—do not reuse it for further checks. *** ### Other Kerno tools (overview) | Tool | In brief | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kerno_healthcheck` | Confirms prerequisites (for example Docker and authentication) before heavier steps. | | `kerno_compose_up` / `kerno_compose_down` | Start or stop an already-generated stack for one application—typically after a successful start-environment job, unless your team uses a different runbook. | | `kerno_environments_status` | See status across applications without starting anything. | | `kerno_compose_status` / `kerno_compose_logs` | Inspect one application’s compose state or service logs. | | `kerno_approve` / `kerno_reject` | Optional workflow step to record that you accept or reject validation results (for example in a review checklist). | *** ### Code search and navigation Kerno also exposes tools to **explore the codebase** structurally: discover modules, see where libraries and symbols are used, jump from a line in a file to its definition or references, and walk **downstream** call chains from a selected piece of code. Typical flow at a high level: 1. **Scan the workspace** to list code modules and their roots. 2. **Index a module** you care about (first run can take time; later runs reuse the index). 3. Use **heatmaps** to see where **dependencies** and **specific symbols** concentrate across folders. 4. **Find usages**, **find definition**, **find references**, and **call hierarchy** to narrow down impact and navigate like in an IDE. Use the **exact symbol names** your assistant receives from the heatmap tools when searching for usages—approximate names usually will not match. *** ### Summary * Start with **`kerno_get_applications`** to understand **applications**, then **`kerno_start_environment`** with a clear **`app`** choice to bring one service stack online. * Use **`kerno_list_endpoints`** with an explicit **scope** to see routes and existing tests. * **`kerno_capture_baseline`** defines **what to cover** via **scope** (whole API, one file, or one endpoint). * **`kerno_validate`** re-runs tests; **changed** scope fits day-to-day edits. * Use **`kerno_job`** to track long-running work; use **code search** tools for navigation and impact exploration beyond HTTP tests. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://kerno.gitbook.io/docs/user-manual/using-kerno-mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.