> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stacknext.space/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> StackNext documentation is written for developers using StackNext in a Next.js App Router project. Use the getting-started and guides sections to install and operate the product, and the reference section for CLI, configuration, MCP and package surfaces. Version-matched package API reference ships inside each npm package under node_modules/@stacknext/<package>/docs/ and is preferred over this site for installed-version APIs. Diagnostic findings are evidence, not confirmed root causes; regression comparisons are deterministic and report-only. Contributor and repository-maintenance documentation is not part of this site.

# MCP tools

> The twenty read-only tools, five prompts and response metadata the StackNext MCP server exposes to AI coding agents.

The StackNext MCP server is read-only. Every tool is annotated
`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true` and
`openWorldHint: false`. See [MCP server](https://docs.stacknext.space/mcp.md) for setup.

## Tools

| Tool | Arguments | Returns |
| - | - | - |
| `get_project_summary` | none | Project name, connection state, counts, latency summary, recent errors and instrumentation coverage. Start here |
| `list_requests` | `limit`, `offset`, `q`, `method`, `status`, `slow`, `minDurationMs`, `sort` | Request summaries with route, status, duration, span/error/query counts and trace id |
| `get_request` | `traceId` | Compatibility alias for `get_trace`: request summary, full span timeline, errors and database queries |
| `list_traces` | `limit`, `offset`, `q`, `sort` | Trace summaries with root span, duration and counts |
| `get_trace` | `traceId` | Full span tree plus correlated errors, database queries and diagnostic references |
| `list_errors` | `limit`, `offset`, `q`, `route`, `name`, `includeStack` | Errors, fingerprint groups and trace correlation. Stacks are omitted unless `includeStack` is true |
| `get_error` | `errorId` | One error with redacted stack and its correlated trace |
| `list_database_queries` | `limit`, `offset`, `q`, `minDurationMs`, `traceId`, `databaseSystem` | Redacted SQL, duration (nullable), success state and route |
| `find_slow_requests` | `minDurationMs`, `limit` | Slowest requests above the threshold, default 500 ms |
| `stacknext_list_diagnostics` | `limit`, `offset`, `category`, `severity`, `status`, `ruleId`, `route`, `traceId`, `since`, `until`, `q` | Deterministic findings with counts, sample window, notes and limitations |
| `stacknext_get_diagnostic` | `diagnosticId` | One finding with bounded evidence, verification steps, limitations and a related trace |
| `stacknext_list_test_runs` | `limit`, `offset` | Live and saved capture runs with status, sample/correlation counts, command timing and environment |
| `stacknext_get_test_run` | `runId` | One run with scenarios, samples, verified trace/query/error evidence, findings, warnings and limitations |
| `stacknext_list_baselines` | `limit`, `offset` | Immutable baselines with source run, scenario/sample counts and environment |
| `stacknext_get_baseline` | `baselineId` | One baseline with its source run, environment and captured scenarios |
| `stacknext_list_comparisons` | `limit`, `offset` | Deterministic comparison summaries with status, severity, counts and environment compatibility |
| `stacknext_get_comparison` | `comparisonId` | One comparison with per-scenario reasons, metrics, environment differences and limitations |
| `stacknext_list_snapshots` | `limit`, `offset` | Frozen snapshots with source, capture time, sample window, counts, file size and invalid-record count |
| `stacknext_get_snapshot` | `snapshotId` | One snapshot with captured config, limitations and its first traces, errors and database queries |
| `stacknext_get_snapshot_trace` | `snapshotId`, `traceId` | One trace from a snapshot's detached view, without live diagnostics |

## Argument constraints

* `limit` is between 1 and 200 (default 50).
* `minDurationMs` is between 0 and 600,000.
* `status` accepts `2xx`, `3xx`, `4xx`, `5xx` or `none`.
* `sort` accepts `recent`, `oldest` or `slowest`.
* Diagnostic `category` accepts `database`, `http`, `performance`, `errors` or
  `runtime`.
* Diagnostic `severity` accepts `info`, `warning` or `error`.
* Diagnostic `status` accepts `observed`, `possible` or
  `insufficient-evidence`.
* `ruleId` accepts `n-plus-one-queries`, `slow-request`, `slow-span`,
  `repeated-external-http`, `error-fingerprint` or `server-error-response`.
* `since` and `until` are epoch milliseconds.

Regression ids are strict: `run-<16 hex>`, `base-<16 hex>` and `cmp-<16 hex>`.
Snapshot ids are strict: `snap-<16 hex>`. An id that does not match the format is
rejected before storage is read.

Comparison status is `improved`, `regressed`, `unchanged` or `inconclusive`;
severity is `high`, `medium`, `low` or `none`.

## Response metadata

Every successful response adds a top-level `meta` object:

```json theme={null}
{
  "meta": {
    "tool": "list_requests",
    "generatedAt": "2026-11-02T12:00:00.000Z",
    "project": "stacknext-example",
    "timeRange": {
      "firstEventTime": "2026-11-02T11:55:00.000Z",
      "lastEventTime": "2026-11-02T11:59:59.000Z"
    },
    "result": {
      "found": 120,
      "returned": 50,
      "limit": 50,
      "offset": 0,
      "hasMore": true,
      "nextOffset": 50
    },
    "connection": {
      "instrumentation": "connected",
      "instances": 1,
      "lastSeen": "2026-11-02T11:59:59.000Z",
      "sdkVersion": "<installed-version>",
      "collectorVersion": "<installed-version>"
    },
    "completeness": { "complete": true, "reasons": [] },
    "notes": []
  }
}
```

* `result.found` is the total in the retention window; `returned` is this page.
* `connection.instrumentation` is `connected`, `waiting` or `unknown`.
* `completeness.complete` is false for pagination, dropped data, an
  unconnected app, an empty result or missing parent spans. Read
  `completeness.reasons`.
* Detail responses add `meta.identifiers` (`traceId`, `errorId`,
  `diagnosticId`, `runId`, `baselineId`, `comparisonId`, `snapshotId` and/or
  `candidateId`).
* `notes` carries short caveats such as omitted stacks, unmeasured query
  durations, findings that are not confirmed root causes, incomplete regression
  records, or snapshot data that is not live telemetry.

Successful calls also return `structuredContent` and advertise an
`outputSchema` when the client supports structured tool output. Tool text
content remains pretty-printed JSON for compatibility.

The server publishes MCP `instructions` during initialization. Codex reads these
directly; other clients may show or ignore them.

## Coverage in the summary

`get_project_summary` returns the same coverage report as
`GET /api/coverage` and `stacknext coverage --json`, plus a compact summary in
`meta.coverage`:

```json theme={null}
{
  "coverage": {
    "observed": 5,
    "active": 1,
    "configured": 0,
    "notObserved": 4,
    "unsupported": 3,
    "unknown": 1,
    "requestsInSample": 12
  }
}
```

`coverage.sample` gives the retention window and connection state. Each
`coverage.items[]` entry carries a status, evidence count/types, last-seen time
and limitations. There is deliberately no percentage or composite score. See
[instrumentation coverage](https://docs.stacknext.space/instrumentation-coverage.md).

## Diagnostics

`stacknext_list_diagnostics` and `stacknext_get_diagnostic` expose the same
deterministic findings as `stacknext diagnose`, the dashboard and
`GET /api/diagnostics`. The server does not run a second engine and does not
call an AI service.

A list response includes `total`, `counts`, `sample`, `notes`, `limitations`,
`engineVersion` and `ruleSetVersion`. Findings are computed over the current
in-memory retention window, not all history. `total` is the number of matching
findings; `items` is the current page. The default finding cap is 100.

`stacknext_get_diagnostic` returns `{ finding, trace, meta }`. The finding
contains the rule, category, severity, status, route, time window, affected
trace count, fingerprint, bounded evidence, `verification` steps and
`limitations`. The related trace is bounded; use `get_trace` for the complete
span tree when it is truncated.

`get_trace` adds a `diagnostics` array of references (`id`, `ruleId`,
`category`, `severity`, `status`, `title`) without changing the trace shape.
Call `stacknext_get_diagnostic` for evidence. Findings are evidence, not
confirmed root causes, and ids can disappear when telemetry ages out.

## Regression and snapshot semantics

Regression tools expose the same records as `stacknext runs`,
`stacknext baseline` and `stacknext compare`. They cannot capture, save,
compare, remove or edit a record.

* A sample is `verified` only when the collector found the injected trace and a
  server span parented to the injected span id. Incomplete reasons include
  `trace-not-found`, `injected-parent-not-found` and
  `no-request-trace-recorded`.
* Run status is `running`, `completed`, `failed`, `interrupted` or `incomplete`.
* Comparison detail includes `environment.compatible`, differences, per-scenario
  status/severity/reasons/metrics, warnings and limitations.
* Snapshot tools read frozen copies and never replay them. A snapshot carries no
  live diagnostics or coverage.

See [regression testing](https://docs.stacknext.space/regression-testing.md) and [snapshots](https://docs.stacknext.space/guides/snapshots.md).

## Prompts

The server offers five optional prompts. They shape an investigation but do not
add capabilities or execute tools on their own.

| Prompt | Arguments | Use |
| - | - | - |
| `diagnose-error` | `errorId?`, `route?` | Find an error, inspect its stack and follow the correlated trace |
| `investigate-slow-request` | `minDurationMs?`, `route?` | Rank slow requests and break down the slowest trace |
| `inspect-database-activity` | `traceId?`, `minDurationMs?` | Inspect SQL, failures, null durations and trace correlation |
| `investigate-trace` | `traceId` | Inspect one timeline, its errors and queries |
| `diagnose-runtime-issue` | `diagnosticId?`, `traceId?`, `route?` | Start from a finding or trace, verify the evidence and report what remains unproven |

## Related

* [MCP server setup](https://docs.stacknext.space/mcp.md)
* [Agent setup](https://docs.stacknext.space/ai-agents/setup.md)
* [Agent workflows](https://docs.stacknext.space/ai-agents/workflows.md)
* [Privacy](https://docs.stacknext.space/privacy.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.