@agent-inspect/mcp-server 6.13.0 → 6.14.1

package/README.md

@@ -1,64 +1,73 @@
 # @agent-inspect/mcp-server
 
-Read-only MCP server exposing local trace listings (no tool invocation, no mutation).
+Read-only MCP server for the **local coding-agent debug loop**: list runs, summarize failures, inspect trees, evaluate contracts, and fetch **TraceFacts** (`get_trace_facts`) — without invoking agent tools or mutating traces.
 
 
 **Support level:** Preview — see [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md).
 
 ## When to use
 
-- Let MCP-compatible clients **read** trace metadata from disk
-- Local dev assistants that browse `.agent-inspect/`
+- Let Cursor, Claude Code, Codex, Gemini, or other MCP clients inspect local `.agent-inspect/` evidence
+- Debug failed trajectories with the same TraceFacts used by CLI checks
 
 ## When not to use
 
-- Invoking agent tools through MCP
-- Uploading traces to a remote MCP host
+- Invoking target-app tools through MCP
+- Uploading traces to a remote MCP host / collector
+- Expecting the server to edit application code
 
 ## Install
 
 ```bash
 npm install @agent-inspect/mcp-server
+# optional helper:
+npx agent-inspect mcp configure --client cursor
 ```
 
 ## Example
 
 ```bash
 npx @agent-inspect/mcp-server --dir .agent-inspect
-# or after install:
-# npx agent-inspect-mcp-server --dir .agent-inspect
 ```
 
+## Flagship tools (read-only)
+
+| Tool | Role |
+|------|------|
+| `list_recent_runs` / `list_recent_failures` | Browse local runs |
+| `get_run_summary` / `get_execution_tree` | Bounded summaries |
+| `get_first_causal_failure` | Deterministic first causal failure |
+| `get_contract_failures` | TraceContract / check failures |
+| `get_trace_facts` | TraceFacts / semantic parity summary |
+| `compare_runs` | Structural diff |
+| `create_share_checked_evidence` | Share-gated Evidence package |
+
+Results are redacted (share profile by default), bounded, and deterministic for the same inputs.
+
 ## Privacy
 
 - Reads local trace directory only
 - Tool results go through a share-profile redaction / size boundary
 - Exposes configured local evidence to the **connected MCP client** — treat that client as a trust boundary
-- No trace mutation; no agent tool invocation
+- No trace mutation; no agent tool invocation; no default upload
 
 ## Limitations
 
 - Preview surface — tool catalog and bounds may evolve
 - Not a gateway or remote upload service
-
-## API
-
-CLI entry: read-only resources for trace listing/search.
-
-## CLI
-
-Prefer `agent-inspect list` / `view` for humans; MCP server for tool integrations.
+- Not a substitute for hosted APM
 
 ## Docs
 
-- [Root README](https://github.com/rajudandigam/agent-inspect#readme)
+- [CODING-AGENT-LOOP.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
+- [TRACE-FACTS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-FACTS.md)
+- [NO-EGRESS-POLICY.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md)
 
 ## Troubleshooting
 
 - **Empty resources:** Confirm `--dir` points at JSONL traces
 - **Security:** Do not expose server beyond localhost without redaction review
 
-
 ## Version
 
 Part of the fixed AgentInspect release line. See the npm badge / package manifest for the current version.

package/dist/{chunk-TLE64A3T.mjs → chunk-C6EBJS57.mjs}

@@ -2096,6 +2096,7 @@ function buildEvidenceManifest(parts) {
       verificationPolicy: parts.verificationPolicy ?? parts.redactionProfile
     },
     assessment,
+    ...parts.semantics !== void 0 ? { semantics: { ...parts.semantics } } : {},
     files: buildEvidenceFileEntries(parts.files)
   };
 }
@@ -2849,6 +2850,38 @@ function summarizeSemanticParity(events) {
     diagnostics: projection.diagnostics
   };
 }
+function buildTraceFacts(events) {
+  const projection = projectLogicalEvents(events);
+  const toolsByName = /* @__PURE__ */ new Map();
+  const llmEvents = [];
+  const outcomeEvents = [];
+  for (const event of projection.logicalEvents) {
+    if (event.kind === "TOOL" && event.status !== "running") {
+      const name = resolveCanonicalToolName(event);
+      const list = toolsByName.get(name) ?? [];
+      list.push(event);
+      toolsByName.set(name, list);
+    }
+    if (event.kind === "LLM" && event.status !== "running") {
+      llmEvents.push(event);
+    }
+    if (event.kind === "OUTCOME") {
+      outcomeEvents.push(event);
+    }
+  }
+  for (const [name, list] of [...toolsByName.entries()]) {
+    toolsByName.set(name, Object.freeze([...list]));
+  }
+  return {
+    rawEvents: Object.freeze([...events]),
+    logicalEvents: projection.logicalEvents,
+    diagnostics: projection.diagnostics,
+    toolsByName,
+    llmEvents: Object.freeze(llmEvents),
+    outcomeEvents: Object.freeze(outcomeEvents),
+    summary: summarizeSemanticParity(events)
+  };
+}
 
 // packages/core/src/checks/index.ts
 var SEVERITY_RANK = {
@@ -6921,6 +6954,11 @@ var FLAGSHIP_TOOLS = [
     name: "get_adapter_diagnostics",
     description: "Bounded adapter/source diagnostics for one run.",
     inputSchema: RUN_ID_SCHEMA
+  },
+  {
+    name: "get_trace_facts",
+    description: "Bounded TraceFacts summary for one run (logical projection counts and finished tool names; no raw prompts).",
+    inputSchema: RUN_ID_SCHEMA
   }
 ];
 var LEGACY_TOOLS = [
@@ -7093,6 +7131,23 @@ async function callReadOnlyTool(context, name, args = {}) {
       context
     );
   }
+  if (name === "get_trace_facts") {
+    const runId = String(args.runId ?? "");
+    const { read } = await openRunTrace(context, runId);
+    const facts = buildTraceFacts(read.events);
+    return deliverMcpPayload(
+      {
+        runId,
+        projectionVersion: "logical-lifecycle-0.1",
+        summary: facts.summary,
+        toolNames: [...facts.toolsByName.keys()].sort((a, b) => a.localeCompare(b)),
+        llmCount: facts.llmEvents.length,
+        outcomeCount: facts.outcomeEvents.length,
+        note: "Bounded TraceFacts summary only; raw events and prompts are not included."
+      },
+      context
+    );
+  }
   if (name === "get_first_causal_failure") {
     const runId = String(args.runId ?? "");
     const { read } = await openRunTrace(context, runId);
@@ -7531,5 +7586,5 @@ async function runReadOnlyMcpServer(options = {}) {
 }
 
 export { MCP_MAX_REQUEST_BYTES, MCP_PROTOCOL_VERSION, READ_ONLY_TOOLS, callReadOnlyTool, createMcpServerContext, handleMcpProtocolLine, runReadOnlyMcpServer };
-//# sourceMappingURL=chunk-TLE64A3T.mjs.map
-//# sourceMappingURL=chunk-TLE64A3T.mjs.map
+//# sourceMappingURL=chunk-C6EBJS57.mjs.map
+//# sourceMappingURL=chunk-C6EBJS57.mjs.map