@aaronsb/kg-cli 0.9.4 → 0.10.0

package/dist/mcp-server.js

@@ -47,6 +47,7 @@ const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const client_js_1 = require("./api/client.js");
+const config_js_1 = require("./lib/config.js");
 const auth_client_js_1 = require("./lib/auth/auth-client.js");
 const mcp_allowlist_js_1 = require("./lib/mcp-allowlist.js");
 const index_js_2 = require("./mcp/formatters/index.js");
@@ -220,6 +221,62 @@ function createAuthenticatedClient() {
 }
 // Client instance - will be initialized in main() before server starts
 let client;
+/**
+ * Fetch recent concepts from the graph for session context.
+ * Returns a compact summary and structured data. Fails gracefully if API is unreachable.
+ */
+async function fetchRecentConcepts(limit, ontology) {
+    try {
+        let query = 'MATCH (c:Concept) WHERE c.created_at_epoch IS NOT NULL';
+        if (ontology) {
+            // Whitelist validation — ontology names are slugified strings
+            if (!/^[a-zA-Z0-9_\-. ()]+$/.test(ontology)) {
+                return { summary: `Invalid ontology name: ${ontology}`, concepts: [] };
+            }
+            query += ` AND c.ontology = '${ontology}'`;
+        }
+        query += ' RETURN c ORDER BY c.created_at_epoch DESC';
+        const result = await client.executeProgram({
+            program: {
+                version: 1,
+                statements: [{
+                        op: '+',
+                        operation: { type: 'cypher', query, limit },
+                        label: 'recent_concepts',
+                    }],
+            },
+        });
+        const nodes = result.result.nodes || [];
+        const concepts = nodes.map((n) => ({
+            label: n.label,
+            concept_id: n.concept_id,
+            ontology: n.ontology ?? null,
+            created_at_epoch: n.properties?.created_at_epoch ?? 0,
+        }));
+        if (concepts.length === 0) {
+            return { summary: 'No concepts in the knowledge graph yet.', concepts: [] };
+        }
+        const labels = concepts.map((c) => c.label).join(' | ');
+        return { summary: `Recent concepts (${concepts.length}): ${labels}`, concepts };
+    }
+    catch {
+        return { summary: 'Knowledge graph unavailable — API server may not be running.', concepts: [] };
+    }
+}
+/**
+ * Resolve the ontology name for session ingest.
+ * Priority: config oauth_client_name > env KG_OAUTH_CLIENT_ID > 'sessions'
+ */
+function getSessionOntology() {
+    const config = (0, config_js_1.getConfig)();
+    const clientName = config.get('auth.oauth_client_name');
+    if (clientName)
+        return clientName;
+    const envClientId = process.env.KG_OAUTH_CLIENT_ID;
+    if (envClientId)
+        return envClientId;
+    return 'sessions';
+}
 /**
  * Tool Definitions
  *
@@ -227,6 +284,28 @@ let client;
  */
 // List available tools
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    // Build dynamic session context
+    const config = (0, config_js_1.getConfig)();
+    let sessionContextDescription;
+    if (config.getSessionContextEnabled()) {
+        const { summary } = await fetchRecentConcepts(config.getSessionContextLimit(), config.getSessionContextOntology());
+        sessionContextDescription = `Recent knowledge graph activity. This tool provides active, unsolicited state information about the knowledge graph — what concepts were most recently created or encountered.
+
+${summary}
+
+Call this tool to refresh context, adjust the limit, or filter by ontology. Results include concept labels, IDs, ontology, and creation epoch.`;
+    }
+    else {
+        sessionContextDescription = 'Read recent knowledge graph activity. Session context is currently disabled in config (~/.config/kg/config.json session.context_enabled).';
+    }
+    const sessionOntology = getSessionOntology();
+    const sessionIngestDescription = `Save a session summary to the knowledge graph for cross-session memory.
+
+**IMPORTANT: Before your session ends or context compacts, call this tool with a summary of key topics, decisions, and insights from this session.**
+
+Text is ingested into the "${sessionOntology}" ontology, creating concepts that will appear in session_context on your next connection. The ingest job is auto-approved.
+
+Input: text (required) — your session summary. Optional: filename for source tracking.`;
     return {
         tools: [
             {
@@ -257,6 +336,10 @@ RECOMMENDED WORKFLOW: After search, use concept (action: "connect") to find HOW
 
 For multi-step exploration, compose searches into a GraphProgram (program tool) instead of making individual calls. One program can seed from search, expand relationships, and filter — all server-side in a single round-trip. Use program (action: "list") to find reusable stored programs, or read the program/syntax resource for composition examples.
 
+ESCALATION: For analytical questions or exploring more than 2 concepts, go directly to the program tool — one composed query replaces many individual calls.
+
+To verify a result, use source to retrieve the original text behind any evidence, or concept (action: "details") to see all evidence and relationships for a concept.
+
 Use 2-3 word phrases (e.g., "linear thinking patterns").`,
                 inputSchema: {
                     type: 'object',
@@ -298,9 +381,11 @@ Use 2-3 word phrases (e.g., "linear thinking patterns").`,
                 name: 'concept',
                 description: `Work with concepts: get details (ALL evidence + relationships), find related concepts (neighborhood exploration), or discover connections (paths between concepts).
 
-For "connect" action, defaults (threshold=0.5, max_hops=5) match the CLI and work well for most queries. Use higher thresholds (0.75+) only if you need to narrow results for precision.
+For "connect" action, defaults (threshold=0.5, max_hops=5) match the CLI and work well for most queries. Use higher thresholds (0.75+) only if you need to narrow results for precision. Note: connect traverses semantic edges only (IMPLIES, SUPPORTS, CONTRADICTS, etc.) — manually-created edges with no traversal history may not appear in paths. Use program/Cypher for comprehensive traversal.
+
+If connect returns no paths or you need to combine multiple lookups, escalate to the program tool — one composed query replaces many individual calls. Do not repeat connect hoping for different results.
 
-For multi-step workflows (search → connect → expand → filter), compose these into a GraphProgram instead of making individual calls. See the program tool and program/syntax resource.`,
+For multi-step workflows (search → connect → expand → filter), compose these into a GraphProgram instead of making individual calls. For example, seed from a search then expand via Cypher using $W_IDS to reference accumulated concept IDs. See the program tool and program/syntax resource for this and other composition patterns.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -343,7 +428,7 @@ For multi-step workflows (search → connect → expand → filter), compose the
                         relationship_types: {
                             type: 'array',
                             items: { type: 'string' },
-                            description: 'Filter relationships (e.g., ["SUPPORTS", "CONTRADICTS"])',
+                            description: 'Filter relationships (e.g., ["SUPPORTS", "CONTRADICTS"]). Constrains traversal, not just results — if the first hop is structural, filtering to semantic types may return empty. Omit for broadest results, then narrow.',
                         },
                         // ADR-065: Epistemic status filtering (for related and connect)
                         include_epistemic_status: {
@@ -626,7 +711,9 @@ Use when you need to:
 - Verify extracted concepts against original source
 - Get the full context of a text passage
 - Retrieve images for visual analysis
-- Check character offsets for highlighting`,
+- Check character offsets for highlighting
+
+Source IDs appear in search results and concept details evidence. Use concept (action: "details") to see all evidence for a concept, or search (type: "sources") to find passages directly.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -655,7 +742,9 @@ EPISTEMIC STATUS CLASSIFICATIONS:
 - INSUFFICIENT_DATA: <3 successful measurements
 - UNCLASSIFIED: Doesn't fit known patterns
 
-Use for filtering relationships by epistemic reliability, identifying contested knowledge areas, and curating high-confidence vs exploratory subgraphs.`,
+Use for filtering relationships by epistemic reliability, identifying contested knowledge areas, and curating high-confidence vs exploratory subgraphs.
+
+Concept (action: "related") and connect accept include_epistemic_status/exclude_epistemic_status filters to narrow traversals by reliability. Use search to find concepts in contested areas, then epistemic_status to understand why.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -711,7 +800,9 @@ Use Cases:
 - Explore conceptual spectrums and gradients
 - Identify position-grounding correlation patterns
 - Discover concepts balanced between opposing ideas
-- Map semantic dimensions in the knowledge graph`,
+- Map semantic dimensions in the knowledge graph
+
+Requires concept IDs for poles — use search to find opposing concepts first. Use concept (action: "details") to inspect pole concepts before analysis.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -811,7 +902,7 @@ Three actions available:
 - "concepts": Get all concepts extracted from a document
 
 Documents are aggregated from source chunks and stored in Garage (S3-compatible storage).
-Use search tool with type="documents" to find documents semantically.`,
+Use search tool with type="documents" to find documents semantically. Use document (action: "concepts") to see what was extracted, then concept (action: "details") or source to drill into specifics.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -875,7 +966,8 @@ Use for manual curation, agent-driven knowledge building, and precise graph mani
 
 **Semantic Resolution:**
 - Use \`from_label\`/\`to_label\` to reference concepts by name instead of ID
-- Resolution uses vector similarity (85% threshold) to find matching concepts
+- Resolution uses vector similarity (75% threshold) to find matching concepts
+- Near-misses (60-75%) return "Did you mean?" suggestions with concept IDs
 
 **Examples:**
 - Create concept: \`{action: "create", entity: "concept", label: "CAP Theorem", ontology: "distributed-systems"}\`
@@ -894,7 +986,7 @@ Use for manual curation, agent-driven knowledge building, and precise graph mani
   ]
 }
 \`\`\`
-Queue executes sequentially, stops on first error (unless continue_on_error=true). Max 20 operations.`,
+Queue executes sequentially, continues past errors by default (set continue_on_error=false to stop on first error). Max 20 operations.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -939,8 +1031,8 @@ Queue executes sequentially, stops on first error (unless continue_on_error=true
                         },
                         continue_on_error: {
                             type: 'boolean',
-                            description: 'For queue: continue executing after errors (default: false, stop on first error)',
-                            default: false,
+                            description: 'For queue: continue executing after errors (default: true). Set false to stop on first error.',
+                            default: true,
                         },
                         // Concept fields
                         label: {
@@ -1042,6 +1134,8 @@ Queue executes sequentially, stops on first error (unless continue_on_error=true
                 name: 'program',
                 description: `Compose and execute GraphProgram queries against the knowledge graph (ADR-500).
 
+Use search/connect/related for quick lookups (one concept, one path). Use program when you need the neighborhood of more than 2 concepts, want to combine search with traversal, or are asking an analytical question about graph structure. If you've made 3+ individual tool calls without converging, you should already be here.
+
 Programs are JSON ASTs that compose Cypher queries and API calls using set-algebra operators.
 Each statement applies an operator to merge/filter results into a mutable Working Graph (W).
 
@@ -1067,6 +1161,11 @@ Each statement applies an operator to merge/filter results into a mutable Workin
   { type: "cypher", query: "MATCH (c:Concept)-[r]->(t:Concept) RETURN c, r, t", limit?: 20 }
   Queries must be read-only (no CREATE/SET/DELETE/MERGE). RETURN nodes and relationships.
 
+**AGE Cypher gotchas** (Apache AGE openCypher differs from Neo4j):
+- Filter relationship types with WHERE, not inline: \`WHERE type(r) IN ['SUPPORTS', 'CONTRADICTS']\` (NOT \`[r:SUPPORTS|CONTRADICTS]\`)
+- Reference working graph concepts: \`WHERE c.concept_id IN $W_IDS\`
+- Always RETURN both nodes and relationships for full path data
+
 **ApiOp** — call internal service functions (no HTTP):
   { type: "api", endpoint: "/search/concepts", params: { query: "...", limit: 10 } }
 
@@ -1074,7 +1173,7 @@ Each statement applies an operator to merge/filter results into a mutable Workin
   /search/concepts   — params: query (required), min_similarity?, limit?
   /search/sources    — params: query (required), min_similarity?, limit?
   /concepts/details  — params: concept_id (required)
-  /concepts/related  — params: concept_id (required), max_depth?, relationship_types?
+  /concepts/related  — params: concept_id (required), max_depth?, relationship_types?  [returns nodes + edges in programs]
   /concepts/batch    — params: concept_ids (required, list)
   /vocabulary/status — params: relationship_type?, status_filter?
 
@@ -1087,6 +1186,9 @@ Each statement applies an operator to merge/filter results into a mutable Workin
       label: "expand relationships" }
   ]}
 
+**Alternative** — API-only composition (no Cypher needed):
+  Use /concepts/related to expand from a known concept ID. Inside programs, related returns both nodes and edges (topology), making it suitable for graph exploration without writing Cypher.
+
 Read the program/syntax resource for the complete language reference with more examples.`,
                 inputSchema: {
                     type: 'object',
@@ -1136,6 +1238,43 @@ Read the program/syntax resource for the complete language reference with more e
                     required: ['action'],
                 },
             },
+            {
+                name: 'session_context',
+                description: sessionContextDescription,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum concepts to return (default: 10, max: 50)',
+                            default: 10,
+                        },
+                        ontology: {
+                            type: 'string',
+                            description: 'Filter by ontology name (default: all ontologies)',
+                        },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: 'session_ingest',
+                description: sessionIngestDescription,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        text: {
+                            type: 'string',
+                            description: 'Session summary text to ingest into the knowledge graph',
+                        },
+                        filename: {
+                            type: 'string',
+                            description: 'Optional filename for source tracking (e.g., "session-2025-01-15.md")',
+                        },
+                    },
+                    required: ['text'],
+                },
+            },
         ],
     };
 });
@@ -2347,7 +2486,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     }
                     case 'queue': {
                         const operations = toolArgs.operations;
-                        const continueOnError = toolArgs.continue_on_error === true;
+                        const continueOnError = toolArgs.continue_on_error !== false;
                         if (!operations || !Array.isArray(operations)) {
                             throw new Error('operations array is required for queue action');
                         }
@@ -2483,6 +2622,11 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                             });
                             const lines = [];
                             const totalMs = result.log.reduce((sum, e) => sum + e.duration_ms, 0);
+                            // Build id → label map for readable link output
+                            const nodeLabels = new Map();
+                            for (const node of result.result.nodes) {
+                                nodeLabels.set(node.concept_id, node.label);
+                            }
                             if (result.aborted) {
                                 lines.push(`✗ Aborted at statement ${result.aborted.statement}: ${result.aborted.reason}`);
                             }
@@ -2516,7 +2660,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                             if (result.result.links.length > 0) {
                                 lines.push('\nLinks:');
                                 for (const link of result.result.links.slice(0, 30)) {
-                                    lines.push(`  ${link.from_id} → ${link.relationship_type} → ${link.to_id}`);
+                                    const from = nodeLabels.get(link.from_id) || link.from_id;
+                                    const to = nodeLabels.get(link.to_id) || link.to_id;
+                                    lines.push(`  ${from} → ${link.relationship_type} → ${to}`);
                                 }
                                 if (result.result.links.length > 30) {
                                     lines.push(`  ... and ${result.result.links.length - 30} more`);
@@ -2579,6 +2725,11 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         try {
                             const result = await client.chainPrograms(toolArgs.deck);
                             const lines = [];
+                            // Build id → label map for readable link output
+                            const nodeLabels = new Map();
+                            for (const node of result.result.nodes) {
+                                nodeLabels.set(node.concept_id, node.label);
+                            }
                             if (result.aborted) {
                                 lines.push(`✗ Chain aborted at statement ${result.aborted.statement}: ${result.aborted.reason}`);
                             }
@@ -2609,7 +2760,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                             if (result.result.links.length > 0) {
                                 lines.push('\nLinks:');
                                 for (const link of result.result.links.slice(0, 30)) {
-                                    lines.push(`  ${link.from_id} → ${link.relationship_type} → ${link.to_id}`);
+                                    const from = nodeLabels.get(link.from_id) || link.from_id;
+                                    const to = nodeLabels.get(link.to_id) || link.to_id;
+                                    lines.push(`  ${from} → ${link.relationship_type} → ${to}`);
                                 }
                                 if (result.result.links.length > 30) {
                                     lines.push(`  ... and ${result.result.links.length - 30} more`);
@@ -2634,6 +2787,39 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         throw new Error(`Unknown program action: ${action}. Use: validate, create, get, list, execute, or chain`);
                 }
             }
+            case 'session_context': {
+                const limit = Math.min(toolArgs.limit || 10, 50);
+                const ontology = toolArgs.ontology || null;
+                const { summary, concepts } = await fetchRecentConcepts(limit, ontology);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: (0, index_js_2.formatSessionContext)(concepts, summary),
+                        }],
+                };
+            }
+            case 'session_ingest': {
+                const text = toolArgs.text;
+                if (!text) {
+                    throw new Error('text is required');
+                }
+                const ontology = getSessionOntology();
+                const result = await client.ingestText(text, {
+                    ontology,
+                    filename: toolArgs.filename || undefined,
+                    auto_approve: true,
+                    force: false,
+                    processing_mode: 'serial',
+                    options: {
+                        target_words: 1000,
+                        overlap_words: 200,
+                    },
+                    source_type: 'mcp',
+                });
+                return {
+                    content: [{ type: 'text', text: (0, index_js_2.formatSessionIngest)(result) }],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -2850,7 +3036,8 @@ Allowed endpoints and their parameters:
   /concepts/related
     Required: concept_id (string)
     Optional: max_depth (integer, default 2), relationship_types (string array)
-    Returns: neighborhood concept nodes
+    Returns: neighborhood concept nodes + edges between them (full topology).
+    Note: relationship_types constrains traversal — omit for broadest results.
 
   /concepts/batch
     Required: concept_ids (string array)