klypix-mcp 1.53.0 → 1.55.0

package/README.md

@@ -193,6 +193,41 @@ 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. When a returned brain card names an exact mapped source path, the structured response
+also includes a review-only evidence-link proposal. It never promotes similarity into truth and
+never writes graph facts or links 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.
+
+For a reproducible map artifact on every pull request and main-branch push, install the shipped
+read-only workflow into a Git checkout:
+
+```bash
+npx klypix-project-map setup-github /path/to/project
+```
+
+The command refuses to overwrite an existing workflow unless `--force` is explicit. The installed
+workflow has `contents: read`, pins every action by commit SHA, pins `graphifyy==0.9.33`, validates
+the graph contract, and uploads `graphify-out/` as a 14-day build artifact. This is opt-in CI code:
+the local MCP tool still never installs or launches Graphify.
+
 ---
 
 ## Supported hosts and their integration level
@@ -398,7 +433,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
 | `brain_connect` | Find and draw related-but-unlinked cards |
-| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context; Graphify artifacts are supported but never installed or run |
+| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; Graphify artifacts are supported but never installed or run locally |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name and content |

package/bin/klypix-project-map.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { discoverProjectGraph } from '../src/project-graph.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const template = path.resolve(here, '..', 'examples', 'github', 'klypix-project-map.yml');
+const args = process.argv.slice(2);
+const command = args[0] || 'status';
+const force = args.includes('--force');
+const rootArg = args.find((value, index) => index > 0 && value !== '--force') || process.cwd();
+
+function projectRoot(value) {
+  const root = fs.realpathSync(path.resolve(value));
+  if (!fs.statSync(root).isDirectory()) throw new Error('Project root is not a directory.');
+  return root;
+}
+
+function usage() {
+  console.log([
+    'KLYPIX Project Map',
+    '',
+    '  klypix-project-map status [project]',
+    '  klypix-project-map setup-github [project] [--force]',
+    '',
+    'setup-github installs a read-only, pinned GitHub Actions workflow. It never installs or runs a provider on your computer.',
+  ].join('\n'));
+}
+
+try {
+  if (command === '--help' || command === '-h' || command === 'help') {
+    usage();
+    process.exit(0);
+  }
+  const root = projectRoot(rootArg);
+  if (command === 'status') {
+    const graph = discoverProjectGraph({ project: root });
+    const workflow = path.join(root, '.github', 'workflows', 'klypix-project-map.yml');
+    console.log(`Project: ${root}`);
+    console.log(`Graph artifact: ${graph.status === 'ready' ? `ready (${graph.artifact.graphJson})` : `missing (${graph.artifact.graphJson})`}`);
+    console.log(`GitHub workflow: ${fs.existsSync(workflow) ? 'installed' : 'not installed'}`);
+    process.exit(0);
+  }
+  if (command !== 'setup-github') {
+    usage();
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(root, '.git'))) throw new Error('Run setup-github inside a Git checkout.');
+  const destination = path.join(root, '.github', 'workflows', 'klypix-project-map.yml');
+  const source = fs.readFileSync(template, 'utf8');
+  if (fs.existsSync(destination)) {
+    const current = fs.readFileSync(destination, 'utf8');
+    if (current === source) {
+      console.log(`Project Map workflow is already current: ${destination}`);
+      process.exit(0);
+    }
+    if (!force) throw new Error(`Workflow already exists with different contents: ${destination}\nReview it, then rerun with --force if replacement is intended.`);
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, source, { encoding: 'utf8', flag: 'w' });
+  console.log(`Installed Project Map workflow: ${destination}`);
+  console.log('Commit the workflow when you are ready. Pull requests and main-branch pushes will produce a read-only Project Map artifact.');
+} catch (error) {
+  console.error(`Project Map: ${error?.message || error}`);
+  process.exit(1);
+}

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, suggestProjectGraphBrainLinks } 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)
@@ -298,10 +309,14 @@ server.registerTool('project_map_context', {
     .filter(block => block.kind === 'text')
     .map(block => block.text)
     .join('\n\n');
+  const evidenceLinkProposals = suggestProjectGraphBrainLinks(graphResult, brainResult.context);
+  const proposalMarkdown = evidenceLinkProposals.length
+    ? `\n\n## Exact-path evidence link proposals\n\n${evidenceLinkProposals.slice(0, 12).map(proposal => `- Review brain card \`${proposal.brainCardId}\` beside **${proposal.nodeLabel}** in \`${proposal.sourceFile}\`.`).join('\n')}\n\n_These are review proposals based only on an exact source-path mention. Nothing was written to the brain._`
+    : '';
   return toContent({
-    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}` }],
+    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}${proposalMarkdown}` }],
     isError: brainResult.isError,
-    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, deepHistory: deep_history === true },
+    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, evidenceLinkProposals, deepHistory: deep_history === true },
   });
 });
 

package/examples/github/klypix-project-map.yml

@@ -0,0 +1,45 @@
+name: KLYPIX Project Map
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: klypix-project-map-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GRAPHIFY_VERSION: "0.9.33"
+
+jobs:
+  project-map:
+    name: Generate bounded map artifact
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Generate code-only graph
+        run: uvx --from "graphifyy==${GRAPHIFY_VERSION}" graphify extract . --code-only
+
+      - name: Validate the generated contract
+        run: node -e "const fs=require('fs'); const p='graphify-out/graph.json'; const g=JSON.parse(fs.readFileSync(p,'utf8')); if(!Array.isArray(g.nodes)||!(Array.isArray(g.edges)||Array.isArray(g.links))) throw Error('unsupported graph contract'); console.log('Project Map:',g.nodes.length,'nodes');"
+
+      - name: Upload Project Map artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: klypix-project-map-${{ github.sha }}
+          path: graphify-out/
+          if-no-files-found: error
+          retention-days: 14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.53.0",
+  "version": "1.55.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,8 @@
     "klypix-write": "bin/klypix-write.mjs",
     "klypix-append": "bin/klypix-append.mjs",
     "klypix-install": "bin/klypix-install.mjs",
-    "klypix-uninstall": "bin/klypix-uninstall.mjs"
+    "klypix-uninstall": "bin/klypix-uninstall.mjs",
+    "klypix-project-map": "bin/klypix-project-map.mjs"
   },
   "main": "index.mjs",
   "exports": {
@@ -75,7 +76,7 @@
   },
   "scripts": {
     "test:project-graph": "node test/project-graph.mjs",
-    "test": "node test/project-graph.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

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,93 @@ 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,
+  };
+}
+
+function textContainsExactSourcePath(text, sourceFile) {
+  const haystack = String(text || '').replace(/\\/g, '/').toLocaleLowerCase('en-US');
+  const needle = String(sourceFile || '').replace(/\\/g, '/').toLocaleLowerCase('en-US');
+  if (!needle || !haystack.includes(needle)) return false;
+  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(^|[\\s\`'"([{<])${escaped}($|[\\s\`'"\\])}>.,;:#])`, 'i').test(haystack);
+}
+
+/**
+ * Deterministic proposals only. These are never persisted and never imply
+ * causality: an exact project-relative source path must appear in the brain
+ * card text before KLYPIX will suggest reviewing the pair.
+ */
+export function suggestProjectGraphBrainLinks(graphResult, brainContext, limit = 40) {
+  if (graphResult?.status !== 'ready' || !Array.isArray(graphResult.nodes)) return [];
+  const hits = Array.isArray(brainContext?.hits) ? brainContext.hits : [];
+  const proposals = [];
+  const seen = new Set();
+  for (const node of graphResult.nodes) {
+    if (!node?.sourceFile) continue;
+    for (const hit of hits) {
+      const texts = [hit?.text, hit?.correctedBy].filter(Boolean);
+      if (!texts.some(text => textContainsExactSourcePath(text, node.sourceFile))) continue;
+      const key = `${hit.id}\u0000${node.id}\u0000${node.sourceFile}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      proposals.push({
+        brainCardId: hit.id,
+        brainArea: hit.area || 'Notes',
+        nodeId: node.id,
+        nodeLabel: node.label || node.id,
+        sourceFile: node.sourceFile,
+        basis: 'exact-source-path',
+        status: 'review-proposal',
+      });
+      if (proposals.length >= Math.max(1, Math.min(100, Number(limit) || 40))) return proposals;
+    }
+  }
+  return proposals;
+}
+
 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') : '',