@systemdox/mcp-server 0.1.11 → 0.1.13

package/README.md

@@ -20,13 +20,21 @@ HTTP. Point any HTTP-capable MCP client at it — nothing to install or update.
       "type": "http",
       "url": "https://<your-workspace>.mcp.systemdox.com/mcp",
       "headers": {
-        "Authorization": "Bearer pweb_prod_key_..."
+        // Reference the key via an env var — never commit the literal key.
+        "Authorization": "Bearer ${SYSTEMDOX_API_KEY}"
       }
     }
   }
 }
 ```
 
+> **Never commit the literal key.** The `pweb_` prefix is deliberately scanner-friendly,
+> and a key in a committed `.mcp.json` is a long-lived read/write credential retained in
+> git history across every clone, fork, and CI log. MCP clients that expand environment
+> variables in `.mcp.json` (e.g. Claude Code) resolve `${SYSTEMDOX_API_KEY}` at load time;
+> deliver the value from your shell, a secret manager, or your CI secret store. For clients
+> that don't expand variables, inject the key at deploy time and keep the file untracked.
+
 - **URL** — `https://<your-workspace>.mcp.systemdox.com/mcp`. `<your-workspace>`
   is your tenant's **slug**; it must match the tenant that owns the API key, or
   the request is rejected `403`. Set a slug on the workspace first (owner/admin →
@@ -35,6 +43,11 @@ HTTP. Point any HTTP-capable MCP client at it — nothing to install or update.
   `X-API-Key`-only request is rejected at the gateway.)
 - **Transport** — stateless request/response (JSON); each call is independent,
   which suits serverless hosting. There is no long-lived SSE stream.
+- **Scope** — the key is the boundary. A key bound to a single space (a
+  "department" key) sees only that space's context; org-wide planner endpoints
+  (`get_planning_context`) are barred to it and answer `403`. Give each
+  department's repo its own key via `${SYSTEMDOX_API_KEY}`, and an agent in one
+  department never sees another's checks, specs, or docs.
 
 ## Option B — Local (stdio) via npx
 
@@ -54,7 +67,8 @@ npx @systemdox/mcp-server setup
       "command": "npx",
       "args": ["@systemdox/mcp-server"],
       "env": {
-        "SYSTEMDOX_API_KEY": "pweb_prod_key_..."
+        // Provided by your shell / secret store — not committed in the file.
+        "SYSTEMDOX_API_KEY": "${SYSTEMDOX_API_KEY}"
       }
     }
   }

package/dist/cli.js

@@ -444,20 +444,28 @@ function registerGetDocs(server2, apiClient2) {
     "get_docs",
     {
       title: "Get Docs",
-      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search.",
+      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search. Pass doc_id with section (a heading anchor) or chunk_id to retrieve just that section instead of the whole document.",
       inputSchema: {
         repo: z3.string().optional().describe("Filter by repo (owner/repo format)"),
         path: z3.string().optional().describe("File path glob pattern (e.g., docs/adr/*.md)"),
         search: z3.string().optional().describe("Keyword search across document content"),
         doc_id: z3.string().optional().describe(
           "Specific document ID to retrieve full content"
+        ),
+        section: z3.string().optional().describe(
+          "Heading anchor (e.g. 'rollback-strategy') \u2014 with doc_id, returns just that section"
+        ),
+        chunk_id: z3.string().optional().describe(
+          "Section chunk id ('{path_hash}#{anchor}') from get_context \u2014 with doc_id, returns just that section"
         )
       }
     },
-    async ({ repo, path, search, doc_id }) => {
+    async ({ repo, path, search, doc_id, section, chunk_id }) => {
       if (doc_id) {
+        const anchor = section ?? (chunk_id ? chunk_id.split("#").pop() : void 0);
         const doc = await apiClient2.get(
-          `/v1/docs/${encodeURIComponent(doc_id)}/content`
+          `/v1/docs/${encodeURIComponent(doc_id)}/content`,
+          anchor ? { section: anchor } : void 0
         );
         if (doc.error) {
           return {
@@ -470,8 +478,18 @@ function registerGetDocs(server2, apiClient2) {
             isError: true
           };
         }
+        let text2 = doc.content;
+        if (anchor && doc.section_resolved === false) {
+          text2 = `_Section "${anchor}" not found \u2014 returning the full document._
+
+` + text2;
+        } else if (anchor && doc.heading) {
+          text2 = `## ${doc.heading}
+
+${doc.content}`;
+        }
         return {
-          content: [{ type: "text", text: doc.content }]
+          content: [{ type: "text", text: text2 }]
         };
       }
       const params = {};
@@ -495,10 +513,14 @@ function registerGetDocs(server2, apiClient2) {
           ]
         };
       }
-      const text = items.map(
-        (d) => `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})` + (d.snippet ? `
-  > ${d.snippet}` : "")
-      ).join("\n");
+      const text = items.map((d) => {
+        const sections = (d.outline ?? []).slice(0, 8);
+        const sectionHint = sections.length > 0 ? `
+  sections: ${sections.map((s) => s.anchor).join(", ")}` : "";
+        return `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})
+  doc_id: \`${d.id}\`` + (d.snippet ? `
+  > ${d.snippet}` : "") + sectionHint;
+      }).join("\n");
       return {
         content: [
           {
@@ -507,7 +529,7 @@ function registerGetDocs(server2, apiClient2) {
 
 ${text}
 
-Use doc_id to retrieve full content.`
+Use doc_id for full content, or doc_id + section to fetch one section.`
           }
         ]
       };
@@ -908,18 +930,41 @@ ${spec.taskContent}`);
   if (!body) throw new Error("spec has no content");
   return body;
 }
-async function fetchDocBody(api, docId) {
+async function fetchDocBody(api, docId, anchor) {
   const doc = await api.get(
-    `/v1/docs/${encodeURIComponent(docId)}/content`
+    `/v1/docs/${encodeURIComponent(docId)}/content`,
+    anchor ? { section: anchor } : void 0
   );
   if (doc.error) throw new Error(doc.error);
   const body = (doc.content ?? "").trim();
   if (!body) throw new Error("document is empty");
   return body;
 }
+function githubDeepLink(repoFullName, path, anchor) {
+  return `https://github.com/${repoFullName}/blob/HEAD/${path}#${anchor}`;
+}
+function formatSectionPointer(repoFullName, path, s) {
+  return `\`${path}#${s.anchor}\` \xB7 \`chunk_id: ${s.chunkId}\` \xB7 [${s.heading}](${githubDeepLink(repoFullName, path, s.anchor)})`;
+}
+function selectSection(outline, taskDescription) {
+  if (!outline || outline.length === 0) return void 0;
+  const keywords = taskDescription.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !SECTION_STOP_WORDS.has(w));
+  let best = outline[0];
+  let bestScore = -1;
+  for (const s of outline) {
+    const heading = s.heading.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) if (heading.includes(kw)) score++;
+    if (score > bestScore) {
+      best = s;
+      bestScore = score;
+    }
+  }
+  return best;
+}
 async function hydrate(api, item, meta) {
   try {
-    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id);
+    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id, meta.section?.anchor);
     return { item, meta, body };
   } catch (err) {
     return {
@@ -967,12 +1012,17 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       };
     }),
     ...docs.items.map((d) => {
+      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), {
         type: "doc",
         id: d.id,
         title: d.title,
-        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)`,
-        fetchHint: `get_docs(doc_id="${d.id}")`
+        section,
+        pointer,
+        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)` + (pointer ? `
+  \u21B3 ${pointer}` : ""),
+        fetchHint: section ? `get_docs(doc_id="${d.id}", section="${section.anchor}")` : `get_docs(doc_id="${d.id}")`
       });
       return {
         type: "doc",
@@ -1045,6 +1095,8 @@ ${formatStack(stack)}`;
   const blocks = [];
   for (const h of hydrated) {
     itemsLeft--;
+    const headline = h.meta.pointer ? `${h.item.content}
+${h.meta.pointer}` : h.item.content;
     const emit = (block) => {
       bodyBudget -= Math.max(
         0,
@@ -1055,7 +1107,7 @@ ${formatStack(stack)}`;
     if (h.error !== void 0) {
       bodyFailures++;
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
       );
@@ -1068,7 +1120,7 @@ _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
     );
     if (allowance < MIN_BODY_TOKENS) {
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`._`
       );
@@ -1080,7 +1132,7 @@ _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`
     );
     itemsWithBody++;
     emit(
-      `${h.item.content}
+      `${headline}
 
 ${body2}` + (truncated ? `
 
@@ -1099,7 +1151,7 @@ _[truncated to fit the token budget \u2014 full text via \`${h.meta.fetchHint}\`
     sections.push(
       `## Relevant Specs & Docs (${blocks.length})
 
-_Full text of the highest-ranked items. Every item carries the ID to fetch it in full._
+_Highest-ranked items \u2014 docs are scoped to their most relevant section. Each carries the ID / \`chunk_id\` to fetch more._
 
 ` + blocks.join("\n\n---\n\n")
     );
@@ -1142,7 +1194,7 @@ _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` : "") + `_`;
   return { text: body + footer, stats };
 }
-var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS;
+var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS, SECTION_STOP_WORDS;
 var init_context_builder = __esm({
   "src/lib/context-builder.ts"() {
     "use strict";
@@ -1156,6 +1208,28 @@ var init_context_builder = __esm({
     MAX_TAIL = 10;
     TAIL_SHARE = 0.15;
     TRUNCATION_NOTICE_TOKENS = 30;
+    SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "of",
+      "to",
+      "and",
+      "or",
+      "for",
+      "in",
+      "on",
+      "with",
+      "how",
+      "why",
+      "what",
+      "add",
+      "new",
+      "use",
+      "using",
+      "update",
+      "fix"
+    ]);
   }
 });
 

package/dist/http.js

@@ -384,20 +384,28 @@ function registerGetDocs(server, apiClient) {
     "get_docs",
     {
       title: "Get Docs",
-      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search.",
+      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search. Pass doc_id with section (a heading anchor) or chunk_id to retrieve just that section instead of the whole document.",
       inputSchema: {
         repo: z3.string().optional().describe("Filter by repo (owner/repo format)"),
         path: z3.string().optional().describe("File path glob pattern (e.g., docs/adr/*.md)"),
         search: z3.string().optional().describe("Keyword search across document content"),
         doc_id: z3.string().optional().describe(
           "Specific document ID to retrieve full content"
+        ),
+        section: z3.string().optional().describe(
+          "Heading anchor (e.g. 'rollback-strategy') \u2014 with doc_id, returns just that section"
+        ),
+        chunk_id: z3.string().optional().describe(
+          "Section chunk id ('{path_hash}#{anchor}') from get_context \u2014 with doc_id, returns just that section"
         )
       }
     },
-    async ({ repo, path, search, doc_id }) => {
+    async ({ repo, path, search, doc_id, section, chunk_id }) => {
       if (doc_id) {
+        const anchor = section ?? (chunk_id ? chunk_id.split("#").pop() : void 0);
         const doc = await apiClient.get(
-          `/v1/docs/${encodeURIComponent(doc_id)}/content`
+          `/v1/docs/${encodeURIComponent(doc_id)}/content`,
+          anchor ? { section: anchor } : void 0
         );
         if (doc.error) {
           return {
@@ -410,8 +418,18 @@ function registerGetDocs(server, apiClient) {
             isError: true
           };
         }
+        let text2 = doc.content;
+        if (anchor && doc.section_resolved === false) {
+          text2 = `_Section "${anchor}" not found \u2014 returning the full document._
+
+` + text2;
+        } else if (anchor && doc.heading) {
+          text2 = `## ${doc.heading}
+
+${doc.content}`;
+        }
         return {
-          content: [{ type: "text", text: doc.content }]
+          content: [{ type: "text", text: text2 }]
         };
       }
       const params = {};
@@ -435,10 +453,14 @@ function registerGetDocs(server, apiClient) {
           ]
         };
       }
-      const text = items.map(
-        (d) => `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})` + (d.snippet ? `
-  > ${d.snippet}` : "")
-      ).join("\n");
+      const text = items.map((d) => {
+        const sections = (d.outline ?? []).slice(0, 8);
+        const sectionHint = sections.length > 0 ? `
+  sections: ${sections.map((s) => s.anchor).join(", ")}` : "";
+        return `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})
+  doc_id: \`${d.id}\`` + (d.snippet ? `
+  > ${d.snippet}` : "") + sectionHint;
+      }).join("\n");
       return {
         content: [
           {
@@ -447,7 +469,7 @@ function registerGetDocs(server, apiClient) {
 
 ${text}
 
-Use doc_id to retrieve full content.`
+Use doc_id for full content, or doc_id + section to fetch one section.`
           }
         ]
       };
@@ -837,18 +859,63 @@ ${spec.taskContent}`);
   if (!body) throw new Error("spec has no content");
   return body;
 }
-async function fetchDocBody(api, docId) {
+async function fetchDocBody(api, docId, anchor) {
   const doc = await api.get(
-    `/v1/docs/${encodeURIComponent(docId)}/content`
+    `/v1/docs/${encodeURIComponent(docId)}/content`,
+    anchor ? { section: anchor } : void 0
   );
   if (doc.error) throw new Error(doc.error);
   const body = (doc.content ?? "").trim();
   if (!body) throw new Error("document is empty");
   return body;
 }
+function githubDeepLink(repoFullName, path, anchor) {
+  return `https://github.com/${repoFullName}/blob/HEAD/${path}#${anchor}`;
+}
+function formatSectionPointer(repoFullName, path, s) {
+  return `\`${path}#${s.anchor}\` \xB7 \`chunk_id: ${s.chunkId}\` \xB7 [${s.heading}](${githubDeepLink(repoFullName, path, s.anchor)})`;
+}
+var SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "to",
+  "and",
+  "or",
+  "for",
+  "in",
+  "on",
+  "with",
+  "how",
+  "why",
+  "what",
+  "add",
+  "new",
+  "use",
+  "using",
+  "update",
+  "fix"
+]);
+function selectSection(outline, taskDescription) {
+  if (!outline || outline.length === 0) return void 0;
+  const keywords = taskDescription.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !SECTION_STOP_WORDS.has(w));
+  let best = outline[0];
+  let bestScore = -1;
+  for (const s of outline) {
+    const heading = s.heading.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) if (heading.includes(kw)) score++;
+    if (score > bestScore) {
+      best = s;
+      bestScore = score;
+    }
+  }
+  return best;
+}
 async function hydrate(api, item, meta) {
   try {
-    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id);
+    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id, meta.section?.anchor);
     return { item, meta, body };
   } catch (err) {
     return {
@@ -896,12 +963,17 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       };
     }),
     ...docs.items.map((d) => {
+      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), {
         type: "doc",
         id: d.id,
         title: d.title,
-        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)`,
-        fetchHint: `get_docs(doc_id="${d.id}")`
+        section,
+        pointer,
+        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)` + (pointer ? `
+  \u21B3 ${pointer}` : ""),
+        fetchHint: section ? `get_docs(doc_id="${d.id}", section="${section.anchor}")` : `get_docs(doc_id="${d.id}")`
       });
       return {
         type: "doc",
@@ -974,6 +1046,8 @@ ${formatStack(stack)}`;
   const blocks = [];
   for (const h of hydrated) {
     itemsLeft--;
+    const headline = h.meta.pointer ? `${h.item.content}
+${h.meta.pointer}` : h.item.content;
     const emit = (block) => {
       bodyBudget -= Math.max(
         0,
@@ -984,7 +1058,7 @@ ${formatStack(stack)}`;
     if (h.error !== void 0) {
       bodyFailures++;
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
       );
@@ -997,7 +1071,7 @@ _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
     );
     if (allowance < MIN_BODY_TOKENS) {
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`._`
       );
@@ -1009,7 +1083,7 @@ _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`
     );
     itemsWithBody++;
     emit(
-      `${h.item.content}
+      `${headline}
 
 ${body2}` + (truncated ? `
 
@@ -1028,7 +1102,7 @@ _[truncated to fit the token budget \u2014 full text via \`${h.meta.fetchHint}\`
     sections.push(
       `## Relevant Specs & Docs (${blocks.length})
 
-_Full text of the highest-ranked items. Every item carries the ID to fetch it in full._
+_Highest-ranked items \u2014 docs are scoped to their most relevant section. Each carries the ID / \`chunk_id\` to fetch more._
 
 ` + blocks.join("\n\n---\n\n")
     );

package/dist/index.js

@@ -400,20 +400,28 @@ function registerGetDocs(server2, apiClient2) {
     "get_docs",
     {
       title: "Get Docs",
-      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search.",
+      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search. Pass doc_id with section (a heading anchor) or chunk_id to retrieve just that section instead of the whole document.",
       inputSchema: {
         repo: z3.string().optional().describe("Filter by repo (owner/repo format)"),
         path: z3.string().optional().describe("File path glob pattern (e.g., docs/adr/*.md)"),
         search: z3.string().optional().describe("Keyword search across document content"),
         doc_id: z3.string().optional().describe(
           "Specific document ID to retrieve full content"
+        ),
+        section: z3.string().optional().describe(
+          "Heading anchor (e.g. 'rollback-strategy') \u2014 with doc_id, returns just that section"
+        ),
+        chunk_id: z3.string().optional().describe(
+          "Section chunk id ('{path_hash}#{anchor}') from get_context \u2014 with doc_id, returns just that section"
         )
       }
     },
-    async ({ repo, path, search, doc_id }) => {
+    async ({ repo, path, search, doc_id, section, chunk_id }) => {
       if (doc_id) {
+        const anchor = section ?? (chunk_id ? chunk_id.split("#").pop() : void 0);
         const doc = await apiClient2.get(
-          `/v1/docs/${encodeURIComponent(doc_id)}/content`
+          `/v1/docs/${encodeURIComponent(doc_id)}/content`,
+          anchor ? { section: anchor } : void 0
         );
         if (doc.error) {
           return {
@@ -426,8 +434,18 @@ function registerGetDocs(server2, apiClient2) {
             isError: true
           };
         }
+        let text2 = doc.content;
+        if (anchor && doc.section_resolved === false) {
+          text2 = `_Section "${anchor}" not found \u2014 returning the full document._
+
+` + text2;
+        } else if (anchor && doc.heading) {
+          text2 = `## ${doc.heading}
+
+${doc.content}`;
+        }
         return {
-          content: [{ type: "text", text: doc.content }]
+          content: [{ type: "text", text: text2 }]
         };
       }
       const params = {};
@@ -451,10 +469,14 @@ function registerGetDocs(server2, apiClient2) {
           ]
         };
       }
-      const text = items.map(
-        (d) => `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})` + (d.snippet ? `
-  > ${d.snippet}` : "")
-      ).join("\n");
+      const text = items.map((d) => {
+        const sections = (d.outline ?? []).slice(0, 8);
+        const sectionHint = sections.length > 0 ? `
+  sections: ${sections.map((s) => s.anchor).join(", ")}` : "";
+        return `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})
+  doc_id: \`${d.id}\`` + (d.snippet ? `
+  > ${d.snippet}` : "") + sectionHint;
+      }).join("\n");
       return {
         content: [
           {
@@ -463,7 +485,7 @@ function registerGetDocs(server2, apiClient2) {
 
 ${text}
 
-Use doc_id to retrieve full content.`
+Use doc_id for full content, or doc_id + section to fetch one section.`
           }
         ]
       };
@@ -853,18 +875,63 @@ ${spec.taskContent}`);
   if (!body) throw new Error("spec has no content");
   return body;
 }
-async function fetchDocBody(api, docId) {
+async function fetchDocBody(api, docId, anchor) {
   const doc = await api.get(
-    `/v1/docs/${encodeURIComponent(docId)}/content`
+    `/v1/docs/${encodeURIComponent(docId)}/content`,
+    anchor ? { section: anchor } : void 0
   );
   if (doc.error) throw new Error(doc.error);
   const body = (doc.content ?? "").trim();
   if (!body) throw new Error("document is empty");
   return body;
 }
+function githubDeepLink(repoFullName, path, anchor) {
+  return `https://github.com/${repoFullName}/blob/HEAD/${path}#${anchor}`;
+}
+function formatSectionPointer(repoFullName, path, s) {
+  return `\`${path}#${s.anchor}\` \xB7 \`chunk_id: ${s.chunkId}\` \xB7 [${s.heading}](${githubDeepLink(repoFullName, path, s.anchor)})`;
+}
+var SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "to",
+  "and",
+  "or",
+  "for",
+  "in",
+  "on",
+  "with",
+  "how",
+  "why",
+  "what",
+  "add",
+  "new",
+  "use",
+  "using",
+  "update",
+  "fix"
+]);
+function selectSection(outline, taskDescription) {
+  if (!outline || outline.length === 0) return void 0;
+  const keywords = taskDescription.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !SECTION_STOP_WORDS.has(w));
+  let best = outline[0];
+  let bestScore = -1;
+  for (const s of outline) {
+    const heading = s.heading.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) if (heading.includes(kw)) score++;
+    if (score > bestScore) {
+      best = s;
+      bestScore = score;
+    }
+  }
+  return best;
+}
 async function hydrate(api, item, meta) {
   try {
-    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id);
+    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id, meta.section?.anchor);
     return { item, meta, body };
   } catch (err) {
     return {
@@ -912,12 +979,17 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       };
     }),
     ...docs.items.map((d) => {
+      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), {
         type: "doc",
         id: d.id,
         title: d.title,
-        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)`,
-        fetchHint: `get_docs(doc_id="${d.id}")`
+        section,
+        pointer,
+        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)` + (pointer ? `
+  \u21B3 ${pointer}` : ""),
+        fetchHint: section ? `get_docs(doc_id="${d.id}", section="${section.anchor}")` : `get_docs(doc_id="${d.id}")`
       });
       return {
         type: "doc",
@@ -990,6 +1062,8 @@ ${formatStack(stack)}`;
   const blocks = [];
   for (const h of hydrated) {
     itemsLeft--;
+    const headline = h.meta.pointer ? `${h.item.content}
+${h.meta.pointer}` : h.item.content;
     const emit = (block) => {
       bodyBudget -= Math.max(
         0,
@@ -1000,7 +1074,7 @@ ${formatStack(stack)}`;
     if (h.error !== void 0) {
       bodyFailures++;
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
       );
@@ -1013,7 +1087,7 @@ _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
     );
     if (allowance < MIN_BODY_TOKENS) {
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`._`
       );
@@ -1025,7 +1099,7 @@ _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`
     );
     itemsWithBody++;
     emit(
-      `${h.item.content}
+      `${headline}
 
 ${body2}` + (truncated ? `
 
@@ -1044,7 +1118,7 @@ _[truncated to fit the token budget \u2014 full text via \`${h.meta.fetchHint}\`
     sections.push(
       `## Relevant Specs & Docs (${blocks.length})
 
-_Full text of the highest-ranked items. Every item carries the ID to fetch it in full._
+_Highest-ranked items \u2014 docs are scoped to their most relevant section. Each carries the ID / \`chunk_id\` to fetch more._
 
 ` + blocks.join("\n\n---\n\n")
     );

package/dist/lib/context-builder.d.ts

@@ -23,6 +23,13 @@ export interface SpecSummary {
     requirementCount: number;
     updatedAt: string;
 }
+/** One heading-scoped section of a document (#865). */
+export interface DocSection {
+    heading: string;
+    level: number;
+    anchor: string;
+    chunkId: string;
+}
 export interface DocListResponse {
     items: Array<{
         id: string;
@@ -32,6 +39,8 @@ export interface DocListResponse {
         doc_type: string;
         size: number;
         synced_at: string;
+        /** Structured section outline, when the doc has been re-indexed (#865). */
+        outline?: DocSection[];
     }>;
 }
 export interface TechStackEntry {

package/dist/lib/context-builder.js

@@ -335,18 +335,63 @@ ${spec.taskContent}`);
   if (!body) throw new Error("spec has no content");
   return body;
 }
-async function fetchDocBody(api, docId) {
+async function fetchDocBody(api, docId, anchor) {
   const doc = await api.get(
-    `/v1/docs/${encodeURIComponent(docId)}/content`
+    `/v1/docs/${encodeURIComponent(docId)}/content`,
+    anchor ? { section: anchor } : void 0
   );
   if (doc.error) throw new Error(doc.error);
   const body = (doc.content ?? "").trim();
   if (!body) throw new Error("document is empty");
   return body;
 }
+function githubDeepLink(repoFullName, path, anchor) {
+  return `https://github.com/${repoFullName}/blob/HEAD/${path}#${anchor}`;
+}
+function formatSectionPointer(repoFullName, path, s) {
+  return `\`${path}#${s.anchor}\` \xB7 \`chunk_id: ${s.chunkId}\` \xB7 [${s.heading}](${githubDeepLink(repoFullName, path, s.anchor)})`;
+}
+var SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "of",
+  "to",
+  "and",
+  "or",
+  "for",
+  "in",
+  "on",
+  "with",
+  "how",
+  "why",
+  "what",
+  "add",
+  "new",
+  "use",
+  "using",
+  "update",
+  "fix"
+]);
+function selectSection(outline, taskDescription) {
+  if (!outline || outline.length === 0) return void 0;
+  const keywords = taskDescription.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !SECTION_STOP_WORDS.has(w));
+  let best = outline[0];
+  let bestScore = -1;
+  for (const s of outline) {
+    const heading = s.heading.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) if (heading.includes(kw)) score++;
+    if (score > bestScore) {
+      best = s;
+      bestScore = score;
+    }
+  }
+  return best;
+}
 async function hydrate(api, item, meta) {
   try {
-    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id);
+    const body = meta.type === "spec" ? await fetchSpecBody(api, meta.id) : await fetchDocBody(api, meta.id, meta.section?.anchor);
     return { item, meta, body };
   } catch (err) {
     return {
@@ -394,12 +439,17 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       };
     }),
     ...docs.items.map((d) => {
+      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), {
         type: "doc",
         id: d.id,
         title: d.title,
-        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)`,
-        fetchHint: `get_docs(doc_id="${d.id}")`
+        section,
+        pointer,
+        listLine: `- **${d.title}** \u2014 \`doc_id: ${d.id}\` (\`${d.repo_full_name}/${d.path}\`)` + (pointer ? `
+  \u21B3 ${pointer}` : ""),
+        fetchHint: section ? `get_docs(doc_id="${d.id}", section="${section.anchor}")` : `get_docs(doc_id="${d.id}")`
       });
       return {
         type: "doc",
@@ -472,6 +522,8 @@ ${formatStack(stack)}`;
   const blocks = [];
   for (const h of hydrated) {
     itemsLeft--;
+    const headline = h.meta.pointer ? `${h.item.content}
+${h.meta.pointer}` : h.item.content;
     const emit = (block) => {
       bodyBudget -= Math.max(
         0,
@@ -482,7 +534,7 @@ ${formatStack(stack)}`;
     if (h.error !== void 0) {
       bodyFailures++;
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
       );
@@ -495,7 +547,7 @@ _Body unavailable (${h.error}) \u2014 retry with \`${h.meta.fetchHint}\`._`
     );
     if (allowance < MIN_BODY_TOKENS) {
       emit(
-        `${h.item.content}
+        `${headline}
 
 _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`._`
       );
@@ -507,7 +559,7 @@ _Body omitted (token budget exhausted) \u2014 fetch with \`${h.meta.fetchHint}\`
     );
     itemsWithBody++;
     emit(
-      `${h.item.content}
+      `${headline}
 
 ${body2}` + (truncated ? `
 
@@ -526,7 +578,7 @@ _[truncated to fit the token budget \u2014 full text via \`${h.meta.fetchHint}\`
     sections.push(
       `## Relevant Specs & Docs (${blocks.length})
 
-_Full text of the highest-ranked items. Every item carries the ID to fetch it in full._
+_Highest-ranked items \u2014 docs are scoped to their most relevant section. Each carries the ID / \`chunk_id\` to fetch more._
 
 ` + blocks.join("\n\n---\n\n")
     );

package/dist/tools/get-docs.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+// src/tools/get-docs.ts
+import { z } from "zod";
+function matchGlob(path, pattern) {
+  const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regex}$`).test(path);
+}
+function registerGetDocs(server, apiClient) {
+  server.registerTool(
+    "get_docs",
+    {
+      title: "Get Docs",
+      description: "Retrieve synced documentation from connected GitHub repositories. Filter by repo, file path pattern, or keyword search. Pass doc_id with section (a heading anchor) or chunk_id to retrieve just that section instead of the whole document.",
+      inputSchema: {
+        repo: z.string().optional().describe("Filter by repo (owner/repo format)"),
+        path: z.string().optional().describe("File path glob pattern (e.g., docs/adr/*.md)"),
+        search: z.string().optional().describe("Keyword search across document content"),
+        doc_id: z.string().optional().describe(
+          "Specific document ID to retrieve full content"
+        ),
+        section: z.string().optional().describe(
+          "Heading anchor (e.g. 'rollback-strategy') \u2014 with doc_id, returns just that section"
+        ),
+        chunk_id: z.string().optional().describe(
+          "Section chunk id ('{path_hash}#{anchor}') from get_context \u2014 with doc_id, returns just that section"
+        )
+      }
+    },
+    async ({ repo, path, search, doc_id, section, chunk_id }) => {
+      if (doc_id) {
+        const anchor = section ?? (chunk_id ? chunk_id.split("#").pop() : void 0);
+        const doc = await apiClient.get(
+          `/v1/docs/${encodeURIComponent(doc_id)}/content`,
+          anchor ? { section: anchor } : void 0
+        );
+        if (doc.error) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error retrieving document: ${doc.error}`
+              }
+            ],
+            isError: true
+          };
+        }
+        let text2 = doc.content;
+        if (anchor && doc.section_resolved === false) {
+          text2 = `_Section "${anchor}" not found \u2014 returning the full document._
+
+` + text2;
+        } else if (anchor && doc.heading) {
+          text2 = `## ${doc.heading}
+
+${doc.content}`;
+        }
+        return {
+          content: [{ type: "text", text: text2 }]
+        };
+      }
+      const params = {};
+      if (repo) params.repo = repo;
+      if (search) params.q = search;
+      const response = await apiClient.get(
+        "/v1/docs",
+        params
+      );
+      let items = response.items;
+      if (path) {
+        items = items.filter((item) => matchGlob(item.path, path));
+      }
+      if (items.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No documents found${repo ? ` in ${repo}` : ""}${path ? ` matching "${path}"` : ""}${search ? ` for "${search}"` : ""}.`
+            }
+          ]
+        };
+      }
+      const text = items.map((d) => {
+        const sections = (d.outline ?? []).slice(0, 8);
+        const sectionHint = sections.length > 0 ? `
+  sections: ${sections.map((s) => s.anchor).join(", ")}` : "";
+        return `- **${d.title}** \u2014 \`${d.repo_full_name}/${d.path}\` (${d.doc_type}, ${d.size} bytes, synced ${d.synced_at})
+  doc_id: \`${d.id}\`` + (d.snippet ? `
+  > ${d.snippet}` : "") + sectionHint;
+      }).join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${items.length} document(s) (${response.total} total):
+
+${text}
+
+Use doc_id for full content, or doc_id + section to fetch one section.`
+          }
+        ]
+      };
+    }
+  );
+}
+export {
+  registerGetDocs
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@systemdox/mcp-server",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "MCP server that exposes SystemDox checks, specs, docs, and tech stack to AI coding tools",
   "main": "./dist/index.js",