@kage-core/kage-graph-mcp 2.3.2 → 2.4.0

package/dist/index.js

@@ -114,6 +114,7 @@ function listTools() {
             // separate deferred schemas. Cuts session start from 4 schema loads to 1.
             name: "kage_context",
             description: "Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task; it answers caller/usage questions from the code graph too, so you rarely need a separate graph tool.",
+            annotations: { title: "Recall verified memory and query the code/knowledge graph", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -218,10 +219,11 @@ function listTools() {
         {
             name: "kage_risk",
             description: "Assess modification risk for files using Kage's code graph plus local git history: dependents, impact surface, churn, ownership, co-change partners, and test gaps. Use before editing hotspot or shared files.",
+            annotations: { title: "Assess file modification risk", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     targets: { type: "array", items: { type: "string" }, description: "File paths to assess" },
                     changed_files: { type: "array", items: { type: "string" }, description: "Optional PR/branch changed files. If targets is omitted, these are assessed." },
                 },
@@ -231,10 +233,11 @@ function listTools() {
         {
             name: "kage_dependency_path",
             description: "Find how two files are connected in Kage's source-derived code graph. Reports direct dependency direction, reverse impact direction, or undirected graph connection.",
+            annotations: { title: "Trace the dependency path between two files", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     from: { type: "string", description: "Source file path or unique suffix" },
                     to: { type: "string", description: "Target file path or unique suffix" },
                 },
@@ -352,11 +355,12 @@ function listTools() {
         },
         {
             name: "kage_decisions",
-            description: "Summarize Kage why-memory for a repo: decisions, gotchas, runbooks, conventions, code explanations, path coverage, weak/stale memory, and important code paths that still lack decision memory.",
+            description: "Summarize the repo's 'why' memory at a glance: the decisions, gotchas, runbooks, conventions, and code explanations Kage has captured, plus which high-traffic code paths still have no decision memory. Use it to brief yourself on a repo before changing it, or to audit where institutional knowledge is thin or going stale. Read-only: returns grouped entries with titles, types, cited file paths, and call-outs for weak, stale, or undocumented hot paths. Does not modify any memory.",
+            annotations: { title: "Summarize the repo's decision memory", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root to summarize." },
                 },
                 required: ["project_dir"],
             },
@@ -386,12 +390,13 @@ function listTools() {
         {
             name: "kage_docs_search",
             description: "Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.",
+            annotations: { title: "Search the repo's own committed docs", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    query: { type: "string" },
-                    project_dir: { type: "string" },
-                    limit: { type: "number" },
+                    query: { type: "string", description: "Search terms to match against the repo's documentation." },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    limit: { type: "number", description: "Max ranked doc hits to return (default 5)." },
                 },
                 required: ["query", "project_dir"],
             },
@@ -489,10 +494,11 @@ function listTools() {
         {
             name: "kage_refresh",
             description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh. On non-default git branches metadata-only packet rewrites are skipped (quiet refresh) to avoid merge conflicts; pass force to persist them anyway.",
+            annotations: { title: "Rebuild Kage indexes and graphs", readOnlyHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     force: { type: "boolean", description: "Persist packet metadata rewrites even on a non-default branch" },
                 },
                 required: ["project_dir"],
@@ -521,10 +527,11 @@ function listTools() {
         {
             name: "kage_pr_check",
             description: "Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. Leads with a human summary of team memories invalidated by the current change — relay it to the developer.",
+            annotations: { title: "Check memory readiness for merge", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                 },
                 required: ["project_dir"],
             },
@@ -612,14 +619,15 @@ function listTools() {
         },
         {
             name: "kage_supersede",
-            description: "Mark one repo-local memory packet as superseded by a replacement packet and write bidirectional lineage edges.",
+            description: "Replace one repo-local memory packet with a newer one that corrects or obsoletes it. Marks the old packet superseded, links it to the replacement, and writes bidirectional lineage edges so the history stays traceable. Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts. Mutates both packets on disk: the superseded packet is withheld from recall but kept for lineage.",
+            annotations: { title: "Supersede a memory packet with a newer one", readOnlyHint: false, destructiveHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
-                    packet_id: { type: "string" },
-                    replacement_packet_id: { type: "string" },
-                    reason: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    packet_id: { type: "string", description: "Id of the existing packet to retire (the one being replaced)." },
+                    replacement_packet_id: { type: "string", description: "Id of the newer packet that wins and stays active." },
+                    reason: { type: "string", description: "Optional human note recorded on the lineage edge explaining why it was superseded." },
                 },
                 required: ["project_dir", "packet_id", "replacement_packet_id"],
             },
@@ -638,12 +646,13 @@ function listTools() {
         {
             name: "kage_skills",
             description: "Codify durable, verified repo memory (runbooks, workflows, actionable decisions) into git-native SKILL.md files under .claude/skills/ that every teammate's agent auto-loads. Only grounded, non-stale packets become skills. Pass dry_run to preview without writing. dir overrides the output directory.",
+            annotations: { title: "Codify verified memory into agent skills", readOnlyHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
-                    dry_run: { type: "boolean" },
-                    dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    dry_run: { type: "boolean", description: "Preview which skills would be written without creating any files." },
+                    dir: { type: "string", description: "Override the output directory (default .claude/skills/)." },
                 },
                 required: ["project_dir"],
             },
@@ -735,21 +744,22 @@ function listTools() {
         },
         {
             name: "kage_learn",
-            description: "Capture an actual reusable learning from the current session as repo-local memory. Prefer this over diff proposal when the agent knows what was learned. Capture is rejected if every referenced path is missing from the repo; set allow_missing_paths to record anyway (e.g. a file you are about to create).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_dir: { type: "string" },
-                    learning: { type: "string" },
-                    title: { type: "string" },
-                    type: { type: "string" },
-                    evidence: { type: "string" },
-                    verified_by: { type: "string" },
-                    tags: { type: "array", items: { type: "string" } },
-                    paths: { type: "array", items: { type: "string" } },
-                    stack: { type: "array", items: { type: "string" } },
-                    graph_nodes: { type: "array", items: { type: "string" } },
-                    allow_missing_paths: { type: "boolean" },
+            description: "Capture a durable, reusable learning from the current session as a verified repo-local memory packet (committed under .agent_memory/, shared with the team via git). Use it the moment you discover something a future session should know: a decision and its rationale, a bug's root cause and fix, a convention, or a setup step. Prefer it over diff-based proposals when you already know what was learned. The write is rejected if every cited path is missing from the repo (set allow_missing_paths for a file you are about to create), and secrets/PII are scanned out before writing. Returns the new packet id plus any contradiction warnings against existing memory.",
+            annotations: { title: "Capture a verified learning to repo memory", readOnlyHint: false },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    learning: { type: "string", description: "The insight to store, in full sentences: what was learned and why it matters to a future session." },
+                    title: { type: "string", description: "Short headline for the packet. Derived from the learning if omitted." },
+                    type: { type: "string", description: "Memory type: decision, bug_fix, runbook, convention, gotcha, workflow, code_explanation. Inferred if omitted." },
+                    evidence: { type: "string", description: "How the learning was confirmed (e.g. test output, a reproduced behavior)." },
+                    verified_by: { type: "string", description: "What verified it (e.g. a command run, a passing test, a reviewer)." },
+                    tags: { type: "array", items: { type: "string" }, description: "Optional keywords to aid future recall." },
+                    paths: { type: "array", items: { type: "string" }, description: "Repo files this memory is about; used to verify the citation now and to recall the memory when those files are touched later." },
+                    stack: { type: "array", items: { type: "string" }, description: "Optional technologies/frameworks the learning relates to." },
+                    graph_nodes: { type: "array", items: { type: "string" }, description: "Optional code-graph symbol or file ids this memory is grounded to." },
+                    allow_missing_paths: { type: "boolean", description: "Allow the write even if cited paths do not exist yet (e.g. a file you are about to create)." },
                     discovery_tokens: { type: "number", description: "Approximate token cost of producing this knowledge (exploration + reasoning). Stored on the packet so recall receipts can report replay value; a conservative per-type default is estimated when omitted." },
                 },
                 required: ["project_dir", "learning"],
@@ -872,13 +882,14 @@ function listTools() {
         },
         {
             name: "kage_feedback",
-            description: "Record usefulness feedback on an approved repo-local memory packet: helpful, wrong, or stale.",
+            description: "Record how useful a recalled repo-local memory packet was, which tunes Kage's trust and future recall. 'helpful' reinforces the packet, 'wrong' flags it as disputed, and 'stale' marks it for re-verification and withholds it from recall until refreshed. Use it right after a recalled packet helped you, misled you, or no longer matched the code. Mutates the packet's quality signals on disk.",
+            annotations: { title: "Rate a recalled memory packet", readOnlyHint: false },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
-                    packet_id: { type: "string" },
-                    kind: { type: "string", enum: ["helpful", "wrong", "stale"] },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    packet_id: { type: "string", description: "Id of the memory packet you are rating." },
+                    kind: { type: "string", enum: ["helpful", "wrong", "stale"], description: "helpful = it was accurate and useful; wrong = it was incorrect (flag as disputed); stale = it no longer matches the code (mark for re-verification)." },
                 },
                 required: ["project_dir", "packet_id", "kind"],
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
   "main": "dist/index.js",
   "files": [