@systemdox/mcp-server 0.1.50 → 0.1.52

package/dist/cli.js

@@ -592,9 +592,9 @@ function localDate(now) {
   return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
 }
 function conflictCopyName(path, date, taken) {
-  const stem = path.replace(/\.md$/, "");
+  const stem2 = path.replace(/\.md$/, "");
   for (let n = 1; ; n++) {
-    const name = `${stem}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
+    const name = `${stem2}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
     if (!taken.has(name.toLowerCase())) return name;
   }
 }
@@ -1828,6 +1828,7 @@ __export(setup_mcp_exports, {
   writeServerEntry: () => writeServerEntry
 });
 import { existsSync as existsSync3, readFileSync } from "fs";
+import { mkdir as mkdir4 } from "fs/promises";
 import { join as join4 } from "path";
 async function validateApiKey(apiKey, apiUrl) {
   try {
@@ -1955,6 +1956,7 @@ async function setupMcpServer(opts) {
   }
   try {
     if ((await readCredentials())[workspace]?.apiKey !== apiKey) await writeCredentials(workspace, apiKey);
+    await mkdir4(join4(homeDir(), ".claude", "skills"), { recursive: true });
     const several = Object.keys(await readCredentials()).length > 1;
     for (const target of selected) {
       const removed = await writeServerEntry(target.path, apiUrl, several ? workspace : void 0);
@@ -2000,7 +2002,7 @@ var init_setup_mcp = __esm({
 
 // src/lib/skills.ts
 import { createHash as createHash3 } from "crypto";
-import { lstat, mkdir as mkdir4, readdir as readdir3, readFile as readFile4, rm as rm3, writeFile as writeFile4 } from "fs/promises";
+import { lstat, mkdir as mkdir5, readdir as readdir3, readFile as readFile4, rm as rm3, writeFile as writeFile4 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname4, join as join5, relative, resolve as resolve3, sep } from "path";
@@ -2125,7 +2127,7 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
   const written = [];
   for (const f of version.files) {
     const full = within(dest, f.path);
-    await mkdir4(dirname4(full), { recursive: true });
+    await mkdir5(dirname4(full), { recursive: true });
     await writeFile4(full, f.content, "utf8");
     written.push(f.path);
   }
@@ -2160,6 +2162,9 @@ function fenceFor(text3) {
   const longest = Math.max(0, ...(text3.match(/`+/g) ?? []).map((r) => r.length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -2169,7 +2174,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join5(r.dest, "SKILL.md")));
   return lines.join("\n");
 }
 var MANIFEST_FILE, ENTRY_FILE, PLUGIN_MANIFEST_FOLDER, MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES, NAME_RE, SEGMENT_RE, SKIPPED, SkillInstallRefused;
@@ -2296,7 +2301,7 @@ __export(plugin_path_exports, {
 });
 import { createHash as createHash4, randomBytes } from "crypto";
 import { existsSync as existsSync5 } from "fs";
-import { mkdir as mkdir5, rename as rename2, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir6, rename as rename2, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname5, join as join6, resolve as resolve5, sep as sep2 } from "path";
 import { inflateRawSync } from "zlib";
 function parsePluginPathArgs(argv) {
@@ -2394,13 +2399,13 @@ async function unpackZip(zip, dest) {
     return full;
   });
   const data = entries2.map((e) => e.directory ? void 0 : entryData(zip, e));
-  await mkdir5(root, { recursive: true });
+  await mkdir6(root, { recursive: true });
   for (const [i, entry] of entries2.entries()) {
     if (entry.directory) {
-      await mkdir5(targets[i], { recursive: true });
+      await mkdir6(targets[i], { recursive: true });
       continue;
     }
-    await mkdir5(dirname5(targets[i]), { recursive: true });
+    await mkdir6(dirname5(targets[i]), { recursive: true });
     await writeFile5(targets[i], data[i], { mode: entry.mode ?? 420 });
   }
   return entries2.filter((e) => !e.directory).length;
@@ -2852,6 +2857,21 @@ var init_get_guardrails = __esm({
   }
 });
 
+// src/lib/spec-label.ts
+function isDecisionDraft(name) {
+  return name.startsWith(DECISION_PREFIX);
+}
+function specLabel(spec) {
+  return isDecisionDraft(spec.name) ? "decision record" : `${spec.requirementCount} requirements`;
+}
+var DECISION_PREFIX;
+var init_spec_label = __esm({
+  "src/lib/spec-label.ts"() {
+    "use strict";
+    DECISION_PREFIX = "ADR: ";
+  }
+});
+
 // src/tools/get-specs.ts
 import { z as z2 } from "zod";
 function registerGetSpecs(server, apiClient2) {
@@ -2918,7 +2938,7 @@ ${spec.taskContent}`);
         };
       }
       const text3 = filtered.map(
-        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${s.requirementCount} requirements` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
+        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${specLabel(s)}` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
       ).join("\n");
       return {
         content: [
@@ -2936,11 +2956,16 @@ ${text3}`
 var init_get_specs = __esm({
   "src/tools/get-specs.ts"() {
     "use strict";
+    init_spec_label();
   }
 });
 
 // src/tools/get-docs.ts
 import { z as z3 } from "zod";
+function literalPrefix(pattern) {
+  const wildcard = pattern.indexOf("*");
+  return wildcard < 0 ? pattern : pattern.slice(0, wildcard);
+}
 function matchGlob(path, pattern) {
   const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
   return new RegExp(`^${regex}$`).test(path);
@@ -3001,11 +3026,17 @@ ${doc.content}`;
       const params = {};
       if (repo) params.repo = repo;
       if (search) params.q = search;
+      if (path) {
+        params.limit = PATH_FILTER_LIMIT;
+        const prefix = literalPrefix(path);
+        if (prefix) params.pathPrefix = prefix;
+      }
       const response = await apiClient2.get(
         "/v1/docs",
         params
       );
       let items = response.items;
+      const unread = path ? response.total - response.items.length : 0;
       if (path) {
         items = items.filter((item2) => matchGlob(item2.path, path));
       }
@@ -3035,16 +3066,20 @@ ${doc.content}`;
 
 ${text3}
 
-Use doc_id for full content, or doc_id + section to fetch one section.`
+` + (unread > 0 ? `${unread} more were not read. Start the path with a folder to narrow it.
+
+` : "") + "Use doc_id for full content, or doc_id + section to fetch one section."
           }
         ]
       };
     }
   );
 }
+var PATH_FILTER_LIMIT;
 var init_get_docs = __esm({
   "src/tools/get-docs.ts"() {
     "use strict";
+    PATH_FILTER_LIMIT = "1000";
   }
 });
 
@@ -3147,7 +3182,9 @@ ${deps}`);
       }
       if (ctx.adrs.length > 0) {
         const adrs = ctx.adrs.map((a) => `- ${a.title}${a.repo ? ` (${a.repo})` : ""}`).join("\n");
-        sections.push(`## Architecture Decision Records (${ctx.adrs.length})
+        const total = ctx.adrTotal ?? ctx.adrs.length;
+        const count = total > ctx.adrs.length ? `${ctx.adrs.length} newest of ${total}` : `${ctx.adrs.length}`;
+        sections.push(`## Architecture Decision Records (${count})
 
 ${adrs}`);
       }
@@ -3576,6 +3613,32 @@ function scoreSeverity(item2) {
   if (!item2.severity) return 0.5;
   return SEVERITY_SCORES[item2.severity] ?? 0.5;
 }
+function stem(word) {
+  return word.length > 3 ? word.replace(/s$/, "") : word;
+}
+function stems(text3) {
+  return new Set(
+    text3.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(stem)
+  );
+}
+function titleShare(title, keywords) {
+  const wanted = stems(keywords.join(" "));
+  if (wanted.size === 0) return 0;
+  const held = stems(title);
+  let matches = 0;
+  for (const word of wanted) {
+    if (held.has(word)) matches++;
+  }
+  return matches / wanted.size;
+}
+function scoreReference(item2, keywords) {
+  const share = titleShare(item2.title, keywords);
+  const score = Math.max(
+    item2.relevance ?? 0,
+    share >= MIN_TITLE_SHARE ? share : 0
+  );
+  return RECORD_PATH.test(item2.path ?? "") ? score * RECORD_FACTOR : score;
+}
 function extractKeywords(text3) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
@@ -3672,7 +3735,8 @@ function scoreItems(items, taskDescription, filePaths) {
     const keywordScore = scoreKeywordMatch(item2, keywords);
     const recencyScore = scoreRecency(item2);
     const severityScore = scoreSeverity(item2);
-    const score = pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
+    const isReference2 = item2.type === "spec" || item2.type === "doc";
+    const score = isReference2 && keywords.length > 0 ? scoreReference(item2, keywords) : pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
     return {
       type: item2.type,
       id: item2.id,
@@ -3681,7 +3745,7 @@ function scoreItems(items, taskDescription, filePaths) {
       score,
       tokenEstimate: estimateTokens(item2.content)
     };
-  }).sort((a, b) => b.score - a.score);
+  }).filter((item2) => item2.score > 0).sort((a, b) => b.score - a.score);
 }
 function selectWithinBudget(items, maxTokens) {
   const selected = [];
@@ -3693,7 +3757,7 @@ function selectWithinBudget(items, maxTokens) {
   }
   return { selected, tokensUsed, totalItems: items.length };
 }
-var WEIGHT_PATH, WEIGHT_KEYWORD, WEIGHT_RECENCY, WEIGHT_SEVERITY, SEVERITY_SCORES, CHARS_PER_TOKEN;
+var WEIGHT_PATH, WEIGHT_KEYWORD, WEIGHT_RECENCY, WEIGHT_SEVERITY, SEVERITY_SCORES, MIN_TITLE_SHARE, RECORD_PATH, RECORD_FACTOR, CHARS_PER_TOKEN;
 var init_scoring = __esm({
   "src/lib/scoring.ts"() {
     "use strict";
@@ -3708,6 +3772,9 @@ var init_scoring = __esm({
       medium: 0.5,
       low: 0.25
     };
+    MIN_TITLE_SHARE = 1 / 3;
+    RECORD_PATH = /(^|\/)changelog\//;
+    RECORD_FACTOR = 0.5;
     CHARS_PER_TOKEN = 4;
   }
 });
@@ -3731,7 +3798,7 @@ ${g.fix}
 }
 function formatSpecHeadline(s) {
   return `### ${s.name}
-\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${s.requirementCount} requirements`;
+\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${specLabel(s)}`;
 }
 function formatDocHeadline(d) {
   return `### ${d.title}
@@ -3742,6 +3809,21 @@ function formatStack(entries2) {
     (e) => `- ${e.name}${e.version ? ` v${e.version}` : ""}${e.notes ? ` \u2014 ${e.notes}` : ""}`
   ).join("\n");
 }
+function selectStack(entries2, words, maxTokens) {
+  const named = (e) => {
+    const entry = `${e.name} ${e.notes ?? ""}`.toLowerCase();
+    return words.some((w) => entry.includes(w));
+  };
+  const ordered = [...entries2.filter(named), ...entries2.filter((e) => !named(e))];
+  const shown = [];
+  for (const entry of ordered) {
+    if (shown.length > 0 && estimateTokens(formatStack([...shown, entry])) > maxTokens) {
+      break;
+    }
+    shown.push(entry);
+  }
+  return { text: formatStack(shown), hidden: entries2.length - shown.length };
+}
 function formatRules(rules) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const r of rules) {
@@ -3763,6 +3845,21 @@ function formatRules(rules) {
 
 ${text3.trim()}`;
 }
+async function findDocs(api, taskDescription) {
+  const query = taskDescription.trim().slice(0, MAX_QUERY_CHARS);
+  if (query) {
+    try {
+      const found = await api.get("/v1/docs", {
+        q: query,
+        limit: String(SEARCH_RESULTS)
+      });
+      if (found.items.length > 0) return { ...found, searched: true };
+    } catch {
+    }
+  }
+  const listed = await api.get("/v1/docs");
+  return { ...listed, searched: false };
+}
 async function fetchSpecBody(api, draftId) {
   const spec = await api.get(
     `/v1/specs/${encodeURIComponent(draftId)}`
@@ -3841,7 +3938,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const [rawGuardrails, rawSpecs, docs, stack, rules, docRepos] = await Promise.all([
     api.get("/v1/guardrails").catch(orEmpty([])),
     api.get("/v1/specs").catch(orEmpty([])),
-    api.get("/v1/docs").catch(orEmpty({ items: [] })),
+    findDocs(api, taskDescription).catch(
+      orEmpty({ items: [], searched: false })
+    ),
     api.get("/v1/ai/settings/stack").catch(orEmpty([])),
     api.get("/v1/standards/rules").catch(orEmpty([])),
     // Capability states — FAIL-OPEN: an unreadable config (older backend, a
@@ -3854,6 +3953,8 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const specs = disabled("requirements") && disabled("design") && disabled("specs") ? [] : rawSpecs;
   const refs = /* @__PURE__ */ new Map();
   const key = (type, id) => `${type}:${id}`;
+  const docTitles = new Set(docs.items.map((d) => d.title));
+  const isCopyOfDoc = (s) => isDecisionDraft(s.name) && docTitles.has(s.name.slice("ADR: ".length));
   const scorable = [
     ...guardrails.map((g) => ({
       type: "guardrail",
@@ -3864,12 +3965,12 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       severity: g.severity,
       updatedAt: g.updatedAt
     })),
-    ...specs.filter((s) => s.status !== "archived").map((s) => {
+    ...specs.filter((s) => s.status !== "archived" && !isCopyOfDoc(s)).map((s) => {
       refs.set(key("spec", s.draftId), {
         type: "spec",
         id: s.draftId,
         title: s.name,
-        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${s.requirementCount} requirements)`,
+        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${specLabel(s)})`,
         fetchHint: `get_specs(draft_id="${s.draftId}")`
       });
       return {
@@ -3880,7 +3981,7 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         updatedAt: s.updatedAt
       };
     }),
-    ...docs.items.map((d) => {
+    ...docs.items.map((d, position) => {
       const section = selectSection(d.outline, taskDescription);
       const pointer = section ? formatSectionPointer(d.repo_full_name, d.path, section) : void 0;
       refs.set(key("doc", d.id), {
@@ -3899,7 +4000,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         title: d.title,
         content: formatDocHeadline(d),
         category: d.doc_type === "adr" ? "architecture" : void 0,
-        updatedAt: d.synced_at
+        updatedAt: d.synced_at,
+        path: d.path,
+        relevance: docs.searched ? 1 - position / (2 * docs.items.length) : void 0
       };
     })
   ];
@@ -3907,9 +4010,16 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const sections = [];
   let overhead = 0;
   if (stack.length > 0) {
+    const { text: text3, hidden } = selectStack(
+      stack,
+      [...extractKeywords(taskDescription), ...detectLanguages(filePaths)],
+      Math.floor(budget * STACK_SHARE)
+    );
     const section = `## Tech Stack
 
-${formatStack(stack)}`;
+${text3}` + (hidden > 0 ? `
+
+_${hidden} more with \`get_tech_stack\`._` : "");
     sections.push(section);
     overhead += estimateTokens(section);
   }
@@ -4028,9 +4138,10 @@ _Highest-ranked items \u2014 docs are scoped to their most relevant section. Eac
   const tailLines = [];
   for (const meta of tailCandidates) {
     const cost = estimateTokens(meta.listLine);
-    if (cost > remaining) break;
+    const named = blocks.length + tailLines.length;
+    if (cost > remaining && named >= MIN_REFERENCES) break;
     tailLines.push(meta.listLine);
-    remaining -= cost;
+    remaining = Math.max(0, remaining - cost);
   }
   if (tailLines.length > 0) {
     sections.push(
@@ -4064,11 +4175,13 @@ _Ranked lower \u2014 fetch with \`get_specs\` / \`get_docs\` if you need them._
 _Context: ${itemsWithBody} full text, ${itemsListed} listed, ${stats.itemsOmitted} omitted \xB7 ~${tokensUsed} of ${budget} tokens` + (bodyFailures > 0 ? ` \xB7 ${bodyFailures} body fetch(es) failed` : "") + (failures.length > 0 ? ` \xB7 ${failures.length} of 5 reads failed` : "") + `_`;
   return { text: body + footer, stats };
 }
-var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS, SECTION_STOP_WORDS;
+var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS, STACK_SHARE, MIN_REFERENCES, SEARCH_RESULTS, MAX_QUERY_CHARS, SECTION_STOP_WORDS;
 var init_context_builder = __esm({
   "src/lib/context-builder.ts"() {
     "use strict";
+    init_language();
     init_scoring();
+    init_spec_label();
     init_scoring();
     DEFAULT_BUDGET = 4e3;
     RESERVE_TOKENS = 200;
@@ -4078,6 +4191,10 @@ var init_context_builder = __esm({
     MAX_TAIL = 10;
     TAIL_SHARE = 0.15;
     TRUNCATION_NOTICE_TOKENS = 30;
+    STACK_SHARE = 0.1;
+    MIN_REFERENCES = 3;
+    SEARCH_RESULTS = 30;
+    MAX_QUERY_CHARS = 300;
     SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
       "the",
       "a",
@@ -4953,7 +5070,7 @@ ${fence}
 ${f.content}${f.content.endsWith("\n") ? "" : "\n"}${fence}`;
       }).join("\n\n");
       return text(
-        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content, and tell the user to start a new Claude Code session.
+        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content. ${afterInstall(`${dest}/SKILL.md`)}
 
 ### ${MANIFEST_FILE}
 
@@ -5229,7 +5346,7 @@ var init_server = __esm({
     init_create_prompt_template();
     init_skills2();
     init_team_setup();
-    SERVER_VERSION = true ? "0.1.50" : "0.0.0-dev";
+    SERVER_VERSION = true ? "0.1.52" : "0.0.0-dev";
   }
 });