Model Context Protocol Tools

Every tool the once mcpModel Context Protocol server advertises in tools/list, with its input schema and a worked return example.

once_query_workspace#

Return the configured workspace root, root manifest state, graph loading state, and next calls.

Call this first when filesystem tools and the Once server may have different working directories. The result identifies the exact workspace every other Once tool uses, reports the target operating system, architecture, and ordered selection tokens, reports whether the root manifest exists, lists loaded packages and target count, preserves graph loading errors as data, and recommends the next discovery or validation call. The matching command-line operation is once query workspace --format json.

Input schema

Example return

once_query_targets#

List every declared target in the workspace, optionally filtered by target kind.

Returns the same record shape as once query targets --format json: one entry per declared target with its canonical id, package, name, target kind, visibility rules, default dependencies, named dependency roles, and exposed capabilities. The optional kind argument narrows results to one target kind.

Input schema

Example return

once_query_capabilities#

Return the capabilities (build, lint, run, test) a target exposes, with their output groups and required inputs.

Returns the same record once query capabilities <target> --format json emits: the target's id and kind plus one entry per capability with its output groups (what running the capability produces) and required outputs (what it depends on having built).

Input schema

Example return

once_query_schema#

Return the typed contract for a target kind: attributes, dep edges, providers, capabilities, source references, and runnable starters.

Returns the target kind schema (the typed contract a target of that kind must match) as once query schema <kind> --format json would. The record carries the target kind's documentation, attribute list with types and required, configurable, implemented, and allowed-value fields, expected dep providers, emitted providers, exposed capabilities, required tools, external source concepts that can guide partial adoption, and a lightweight list of runnable starter examples. Attributes marked implemented: false are discoverable compatibility fields that validation rejects until their target kind gives them behavior. Use once_materialize_example to create an unchanged starter without loading its contents into model context, or once_query_example when the caller needs to inspect and adapt the files.

Input schema

Example return

once_query_example#

Return the complete file bundle for one target kind starter example.

Returns the same record as once query example <kind> <slug> --format json: the selected example's slug, name, selection hint, and every file a caller can inspect or adapt. Text files use contents; binary files use contents_base64. Example descriptors are discovered through once_list_target_kinds or once_query_schema. For direct setup, prefer once_materialize_example, which writes the bundle without sending large dependency payloads through model context.

Input schema

Example return

once_materialize_example#

Materialize a complete target kind starter directly inside the configured workspace.

This collision-safe setup tool is available only when the server starts with once mcp --allow-run. It copies the selected example without returning its file contents through model context. Existing files with identical contents are kept, making retries idempotent. If any path conflicts, Once reports every conflict and writes nothing. A successful result includes created and unchanged paths, canonical targets, complete-workspace validation, and exact suggested tool calls for targets of the requested kind. The matching command-line operation is once edit materialize-example <kind> <slug> --destination <dir>.

Input schema

Example return

once_list_target_kinds#

List target kinds with their docs, external source references, and example slugs, optionally filtered by ecosystem or intent.

Lightweight discovery entry point. Returns matching target kinds with documentation, external build-system concepts they can partially replace, and bundled starter examples. When the request names one or more ecosystems or runner families, include all of their names in the short query copied from the request. Once combines those specific matches while ignoring generic intent words, which lets a harness discover every native test integration in a mixed repository with one call. Omit the query when the intent is unknown. Call once_query_schema for the full contract of each chosen target kind. The matching command-line operation is once query target-kinds --query <text> --format json.

Input schema

Example return

once_list_native_projects#

List native project declarations and the roots they currently recognize.

Returns each enabled native project's name, documentation, marker files, additional resolver inputs, seed target kind, and current package matches. Detection reads file names only and does not execute native project code. The matching command-line operation is once query native-projects --format json.

Input schema

Example return

once_preview_native_project#

Preview the seed target and complete typed graph derived by one detected native project.

Runs the selected native project's ordinary target-kind resolver without writing a manifest, then returns its declaration, detection evidence, seed target, and expanded typed targets. Omit package when the native project has one match. Expanded dependency graphs can be very large. For a loaded project, prefer once_query_workspace, filtered once_query_targets, once_query_tests, and once_get_target when the complete graph is not needed. The matching command-line operation is once query native-project <name> [--package <path>] --format json.

Input schema

Example return

once_init_native_project#

Initialize Once from one detected native project.

This state-changing tool is available only when the server starts with once mcp --allow-run. It writes the native project's validated seed target through the manifest editor while preserving unrelated configuration and comments. Repeating an identical initialization is idempotent. A conflicting target with the same name is rejected. The matching command-line operation is once edit init-native-project <name> [--package <path>].

Input schema

Example return

once_query_module_contract#

Return the complete project-module authoring contract, primitives, invariants, capability starters, and normalized result examples.

Use this when no discovered target kind covers an external rule or plugin. The result contains the exact Starlark declaration helpers, schema invariants, implementation context fields, generic host-analysis and action primitives, module registration snippet, maintenance loop, and runnable generic, lint, and test starters with normalized result examples. A coding harness can use it to author and maintain a project-local target kind without waiting for a built-in integration. The matching command-line operation is once query module-contract --format json.

Input schema

Example return

once_fetch_external_source#

Fetch bounded UTF-8 source code, metadata, or documentation from a public HTTPS address.

Fetches an authoritative external rule, plugin, registry record, or build-system reference for a coding harness to inspect before generating a local Once target kind. Only public HTTPS addresses are accepted, redirects are not followed, and response content is bounded to one mebibyte. The result includes the content, media type, digest, byte count, and truncation state. The matching command-line operation is once query external-source <url> --format json.

Input schema

Example return

once_validate_module#

Validate a project-local Starlark module and return its target kind contracts before registration or execution.

Reads one workspace-relative module file, evaluates it with the public Once declarations and generic primitives, and returns either its discovered target kind schemas or a structured repair diagnostic. Use it after a harness writes or updates an external-rule adaptation and before registering targets that depend on it. The matching command-line operation is once query validate-module <path> --format json.

Input schema

Example return

once_get_target#

Return one resolved target with its sources, dependency roles, typed attributes, capabilities, and providers.

Returns the same GraphTarget record once_query_targets emits, scoped to one target id. Includes default dependencies in deps, named roles in dependency_edges, typed attribute values, exposed capabilities, emitted providers, and manifest diagnostics. Use this before editing a target to learn its current shape.

Input schema

Example return

once_query_tests#

List targets that expose Once's generic test capability.

Returns every target with a test capability, including its target kind, dependencies, runner type when the target kind exposes once_test_info, labels, and normalized result path. Use this as the agent test discovery entry point before running or filtering tests.

Input schema

Example return

once_query_affected_tests#

Return test targets likely affected by a set of changed workspace paths.

Maps changed paths to test targets using graph relationships, declared inputs, and package ownership. A test is affected when a changed path belongs to the test target itself or to one of its declared dependencies. Declared source patterns are matched without requiring the changed file to still exist. An otherwise unowned path, including a package manifest, belongs to the nearest package and selects only that package's reverse dependency closure. The root manifest, configured graph modules, and paths outside every known package conservatively select every test. Selection does not depend on a particular test runner.

Input schema

Example return

once_query_test_plan#

Create an immutable test plan without assigning work to runners.

Returns the selection policy, normalized changed paths, unmatched paths, selected tests, and stable execution batches. The plan deliberately contains no local worker, remote provider, or fixed-job assignment, so scheduling can change without changing test identity or invalidating reusable results. Before a target's first complete run, or when its discovery inputs change, the plan intentionally contains one whole-target batch. Run that target once with once_run_tests, inspect once_query_test_manifest, then query the plan again to see automatic file or case batches. Pass target with a test_unit from the manifest to create an exact unit-filtered plan. Planning rejects targets that do not declare exact filtering and units absent from the persisted whole-target manifest. The matching command-line operations are once query test-plan --changed-path <path> --format json and once query test-plan --target <target> --test-unit <unit> --format json.

Input schema

Example return

once_run_tests#

Run test targets by id, or run tests affected by changed workspace paths.

Creates the same immutable plan as once_query_test_plan, then pulls stable batches from a shared local queue. Batches with longer historical uncached durations are queued first, and idle workers dynamically take the next batch. Explicit target or targets produce an exact plan; otherwise changed_paths drive conservative graph selection. With exactly one target, test_unit runs a stable unit returned by once_query_test_manifest when the target kind declares filtering support. jobs caps workers without changing plan or batch identity. Set summary_only for compact normalized totals without case-level records. The result's plan is the work that just executed. Its next_plan is recomputed after complete runs refresh discovery, so use that field to assess file or case batching for the next run. The result also includes actual schedule attempts and normalized test results. Failed tests are returned as normal tool content with success: false rather than a tool protocol error, so agents can inspect failures and iterate. The matching command-line operations are once test --changed-path <path> --jobs <count> --format json and once test <target> --test-unit <unit> --format json.

Input schema

Example return

once_query_test_results#

Read normalized once.test_results.v1 results for a target.

Reads the normalized result file produced by the target's test capability. This is the stable agent-facing interface for pass or fail summaries, case-level failures, attempts, and artifacts. Set summary_only when exact totals are sufficient and a large case array would waste model context. The matching command-line operation is once query test-results <target> --summary-only --format json. Callers do not need to parse a runner's command output.

Input schema

Example return

once_query_test_manifest#

List stable test units discovered in a target's normalized results.

Returns an immutable once.test_manifest.v1 projection of the target's current normalized test results and its target-kind-declared listing and filtering support. When no results exist, the manifest reports whole_target_fallback with no units; run the whole target once to refresh discovery. Unit identifiers can be passed to once_query_test_plan or once_run_tests only when case_filtering is runner_args. The matching command-line operation is once query test-manifest <target> --format json.

Input schema

Example return

once_query_test_attempts#

List persisted test batch attempts and measured durations.

Returns actual schedule attempts recorded by once_run_tests or once test --changed-path. Each record connects a stable plan and batch to its local worker, status, cache state, timestamps, measured duration, and the estimate used for ordering. Use target to inspect one test target and limit to bound history. The matching command-line operation is once query test-attempts --target <target> --limit <count> --format json.

Input schema

Example return

once_query_evidence#

List durable evidence records, optionally filtered by subject.

Returns the same record shape as once query evidence --format json: durable action evidence captured after once exec, once run, once build, once lint, or once test. Declared graph actions include an input fingerprint manifest whose categorized components explain which hashed source, dependency, toolchain, command, environment, or module input changed without exposing raw command or environment values. Other action types omit the optional manifest. Pass subject to filter to one command action, target, or target capability, such as cli or cli:test. The tool returns the newest five matching records by default; set limit from 1 through 100 when more or fewer are useful. The matching command-line option is once query evidence --limit <count>. Evidence is historical provenance, not proof that inputs remain unchanged; run the relevant capability when a current result is required.

Input schema

Example return

once_query_graph_fingerprint#

Compute a deterministic, content-addressed digest of the whole graph.

Returns the same record as once query graph-fingerprint --format json: a single stable digest that folds in every target declaration, the resolved contents of every declared source file, the pinned Mise toolchain (mise.toml and mise.lock when present), and the root workspace manifest. The digest changes whenever any of those inputs change, so two identical checkouts on different machines produce the same digest. components lists the categorized (category, label, digest) triples behind the digest, mirroring per-action input fingerprints, so a caller can see which target, source, toolchain, or manifest input contributed. Categories default to all on; set include_sources, include_toolchain, or include_manifest to false to scope the digest, for example to compare only graph structure across checkouts. The matching command-line operation is once query graph-fingerprint [--no-sources --no-toolchain --no-manifest].

Input schema

Example return

once_validate_script#

Parse and validate an annotated script's cache contract.

Reads a workspace-relative script, validates its shebang and once directives, and returns the parsed runtime, inputs, outputs, dependency scripts, fingerprints, environment names, working directory, remote policy, and output symlink policy. Put singular directives with quoted values directly after the shebang, for example # once input "input.txt" and # once output "output.txt". Plural names, colon syntax, and unquoted paths are invalid. Invalid contracts return { valid: false, diagnostics: [...] }, so callers can repair directive typos before execution. The matching command-line operation is once query script <path>.

Input schema

Example return

once_exec_script#

Execute a validated annotated script through Once's action cache.

Opt-in tool exposed only when the Model Context Protocol server starts with once mcp --allow-run. Validates the script contract before running the same path as once exec --script, materializes declared outputs, and returns captured streams, exit status, action digest, cache hit or miss state, and matching evidence. Invoke it twice with unchanged declared inputs to verify cache reuse.

Input schema

Example return

once_build_target#

Build a target by running its generic build capability.

This tool is available only when the server starts with once mcp --allow-run. It behaves like once build <target> --format json, including dependency traversal, target actions, cache policy, and output groups. Because cache identity follows declared content rather than workspace history, a first build in a new workspace can reuse an equivalent action produced elsewhere. The result includes the exit status, command diagnostics under stderr, and bounded declared action logs under captured_stdout and captured_stderr. A captured field is null when the target did not declare that log. A failed build is returned as normal tool content with success: false so agents can inspect diagnostics.

Input schema

Example return

once_lint_target#

Run a target's lint capability and return normalized findings.

This tool is available only when the server starts with once mcp --allow-run. It behaves like once lint <target> --format json: analyzer output is cached in Static Analysis Results Interchange Format, then projected into the tool-neutral once.lint_results.v1 record. The command reports failure when warning or error findings exist, while still returning the complete finding list for repair. Native analyzer configuration remains authoritative.

Input schema

Example return

once_validate_actions#

Run scripted graph actions in a private validation sandbox.

Runs the same declared action analysis used by the graph, bypasses the action cache, inventories private and real-workspace filesystem changes, and returns structured input and output repairs. The matching command-line operation is once query validate-actions <target> --capability <name>. This tool requires once mcp --allow-run because it executes commands. Successful reads that leave no filesystem evidence remain a documented limitation of symlink-only validation.

Input schema

Example return

once_run_target#

Run a target by executing its generic run capability.

This tool is available only when the server starts with once mcp --allow-run. It behaves like once run <target> --format json, including prerequisite build outputs declared by the target's run capability. Argument interpretation is target-kind-specific, so inspect the target-kind schema before supplying arguments. Set visible to request a visible interface when the target kind supports one. Uncacheable actions run again instead of replaying an action-cache hit. The result includes command diagnostics under stderr and up to 64 kibibytes of each declared stdout.log or stderr.log output under captured_stdout and captured_stderr, so an agent can verify ordinary command output without a separate filesystem read. A captured field is null when the target did not declare that log.

Input schema

Example return

once_start_target#

Start a target in a persisted runtime session and return its session id.

This tool is available only when the server starts with once mcp --allow-run. It starts the target, saves its standard output and standard error under .once/runtime/<session_id>/, and returns immediately with the session record. Use the status, logs, and stop tools to follow the process.

Input schema

Example return

once_runtime_status#

Return the latest persisted status for a runtime session.

Reads .once/runtime/<session_id>/session.json and returns the latest status. Status values include starting, running, stopping, stopped, exited, and failed.

Input schema

Example return

once_runtime_logs#

Read standard output or standard error records for a runtime session.

Reads persisted line-oriented standard output and standard error records from a runtime session. Pass source to restrict the result to stdout or stderr, and pass a previous cursor to read only newer records.

Input schema

Example return

once_stop_runtime#

Request that a runtime session stop.

Requests that the process stop and updates the session status as the request is handled.

Input schema

Example return

once_validate_workspace#

Validate the complete workspace graph before execution.

Loads every manifest and target kind schema, then checks target attributes, target-valued attribute references, duplicate target identifiers, missing dependencies, dependency visibility, dependency provider compatibility, source patterns, and dependency cycles. Returns stable diagnostics with target and attribute scope plus suggested repairs. Call this after materializing a starter or applying edits and before build, run, or test. The matching command-line operation is once query validate-workspace.

Input schema

Example return

once_validate_target#

Validate a proposed [[target]] table against its target kind schema. Returns structured diagnostics instead of prose.

Schema-only validation: checks that the target declares a known target kind, every named dependency role is declared by that kind, every required attribute is present, every declared attribute is known and has the declared type, and the target name is well-formed. The check is local; it does not resolve dependency references or read other manifests. Returns { valid: true } on success or { valid: false, diagnostics: [...] } where each diagnostic carries a stable code, the offending target id, the offending attribute when applicable, and repairs an agent can apply.

Input schema

Example return

once_apply_edit#

Apply a batch of create / update / delete operations to one once.toml atomically.

Reads the manifest at <workspace>/<package>/once.toml and applies the operations only if every operation succeeds. Returns { applied: true, changed: <bool>, path: <manifest path> } on success. changed is false when the requested state already exists, in which case no manifest is written. Returns { applied: false, diagnostics: [...] } with the structured diagnostic shape used by once_validate_target when the edit is invalid. A failed batch leaves the original file unchanged.

Input schema

Example return