@compr/opscontext-mcp 2.8.1 → 2.8.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.8.2] 2026-09-08: every source says what it is
+
+### Added
+
+- **One-line summary per source in `list_sources` and `contextengine list-sources`**
+  (`src/source-summary.ts`): frontmatter `description` when the file has one, else H1 title
+  plus first prose line, else the module docstring or header comment for code. Read from the
+  first 4 KB of each file only. Why: with 800+ sources an agent opened two or three whole
+  documents to find the right one; the summary lets it pick once.
+
 ## [2.8.1] 2026-09-07: a push is not done until its CI is read
 
 ### Added

package/dist/cli.js

@@ -641,6 +641,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { SERVER_COMMANDS, suggestCommands } from "./cli-commands.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -743,6 +744,9 @@ async function cliListSources() {
         const count = chunks.filter((c) => c.source === s.name).length;
         const status = exists ? `✅ ${count} chunks` : "⚠ file not found";
         console.log(`  ${s.name}: ${status}`);
+        const summary = exists ? summarizeSource(s) : "";
+        if (summary)
+            console.log(`    ${summary}`);
         console.log(`    ${s.path}`);
     }
     console.log("");

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -575,7 +576,7 @@ server.tool("search_context", "Search across all indexed project knowledge (copi
 // ---------------------------------------------------------------------------
 // Tool: list_sources
 // ---------------------------------------------------------------------------
-server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, with their status (found/missing) and chunk counts.", {}, async () => {
+server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, each with a one-line summary (from the file's own head: frontmatter description, title plus first sentence, or module docstring), status (found/missing) and chunk counts. Read the summary to pick the right source before calling read_source.", {}, async () => {
     const lines = sources.map((s) => {
         const exists = existsSync(s.path);
         const count = chunks.filter((c) => c.source === s.name).length;
@@ -583,7 +584,8 @@ server.tool("list_sources", "List all knowledge sources indexed by ContextEngine
         const status = exists
             ? `✅ ${count} chunks${embeddedCount > 0 ? ` (${embeddedCount} embedded)` : ""}`
             : "⚠ file not found";
-        return `${s.name}: ${status}\n  ${s.path}`;
+        const summary = exists ? summarizeSource(s) : "";
+        return `${s.name}: ${status}${summary ? `\n  ${summary}` : ""}\n  ${s.path}`;
     });
     const embStatus = isEmbeddingsReady()
         ? `✅ ${embeddedChunks.length} vectors`

package/dist/source-summary.d.ts

@@ -0,0 +1,9 @@
+import type { KnowledgeSource } from "./config.js";
+export declare const HEAD_BYTES = 4096;
+export declare const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export declare function readHead(path: string, bytes?: number): string;
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export declare function summarizeSource(source: KnowledgeSource): string;
+export declare function summarizeText(text: string, type: "markdown" | "code"): string;
+//# sourceMappingURL=source-summary.d.ts.map

package/dist/source-summary.js

@@ -0,0 +1,150 @@
+/**
+ * One-line summary per knowledge source, for list_sources (MCP) and
+ * `contextengine list-sources` (CLI).
+ *
+ * Why: with 800+ sources, an agent reading a bare name plus a path opens two
+ * or three files to find the right one. Each open puts a whole document into
+ * its context (see CLAUDE.md, multi-agent cost). A summary line derived from
+ * the first few KB of the file lets it pick once.
+ *
+ * Reads only the head of the file (HEAD_BYTES), never the whole document, so
+ * the cost is bounded no matter how many sources are configured.
+ */
+import { openSync, readSync, closeSync } from "fs";
+export const HEAD_BYTES = 4096;
+export const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export function readHead(path, bytes = HEAD_BYTES) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        const buf = Buffer.alloc(bytes);
+        const n = readSync(fd, buf, 0, bytes, 0);
+        return buf.subarray(0, n).toString("utf-8");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export function summarizeSource(source) {
+    return summarizeText(readHead(source.path), source.type);
+}
+export function summarizeText(text, type) {
+    if (!text)
+        return "";
+    return clip(type === "code" ? summarizeCode(text) : summarizeMarkdown(text));
+}
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= SUMMARY_MAX)
+        return one;
+    return one.slice(0, SUMMARY_MAX - 3).trimEnd() + "...";
+}
+/** Strip markdown decoration so the line reads as plain text. */
+function plain(line) {
+    return line
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "") // images
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links -> text
+        .replace(/`([^`]*)`/g, "$1") // inline code
+        .replace(/\*\*|__/g, "") // bold
+        .replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "") // list bullet
+        .replace(/^\s*>\s?/, "") // blockquote
+        .trim();
+}
+/** Header metadata lines that say nothing about the content. */
+const META_LINE = /^(updated|last updated|created|date|status|author|owner|version|scope|audience)\b\s*[:\-]/i;
+function summarizeMarkdown(text) {
+    let body = text;
+    // YAML frontmatter: prefer its description, it IS a one-line summary.
+    if (body.startsWith("---\n") || body.startsWith("---\r\n")) {
+        const end = body.indexOf("\n---", 4);
+        if (end !== -1) {
+            const fm = body.slice(4, end);
+            const desc = fm.match(/^description:\s*(.+)$/m);
+            if (desc)
+                return desc[1].trim().replace(/^["']|["']$/g, "");
+            body = body.slice(end + 4);
+        }
+    }
+    let title = "";
+    let prose = "";
+    let inFence = false;
+    for (const raw of body.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("```") || line.startsWith("~~~")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || !line)
+            continue;
+        if (line.startsWith("<!--") || line.startsWith("|") || line.startsWith("![") || line.startsWith("[!"))
+            continue;
+        if (/^[-=*_]{3,}$/.test(line))
+            continue;
+        if (line.startsWith("#")) {
+            if (!title)
+                title = plain(line.replace(/^#+\s*/, ""));
+            continue;
+        }
+        const p = plain(line);
+        if (p.length < 12)
+            continue; // lone dates, "v2.1", etc.
+        if (META_LINE.test(p))
+            continue; // "Updated: 2026-03-13", "Status: draft"
+        prose = p;
+        break;
+    }
+    if (title && prose)
+        return `${title}: ${prose}`;
+    return title || prose;
+}
+const CODE_SKIP = /^(#!|\/\/\s*eslint|\/\*\s*eslint|@ts-|#\s*-\*-|#\s*coding[:=]|SPDX|Copyright|\[LOCK|\[LOCKED\]|\[NEVER\]|WHY:|FIX:|import |from |export |const |let |var |use strict|"use strict")/i;
+function summarizeCode(text) {
+    const lines = text.split("\n");
+    let inBlock = false;
+    for (const raw of lines) {
+        let line = raw.trim();
+        if (!line)
+            continue;
+        if (!inBlock) {
+            const opensBlock = line.startsWith("/*") || line.startsWith('"""') || line.startsWith("'''");
+            const closesOnSameLine = (line.startsWith("/*") && /\*\/$/.test(line)) ||
+                (/^("""|''')/.test(line) && line.length > 3 && /("""|''')$/.test(line));
+            if (CODE_SKIP.test(line)) {
+                // Pragma, shebang or marker on the raw line: skip it. A one-line
+                // block comment ("/* eslint-disable */") must not leave us in a block.
+                if (opensBlock && !closesOnSameLine)
+                    inBlock = true;
+                continue;
+            }
+            if (opensBlock) {
+                inBlock = !closesOnSameLine;
+                line = line.replace(/^(\/\*+|"""|''')\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+            }
+            else if (line.startsWith("//") || line.startsWith("#")) {
+                line = line.replace(/^(\/\/|#)+\s*/, "").trim();
+            }
+            else {
+                // Code before any comment: nothing worth saying about this file.
+                return "";
+            }
+        }
+        else {
+            if (/(\*\/|"""|''')$/.test(line))
+                inBlock = false;
+            line = line.replace(/^\*+\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+        }
+        if (!line || /^[-=*_#]{3,}$/.test(line) || CODE_SKIP.test(line))
+            continue;
+        if (line.length < 12)
+            continue;
+        return line;
+    }
+    return "";
+}
+//# sourceMappingURL=source-summary.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",