@neat.is/mcp 0.4.11 → 0.4.13

package/dist/index.js

@@ -4,7 +4,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { CheckPoliciesScopeSchema, HypotheticalActionSchema } from "@neat.is/types";
+import {
+  CheckPoliciesScopeSchema,
+  DivergenceTypeSchema,
+  HypotheticalActionSchema
+} from "@neat.is/types";
 
 // src/client.ts
 function createHttpClient(baseUrl2, bearerToken) {
@@ -250,9 +254,6 @@ function registerResources(server2, client2, options = {}) {
   };
 }
 
-// src/index.ts
-import { DivergenceTypeSchema } from "@neat.is/types";
-
 // src/tools.ts
 import { Provenance } from "@neat.is/types";
 
@@ -717,6 +718,154 @@ async function postJson(client2, path, body) {
   }
   return c.post(path, body);
 }
+async function neatListUninstrumented(client2, input) {
+  try {
+    const result = await client2.get(
+      projectPath(input.project, "/extend/list-uninstrumented")
+    );
+    const libs = result.libraries;
+    if (libs.length === 0) {
+      return formatEmptyResponse(
+        "All detected libraries are covered by the auto-instrumentations bundle or the HTTP fallback. No extension needed."
+      );
+    }
+    const blockLines = libs.map((l) => {
+      const pkgBit = l.instrumentation_package ? ` \u2192 ${l.instrumentation_package}@${l.package_version ?? "*"}` : " \u2192 no registry entry";
+      return `  \u2022 ${l.library} [${l.coverage}]${pkgBit}${l.notes ? ` \u2014 ${l.notes}` : ""}`;
+    });
+    return formatToolResponse({
+      summary: `${libs.length} librar${libs.length === 1 ? "y needs" : "ies need"} instrumentation beyond the auto-instrumentations bundle.`,
+      block: blockLines.join("\n")
+    });
+  } catch (err) {
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
+async function neatLookupInstrumentation(client2, input) {
+  const qs = input.installedVersion ? `?library=${encodeURIComponent(input.library)}&version=${encodeURIComponent(input.installedVersion)}` : `?library=${encodeURIComponent(input.library)}`;
+  try {
+    const result = await client2.get(
+      projectPath(input.project, `/extend/lookup${qs}`)
+    );
+    const lines = [
+      `  coverage: ${result.coverage}`,
+      ...result.instrumentation_package ? [`  instrumentation_package: ${result.instrumentation_package}@${result.package_version ?? "*"}`] : [],
+      ...result.registration ? [`  registration: ${result.registration}`] : [],
+      ...result.notes ? [`  notes: ${result.notes}`] : []
+    ];
+    return formatToolResponse({
+      summary: `Registry entry for ${input.library}: coverage is ${result.coverage}.`,
+      block: lines.join("\n")
+    });
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+      return formatEmptyResponse(`${input.library} is not in the instrumentation registry.`);
+    }
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
+async function neatDescribeProjectInstrumentation(client2, input) {
+  try {
+    const state = await client2.get(
+      projectPath(input.project, "/extend/describe")
+    );
+    const lines = [
+      `  hook files:     ${state.hookFiles.length > 0 ? state.hookFiles.join(", ") : "(none \u2014 run neat init first)"}`,
+      `  .env.neat:      ${state.envNeat ? "present" : "absent"}`
+    ];
+    const depEntries = Object.entries(state.installedDeps);
+    if (depEntries.length > 0) {
+      lines.push("  installed OTel deps:");
+      for (const [pkg, ver] of depEntries) {
+        lines.push(`    ${pkg}@${ver}`);
+      }
+    } else {
+      lines.push("  installed OTel deps: (none)");
+    }
+    const ready = state.hookFiles.length > 0;
+    return formatToolResponse({
+      summary: ready ? `Project has ${state.hookFiles.length} instrumentation hook file${state.hookFiles.length === 1 ? "" : "s"} and is ready for neat_apply_extension.` : "Project has no instrumentation hook files. Run neat init before extending.",
+      block: lines.join("\n")
+    });
+  } catch (err) {
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
+async function neatApplyExtension(client2, input) {
+  try {
+    const result = await postJson(
+      client2,
+      projectPath(input.project, "/extend/apply"),
+      {
+        library: input.library,
+        instrumentation_package: input.instrumentation_package,
+        version: input.version,
+        registration_snippet: input.registration_snippet
+      }
+    );
+    if (result.alreadyApplied) {
+      return formatEmptyResponse(
+        `${input.library} instrumentation is already applied \u2014 no changes made.`
+      );
+    }
+    const lines = [
+      `  files touched: ${result.filesTouched.join(", ") || "(none)"}`,
+      `  deps added:    ${result.depsAdded.join(", ") || "(none)"}`,
+      `  install:       ${result.installOutput}`
+    ];
+    return formatToolResponse({
+      summary: `Applied ${input.instrumentation_package} for ${input.library}. ${result.filesTouched.length} file${result.filesTouched.length === 1 ? "" : "s"} touched, logged to ~/.neat/extend-log.ndjson.`,
+      block: lines.join("\n")
+    });
+  } catch (err) {
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
+async function neatDryRunExtension(client2, input) {
+  try {
+    const result = await postJson(
+      client2,
+      projectPath(input.project, "/extend/dry-run"),
+      {
+        library: input.library,
+        instrumentation_package: input.instrumentation_package,
+        version: input.version,
+        registration_snippet: input.registration_snippet
+      }
+    );
+    const lines = [
+      `  files that would be touched: ${result.filesTouched.join(", ") || "(none)"}`,
+      `  deps to add:                 ${result.depsToAdd.join(", ") || "(none)"}`,
+      `  hook file patch:             ${result.templatePatch}`
+    ];
+    return formatToolResponse({
+      summary: `Dry run for ${input.library}: ${result.filesTouched.length} file${result.filesTouched.length === 1 ? "" : "s"} would be touched. No changes made.`,
+      block: lines.join("\n")
+    });
+  } catch (err) {
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
+async function neatRollbackExtension(client2, input) {
+  try {
+    const result = await postJson(
+      client2,
+      projectPath(input.project, "/extend/rollback"),
+      { library: input.library }
+    );
+    if (!result.undone) {
+      return formatEmptyResponse(
+        `No prior apply found for ${input.library} \u2014 nothing to roll back.`
+      );
+    }
+    return formatToolResponse({
+      summary: `Rolled back instrumentation for ${input.library}. ${result.message}. Run your package manager install to sync the lockfile.`,
+      block: `  result: ${result.message}`
+    });
+  } catch (err) {
+    return formatErrorResponse(`Error talking to neat-core: ${err.message}`);
+  }
+}
 
 // src/index.ts
 var baseUrl = process.env.NEAT_CORE_URL ?? "http://localhost:8080";
@@ -731,7 +880,8 @@ var server = new McpServer({
   name: "neat",
   version: "0.1.0"
 });
-server.tool(
+var registerTool = (name, description, paramsSchema, cb) => server.tool(name, description, paramsSchema, cb);
+registerTool(
   "get_root_cause",
   "Trace a failing node up its dependency graph to find the underlying cause. Use this when something is breaking and you want to know which upstream component is the actual culprit.",
   {
@@ -741,7 +891,7 @@ server.tool(
   },
   async (input) => getRootCause(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_blast_radius",
   "List every node downstream of the given node \u2014 what would break if this node failed or was redeployed.",
   {
@@ -751,7 +901,7 @@ server.tool(
   },
   async (input) => getBlastRadius(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_dependencies",
   "List the transitive outgoing dependencies of a node, BFS to depth N (default 3, max 10). Each result carries distance, edge type, and provenance \u2014 both static (EXTRACTED) and runtime (OBSERVED). Pass depth=1 for direct-only.",
   {
@@ -761,7 +911,7 @@ server.tool(
   },
   async (input) => getDependencies(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_observed_dependencies",
   "List only the runtime (OBSERVED via OTel) outgoing dependencies of a node. Use this to compare what code SAYS the service depends on vs what production actually does.",
   {
@@ -770,7 +920,7 @@ server.tool(
   },
   async (input) => getObservedDependencies(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_incident_history",
   "Return recent OTel error events recorded against a node, most recent first.",
   {
@@ -780,7 +930,7 @@ server.tool(
   },
   async (input) => getIncidentHistory(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "semantic_search",
   "Search nodes by natural-language query. Uses embedding vectors when an embedder is available (Ollama nomic-embed-text \u2192 in-process MiniLM \u2192 substring fallback) \u2014 phrase the query the way you would describe what you want.",
   {
@@ -789,7 +939,7 @@ server.tool(
   },
   async (input) => semanticSearch(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_graph_diff",
   'Diff a saved graph snapshot against the current live graph. Useful for change reviews and post-incidents \u2014 answers "what changed in the architecture between then and now." Returns added/removed/changed nodes and edges with both snapshot timestamps.',
   {
@@ -800,7 +950,7 @@ server.tool(
   },
   async (input) => getGraphDiff(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_recent_stale_edges",
   "List the most recent OBSERVED \u2192 STALE edge transitions. Use this to spot integrations that have gone quiet \u2014 a CALLS edge that just went stale typically means an upstream stopped calling, not that the link is healthy.",
   {
@@ -810,7 +960,7 @@ server.tool(
   },
   async (input) => getRecentStaleEdges(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "get_divergences",
   "Returns places where what the code declares (EXTRACTED) doesn't match what production observed (OBSERVED). The single most NEAT-shaped query \u2014 the one that justifies the whole graph. Use when the user asks 'is anything weird?' or 'what does production do that the code doesn't?' or 'find me a bug' on an unfamiliar codebase. Returns divergences ranked by confidence \xD7 severity. Prefer this over `get_root_cause` when no specific node is failing.",
   {
@@ -823,7 +973,7 @@ server.tool(
   },
   async (input) => getDivergences(client, { ...input, project: projectFor(input) })
 );
-server.tool(
+registerTool(
   "check_policies",
   "Inspect or dry-run the project's policy.json. Without hypotheticalAction, returns currently-recorded violations. With hypotheticalAction, returns violations that would result if the action were applied. Architectural assertions in five shapes (structural / compatibility / provenance / ownership / blast-radius).",
   {
@@ -840,6 +990,61 @@ server.tool(
     project: projectFor(input)
   })
 );
+registerTool(
+  "neat_list_uninstrumented",
+  "List libraries in the project that need instrumentation beyond the auto-instrumentations bundle. Returns first-party, third-party, and gap libraries that require an explicit instrumentation package.",
+  { project: projectField },
+  async (input) => neatListUninstrumented(client, { project: projectFor(input) })
+);
+registerTool(
+  "neat_lookup_instrumentation",
+  "Look up the registry entry for a specific library. Returns the canonical instrumentation package, version, and registration snippet if one exists.",
+  {
+    library: z.string().describe('npm package name, e.g. "@prisma/client"'),
+    installedVersion: z.string().optional().describe("Installed version for range matching"),
+    project: projectField
+  },
+  async (input) => neatLookupInstrumentation(client, { ...input, project: projectFor(input) })
+);
+registerTool(
+  "neat_describe_project_instrumentation",
+  "Describe the current state of OTel instrumentation in the project: which hook files exist, whether .env.neat is present, which OTel deps are installed.",
+  { project: projectField },
+  async (input) => neatDescribeProjectInstrumentation(client, { project: projectFor(input) })
+);
+registerTool(
+  "neat_apply_extension",
+  "Install an instrumentation package and splice its registration into the existing OTel hook file. Idempotent \u2014 calling twice with the same args is a no-op. Only modifies instrumentation files, package.json, and the lockfile (via the project package manager).",
+  {
+    library: z.string().describe('The library being instrumented, e.g. "@prisma/client"'),
+    instrumentation_package: z.string().describe('The instrumentation npm package, e.g. "@prisma/instrumentation"'),
+    version: z.string().describe('Semver range for the instrumentation package, e.g. "^6.0.0"'),
+    registration_snippet: z.string().describe('The JS/TS snippet to splice into the instrumentations array, e.g. "instrumentations.push(new PrismaInstrumentation())"'),
+    project: projectField
+  },
+  async (input) => neatApplyExtension(client, { ...input, project: projectFor(input) })
+);
+registerTool(
+  "neat_dry_run_extension",
+  "Preview what neat_apply_extension would do without making any changes. Returns the exact file diff, deps to add, and install command.",
+  {
+    library: z.string().describe('The library being instrumented, e.g. "@prisma/client"'),
+    instrumentation_package: z.string().describe('The instrumentation npm package, e.g. "@prisma/instrumentation"'),
+    version: z.string().describe('Semver range for the instrumentation package, e.g. "^6.0.0"'),
+    registration_snippet: z.string().describe("The JS/TS snippet to splice into the instrumentations array"),
+    project: projectField
+  },
+  async (input) => neatDryRunExtension(client, { ...input, project: projectFor(input) })
+);
+registerTool(
+  "neat_rollback_extension",
+  "Undo the last neat_apply_extension for a given library. Removes the dep from package.json and the registration from the hook file. Does not re-run the package manager \u2014 run install manually to sync the lockfile.",
+  {
+    library: z.string().describe("The library whose instrumentation should be rolled back"),
+    project: projectField
+  },
+  async (input) => neatRollbackExtension(client, { ...input, project: projectFor(input) })
+);
 var incidentsPollMs = process.env.NEAT_RESOURCE_POLL_MS ? Number(process.env.NEAT_RESOURCE_POLL_MS) : void 0;
 var resourceRegistration = registerResources(server, client, {
   ...incidentsPollMs !== void 0 ? { incidentsPollMs } : {},