klypix-mcp 1.53.0 → 1.54.0

package/README.md

@@ -193,6 +193,27 @@ excludes the owning IDE/chat application's RAM, redacts command-line secrets, an
 brain or terminates a process. Multiple processes under one host are reported as parallel sessions,
 not called duplicates without an authoritative logical-session receipt.
 
+### Project Map: current structure beside project understanding
+
+If the project contains a compatible NetworkX node-link `graph.json`, agents can ask for bounded
+code-structure evidence and current brain context in one read-only call:
+
+```jsonc
+project_map_context {
+  "question": "what owns refresh-token rotation?",
+  "graph_path": "graphify-out/graph.json"
+}
+```
+
+Use `compare_to` with another project-relative graph artifact to add exact total node/edge deltas
+and additions/removals from the two bounded query neighborhoods. Both paths are confined to the
+declared project root; unsafe source paths are withheld; large or unsupported artifacts are
+rejected. The tool never writes graph facts into `brain.klypix`.
+
+Graphify is the first compatible producer. KLYPIX reads artifacts that users generate separately;
+it does not bundle, install, or run Graphify and does not imply a partnership. A compatible generic
+`graph.json` works through the same provider-neutral boundary.
+
 ---
 
 ## Supported hosts and their integration level

package/bin/klypix-worker.mjs

@@ -30,7 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
-import { projectGraphContextMarkdown, queryProjectGraph } from '../src/project-graph.mjs';
+import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import {
@@ -256,12 +256,13 @@ server.registerTool('project_map_context', {
     question: z.string().min(1).describe('Question or code concept to ground in both current structure and project memory.'),
     project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
     graph_path: z.string().optional().describe('Optional project-relative graph JSON path. Defaults to graphify-out/graph.json and may not escape the project root.'),
+    compare_to: z.string().optional().describe('Optional project-relative prior graph JSON path. Adds exact total deltas plus bounded query-neighborhood changes; it may not escape the project root.'),
     depth: z.number().optional().describe('Relationship hops around the best code matches (0-3, default 1).'),
     max_nodes: z.number().optional().describe('Maximum code nodes returned (default 60, capped 200).'),
     k: z.number().optional().describe('Maximum brain cards returned (default 8; fast mode caps 8, deep history caps 20).'),
     deep_history: z.boolean().optional().describe('false (default) uses the sub-second lexical-fast correction-aware path; true opts into whole-brain semantic/history retrieval, which may cold-load the local model.'),
   },
-}, async ({ question, project, graph_path, depth, max_nodes, k, deep_history }) => {
+}, async ({ question, project, graph_path, compare_to, depth, max_nodes, k, deep_history }) => {
   let graphResult;
   let graphMarkdown;
   try {
@@ -272,9 +273,19 @@ server.registerTool('project_map_context', {
       depth,
       maxNodes: max_nodes,
     });
+    if (compare_to) {
+      const previousGraphResult = queryProjectGraph({
+        project: project || mcpPresence.vault,
+        graphPath: compare_to,
+        query: question,
+        depth,
+        maxNodes: max_nodes,
+      });
+      graphResult.change = compareProjectGraphResults(graphResult, previousGraphResult);
+    }
     graphMarkdown = projectGraphContextMarkdown(graphResult);
   } catch (error) {
-    graphResult = { schemaVersion: 1, status: 'invalid', error: error?.message || String(error) };
+    graphResult = { schemaVersion: 2, status: 'invalid', error: error?.message || String(error) };
     graphMarkdown = `# Project Map\n\nThe generated graph could not be read safely: ${graphResult.error}`;
   }
   const graphFiles = Array.isArray(graphResult?.nodes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",

package/src/project-graph.mjs

@@ -7,7 +7,7 @@
 import fs from 'fs';
 import path from 'path';
 
-export const PROJECT_GRAPH_SCHEMA_VERSION = 1;
+export const PROJECT_GRAPH_SCHEMA_VERSION = 2;
 export const DEFAULT_PROJECT_GRAPH = 'graphify-out/graph.json';
 export const DEFAULT_PROJECT_GRAPH_HTML = 'graphify-out/graph.html';
 export const DEFAULT_PROJECT_GRAPH_REPORT = 'graphify-out/GRAPH_REPORT.md';
@@ -148,6 +148,11 @@ function normalizeGraph(raw, projectRoot, artifact) {
   return {
     schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
     provider: 'graphify',
+    format: {
+      family: 'networkx-node-link',
+      sourceSchemaVersion: shortString(raw.schema_version ?? raw.schemaVersion, 80) || null,
+      providerVersion: shortString(raw?.metadata?.version ?? raw?.meta?.version ?? raw.generator_version, 80) || null,
+    },
     artifact,
     nodes,
     edges,
@@ -294,6 +299,7 @@ export function queryProjectGraph({ project, graphPath, query = '', depth = 1, m
   return {
     schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
     provider: graph.provider,
+    format: graph.format,
     status: 'ready',
     query: String(query || ''),
     depth: hopLimit,
@@ -311,23 +317,52 @@ export function queryProjectGraph({ project, graphPath, query = '', depth = 1, m
   };
 }
 
+function edgeIdentity(edge) {
+  return `${edge.source}\u0000${edge.relation}\u0000${edge.target}\u0000${edge.confidence}`;
+}
+
+/**
+ * Compare two already-bounded query results. Artifact totals are exact; named
+ * node/edge changes describe only the returned neighborhoods and say so.
+ */
+export function compareProjectGraphResults(current, previous) {
+  if (!current || !previous || current.status !== 'ready' || previous.status !== 'ready') return null;
+  const oldNodes = new Map(previous.nodes.map(node => [node.id, node]));
+  const newNodes = new Map(current.nodes.map(node => [node.id, node]));
+  const oldEdges = new Map(previous.edges.map(edge => [edgeIdentity(edge), edge]));
+  const newEdges = new Map(current.edges.map(edge => [edgeIdentity(edge), edge]));
+  return {
+    graphNodesDelta: current.counts.graphNodes - previous.counts.graphNodes,
+    graphEdgesDelta: current.counts.graphEdges - previous.counts.graphEdges,
+    addedNodes: current.nodes.filter(node => !oldNodes.has(node.id)).slice(0, 80),
+    removedNodes: previous.nodes.filter(node => !newNodes.has(node.id)).slice(0, 80),
+    addedEdges: current.edges.filter(edge => !oldEdges.has(edgeIdentity(edge))).slice(0, 160),
+    removedEdges: previous.edges.filter(edge => !newEdges.has(edgeIdentity(edge))).slice(0, 160),
+    coverage: 'bounded-query-neighborhoods',
+    comparedArtifact: previous.artifact?.graphJson || null,
+  };
+}
+
 export function projectGraphContextMarkdown(result) {
   if (result.status === 'missing') {
     return `# Project Map\n\nNo supported project graph was found at \`${result.artifact.graphJson}\`. KLYPIX did not install or run a provider. Generate the artifact with Graphify, then retry.`;
   }
   const lines = result.nodes.map(node => {
-    const where = node.sourceFile ? ` — \`${node.sourceFile}${node.sourceLocation ? `:${node.sourceLocation}` : ''}\`` : '';
-    return `- **${node.label || node.id}** (${node.kind || 'symbol'})${where} · id \`${node.id}\``;
+    const where = node.sourceFile ? ` in \`${node.sourceFile}${node.sourceLocation ? `:${node.sourceLocation}` : ''}\`` : '';
+    return `- **${node.label || node.id}** (${node.kind || 'symbol'})${where}; id \`${node.id}\``;
   });
   const edgeLines = result.edges.slice(0, 80).map(edge =>
-    `- \`${edge.source}\` —${edge.relation}→ \`${edge.target}\` [${edge.confidence}]`);
+    `- \`${edge.source}\` --${edge.relation}--> \`${edge.target}\` [${edge.confidence}]`);
   const warnings = [];
   if (result.diagnostics?.unsafeSourcePaths) warnings.push(`${result.diagnostics.unsafeSourcePaths} unsafe/out-of-root source path(s) were withheld`);
   if (result.diagnostics?.danglingEdges) warnings.push(`${result.diagnostics.danglingEdges} dangling edge(s) were ignored`);
   return [
-    '# Project Map — code evidence',
-    `Provider artifact: \`${result.artifact.graphJson}\` · ${result.counts.graphNodes.toLocaleString()} nodes · ${result.counts.graphEdges.toLocaleString()} edges · query \`${result.query || '(overview)'}\`.`,
+    '# Project Map: code evidence',
+    `Provider artifact: \`${result.artifact.graphJson}\`; ${result.counts.graphNodes.toLocaleString()} nodes; ${result.counts.graphEdges.toLocaleString()} edges; query \`${result.query || '(overview)'}\`.`,
     warnings.length ? `Safety note: ${warnings.join('; ')}.` : '',
+    result.change ? `## Change from \`${result.change.comparedArtifact || 'comparison artifact'}\`\nExact total deltas: ${result.change.graphNodesDelta >= 0 ? '+' : ''}${result.change.graphNodesDelta} nodes; ${result.change.graphEdgesDelta >= 0 ? '+' : ''}${result.change.graphEdgesDelta} edges. Named additions and removals are limited to the two bounded query neighborhoods.` : '',
+    result.change?.addedNodes?.length ? `Added in bounded result: ${result.change.addedNodes.slice(0, 20).map(node => `\`${node.label || node.id}\``).join(', ')}.` : '',
+    result.change?.removedNodes?.length ? `Removed from bounded result: ${result.change.removedNodes.slice(0, 20).map(node => `\`${node.label || node.id}\``).join(', ')}.` : '',
     '## Relevant code nodes',
     lines.join('\n') || '_No matching code nodes._',
     edgeLines.length ? '## Relationships\n' + edgeLines.join('\n') : '',