claude-code-ultimate-guide-mcp 1.0.4 → 1.1.0

package/dist/index.js

@@ -15125,6 +15125,555 @@ function registerSearchExamples(server) {
   );
 }
 
+// src/lib/docs-cache.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { resolve } from "path";
+var ANTHROPIC_DOCS_URL = "https://code.claude.com/docs/llms-full.txt";
+var SNAPSHOT_DIR = resolve(homedir(), ".cache", "claude-code-guide");
+function getSnapshotDir() {
+  return SNAPSHOT_DIR;
+}
+function indexPath(type) {
+  return resolve(SNAPSHOT_DIR, `anthropic-docs-${type}-index.json`);
+}
+function contentPath(type) {
+  return resolve(SNAPSHOT_DIR, `anthropic-docs-${type}-content.json`);
+}
+async function fetchOfficialDocs() {
+  const response = await fetch(ANTHROPIC_DOCS_URL, {
+    headers: { "User-Agent": "claude-code-ultimate-guide-mcp/1.1.0" },
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} fetching ${ANTHROPIC_DOCS_URL}`);
+  }
+  const text = await response.text();
+  if (text.length < 5e5) {
+    throw new Error(
+      `Response looks malformed (got ${(text.length / 1024).toFixed(0)}KB, expected >500KB). The URL format may have changed.`
+    );
+  }
+  return text;
+}
+function parseIntoSections(raw) {
+  const lines = raw.split("\n");
+  const sections = {};
+  const contents = {};
+  let currentSlug = null;
+  let currentTitle = null;
+  let currentSourceUrl = null;
+  let currentStartLine = 0;
+  let titleCandidate = null;
+  let titleCandidateLine = -1;
+  const flushSection = (endLine) => {
+    if (!currentSlug || !currentTitle || !currentSourceUrl) return;
+    const sectionLines = lines.slice(currentStartLine, endLine);
+    const content2 = sectionLines.join("\n").trimEnd();
+    if (content2.length === 0) return;
+    const hash2 = createHash("sha256").update(content2).digest("hex").slice(0, 16);
+    sections[currentSlug] = {
+      slug: currentSlug,
+      title: currentTitle,
+      sourceUrl: currentSourceUrl,
+      hash: hash2,
+      lineCount: sectionLines.length,
+      charCount: content2.length
+    };
+    contents[currentSlug] = { content: content2 };
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("# ") && !line.startsWith("## ")) {
+      titleCandidate = line;
+      titleCandidateLine = i;
+      continue;
+    }
+    const sourceMatch = line.match(
+      /^Source:\s+(https:\/\/code\.claude\.com\/docs\/(?:en\/)?([a-zA-Z0-9-]+))\s*$/
+    );
+    if (sourceMatch && titleCandidate !== null && i === titleCandidateLine + 1) {
+      const sourceUrl = sourceMatch[1];
+      const slug = sourceMatch[2];
+      flushSection(titleCandidateLine);
+      currentSlug = slug;
+      currentTitle = titleCandidate;
+      currentSourceUrl = sourceUrl;
+      currentStartLine = titleCandidateLine;
+      titleCandidate = null;
+      titleCandidateLine = -1;
+      continue;
+    }
+    if (titleCandidate !== null && i > titleCandidateLine + 1) {
+      titleCandidate = null;
+      titleCandidateLine = -1;
+    }
+  }
+  flushSection(lines.length);
+  if (Object.keys(sections).length === 0) {
+    throw new Error(
+      "Section parser found 0 sections \u2014 llms-full.txt format may have changed. Please open an issue at https://github.com/FlorianBruniaux/claude-code-ultimate-guide"
+    );
+  }
+  const contentHash = createHash("sha256").update(raw).digest("hex").slice(0, 16);
+  const index = {
+    schemaVersion: 1,
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    contentHash,
+    sectionCount: Object.keys(sections).length,
+    sections
+  };
+  const content = {
+    schemaVersion: 1,
+    sections: contents
+  };
+  return { index, content };
+}
+function saveSnapshot(type, index, content) {
+  mkdirSync(SNAPSHOT_DIR, { recursive: true });
+  const iPath = indexPath(type);
+  writeFileSync(`${iPath}.tmp`, JSON.stringify(index, null, 2), "utf8");
+  renameSync(`${iPath}.tmp`, iPath);
+  const cPath = contentPath(type);
+  writeFileSync(`${cPath}.tmp`, JSON.stringify(content, null, 2), "utf8");
+  renameSync(`${cPath}.tmp`, cPath);
+}
+function loadIndex(type) {
+  const path = indexPath(type);
+  if (!existsSync2(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync2(path, "utf8"));
+    if (data.schemaVersion !== 1) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+function loadSections(type, slugs) {
+  const path = contentPath(type);
+  if (!existsSync2(path)) return {};
+  try {
+    const data = JSON.parse(readFileSync2(path, "utf8"));
+    const result = {};
+    for (const slug of slugs) {
+      const section = data.sections[slug];
+      if (section) result[slug] = section.content;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+function snapshotAgeDays(index) {
+  return Math.floor((Date.now() - new Date(index.fetchedAt).getTime()) / (1e3 * 60 * 60 * 24));
+}
+
+// src/lib/docs-diff.ts
+function diffSnapshots(baseline, current) {
+  const baselineSlugs = new Set(Object.keys(baseline.sections));
+  const currentSlugs = new Set(Object.keys(current.sections));
+  const added = [];
+  const removed = [];
+  const modified = [];
+  let unchanged = 0;
+  for (const slug of currentSlugs) {
+    if (!baselineSlugs.has(slug)) {
+      const s = current.sections[slug];
+      added.push({ slug, title: s.title, sourceUrl: s.sourceUrl, kind: "added" });
+    }
+  }
+  for (const slug of baselineSlugs) {
+    if (!currentSlugs.has(slug)) {
+      const s = baseline.sections[slug];
+      removed.push({ slug, title: s.title, sourceUrl: s.sourceUrl, kind: "removed" });
+    }
+  }
+  for (const slug of baselineSlugs) {
+    if (!currentSlugs.has(slug)) continue;
+    const base = baseline.sections[slug];
+    const curr = current.sections[slug];
+    if (base.hash === curr.hash) {
+      unchanged++;
+      continue;
+    }
+    modified.push({
+      slug,
+      title: curr.title,
+      sourceUrl: curr.sourceUrl,
+      kind: "modified",
+      linesBefore: base.lineCount,
+      linesAfter: curr.lineCount,
+      charsBefore: base.charCount,
+      charsAfter: curr.charCount,
+      lineDelta: curr.lineCount - base.lineCount
+      // firstChangedLine is enriched by the tool layer after loading content
+    });
+  }
+  return {
+    unchanged,
+    added,
+    removed,
+    modified,
+    baselineDate: baseline.fetchedAt,
+    currentDate: current.fetchedAt
+  };
+}
+function findFirstChangedLine(baseContent, currentContent) {
+  const baseLines = baseContent.split("\n");
+  const currLines = currentContent.split("\n");
+  const len = Math.min(baseLines.length, currLines.length);
+  for (let i = 0; i < len; i++) {
+    if (baseLines[i] !== currLines[i]) {
+      return currLines[i].slice(0, 120);
+    }
+  }
+  if (currLines.length > baseLines.length) {
+    return (currLines[baseLines.length] ?? "").slice(0, 120);
+  }
+  return "";
+}
+
+// src/tools/official-docs.ts
+var STALENESS_WARN_DAYS = 30;
+function formatDate(iso) {
+  return iso.slice(0, 10);
+}
+function formatSize(bytes) {
+  if (bytes >= 1e6) return `${(bytes / 1e6).toFixed(2)} MB`;
+  return `${(bytes / 1024).toFixed(0)} KB`;
+}
+function extractExcerpt(content, query, maxLen = 300) {
+  const lowerContent = content.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+  const idx = lowerContent.indexOf(lowerQuery);
+  if (idx === -1) {
+    const excerpt = content.slice(0, maxLen);
+    return excerpt + (content.length > maxLen ? "\u2026" : "");
+  }
+  const start = Math.max(0, idx - 100);
+  const end = Math.min(content.length, idx + query.length + 200);
+  const prefix = start > 0 ? "\u2026" : "";
+  const suffix = end < content.length ? "\u2026" : "";
+  return prefix + content.slice(start, end) + suffix;
+}
+function scoreSection(title, content, query) {
+  const q = query.toLowerCase();
+  const titleScore = title.toLowerCase().includes(q) ? 3 : 0;
+  const bodyScore = content.toLowerCase().includes(q) ? 1 : 0;
+  return titleScore + bodyScore;
+}
+function registerOfficialDocs(server) {
+  server.tool(
+    "init_official_docs",
+    "Fetch the official Anthropic Claude Code docs (llms-full.txt) and store a local snapshot as the diff baseline. Run this first. Safe to re-run \u2014 overwrites previous baseline AND current. Takes ~5s (fetches ~1.2MB from Anthropic).",
+    {},
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    async () => {
+      let raw;
+      try {
+        raw = await fetchOfficialDocs();
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to fetch official docs: ${err instanceof Error ? err.message : String(err)}
+
+Check network connectivity and retry.`
+          }],
+          isError: true
+        };
+      }
+      let parsed;
+      try {
+        parsed = parseIntoSections(raw);
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Parsing failed: ${err instanceof Error ? err.message : String(err)}`
+          }],
+          isError: true
+        };
+      }
+      try {
+        saveSnapshot("baseline", parsed.index, parsed.content);
+        saveSnapshot("current", parsed.index, parsed.content);
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to save snapshot to disk: ${err instanceof Error ? err.message : String(err)}
+
+Check that ${getSnapshotDir()} is writable.`
+          }],
+          isError: true
+        };
+      }
+      const { index } = parsed;
+      const totalChars = Object.values(index.sections).reduce((s, sec) => s + sec.charCount, 0);
+      const lines = [
+        "# Official Docs Snapshot Created",
+        "",
+        `Fetched: ${index.fetchedAt}`,
+        `Sections: ${index.sectionCount}`,
+        `Total size: ${formatSize(totalChars)}`,
+        `Snapshot dir: ${getSnapshotDir()}`,
+        "",
+        "Both baseline and current snapshots have been set.",
+        "",
+        "Next steps:",
+        "  - Run refresh_official_docs() to update current without touching the baseline",
+        "  - Run diff_official_docs() to see changes between baseline and current",
+        "  - Run search_official_docs(query) to search the official docs"
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "refresh_official_docs",
+    'Re-fetch the official Anthropic Claude Code docs and update the "current" snapshot without touching the baseline. Run this to update the comparison target before diffing. Takes ~5s (fetches ~1.2MB from Anthropic).',
+    {},
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    async () => {
+      const baseline = loadIndex("baseline");
+      if (!baseline) {
+        return {
+          content: [{
+            type: "text",
+            text: "No baseline snapshot found. Run init_official_docs() first to create both the baseline and the initial current snapshot."
+          }],
+          isError: true
+        };
+      }
+      let raw;
+      try {
+        raw = await fetchOfficialDocs();
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to fetch official docs: ${err instanceof Error ? err.message : String(err)}
+
+Your existing snapshots are intact.`
+          }],
+          isError: true
+        };
+      }
+      let parsed;
+      try {
+        parsed = parseIntoSections(raw);
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Parsing failed: ${err instanceof Error ? err.message : String(err)}
+
+Your existing snapshots are intact.`
+          }],
+          isError: true
+        };
+      }
+      try {
+        saveSnapshot("current", parsed.index, parsed.content);
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to save current snapshot: ${err instanceof Error ? err.message : String(err)}`
+          }],
+          isError: true
+        };
+      }
+      const diff = diffSnapshots(baseline, parsed.index);
+      const total = diff.added.length + diff.removed.length + diff.modified.length;
+      const lines = [
+        "# Official Docs \u2014 Current Snapshot Updated",
+        "",
+        `Fetched: ${parsed.index.fetchedAt}`,
+        `Sections: ${parsed.index.sectionCount}`,
+        ""
+      ];
+      if (total === 0) {
+        lines.push(`No changes vs baseline (${formatDate(baseline.fetchedAt)}). All ${diff.unchanged} sections unchanged.`);
+      } else {
+        lines.push(`vs baseline (${formatDate(baseline.fetchedAt)}): ${diff.added.length} added, ${diff.removed.length} removed, ${diff.modified.length} modified, ${diff.unchanged} unchanged`);
+        lines.push("");
+        lines.push("Run diff_official_docs() for the full diff.");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "diff_official_docs",
+    "Compare the baseline and current official Anthropic Claude Code docs snapshots. Shows added, removed, and modified pages. No network call \u2014 reads local files only. Run init_official_docs() first, then refresh_official_docs() when you want to update the current snapshot.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async () => {
+      const baseline = loadIndex("baseline");
+      if (!baseline) {
+        return {
+          content: [{
+            type: "text",
+            text: "No baseline found. Run init_official_docs() first to create a baseline snapshot."
+          }],
+          isError: true
+        };
+      }
+      const current = loadIndex("current");
+      if (!current) {
+        return {
+          content: [{
+            type: "text",
+            text: "No current snapshot found. Run refresh_official_docs() to fetch the latest docs."
+          }],
+          isError: true
+        };
+      }
+      if (baseline.contentHash === current.contentHash) {
+        const ageDays2 = snapshotAgeDays(current);
+        const staleWarn = ageDays2 > STALENESS_WARN_DAYS ? `
+\u26A0\uFE0F  Current snapshot is ${ageDays2} days old \u2014 consider running refresh_official_docs()` : "";
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "# Official Docs Diff",
+              "",
+              `Baseline: ${formatDate(baseline.fetchedAt)} | Current: ${formatDate(current.fetchedAt)}`,
+              "",
+              `No changes detected. All ${baseline.sectionCount} sections unchanged.${staleWarn}`,
+              "",
+              "Run refresh_official_docs() to fetch latest docs and update current."
+            ].join("\n")
+          }]
+        };
+      }
+      const diff = diffSnapshots(baseline, current);
+      if (diff.modified.length > 0) {
+        const modifiedSlugs = diff.modified.map((m) => m.slug);
+        const baselineContents = loadSections("baseline", modifiedSlugs);
+        const currentContents = loadSections("current", modifiedSlugs);
+        for (const entry of diff.modified) {
+          const baseContent = baselineContents[entry.slug];
+          const currContent = currentContents[entry.slug];
+          if (baseContent && currContent) {
+            const line = findFirstChangedLine(baseContent, currContent);
+            if (line) entry.firstChangedLine = line;
+          }
+        }
+      }
+      const lines = [
+        "# Official Docs Diff",
+        "",
+        `Baseline: ${formatDate(baseline.fetchedAt)} | Current: ${formatDate(current.fetchedAt)}`,
+        ""
+      ];
+      const ageDays = snapshotAgeDays(current);
+      if (ageDays > STALENESS_WARN_DAYS) {
+        lines.push(`\u26A0\uFE0F  Current snapshot is ${ageDays} days old \u2014 consider running refresh_official_docs()`);
+        lines.push("");
+      }
+      if (diff.added.length > 0) {
+        lines.push(`## Added (${diff.added.length})`);
+        for (const s of diff.added) {
+          lines.push(`+ ${s.slug} \u2014 "${s.title}"`);
+          lines.push(`  ${s.sourceUrl}`);
+        }
+        lines.push("");
+      }
+      if (diff.removed.length > 0) {
+        lines.push(`## Removed (${diff.removed.length})`);
+        for (const s of diff.removed) {
+          lines.push(`- ${s.slug} \u2014 "${s.title}"`);
+          lines.push(`  ${s.sourceUrl}`);
+        }
+        lines.push("");
+      }
+      if (diff.modified.length > 0) {
+        lines.push(`## Modified (${diff.modified.length})`);
+        for (const s of diff.modified) {
+          const delta = s.lineDelta !== void 0 ? s.lineDelta >= 0 ? `+${s.lineDelta}` : `${s.lineDelta}` : "";
+          const charDelta = s.charsAfter !== void 0 && s.charsBefore !== void 0 ? s.charsAfter - s.charsBefore >= 0 ? `+${s.charsAfter - s.charsBefore}` : `${s.charsAfter - s.charsBefore}` : "";
+          lines.push(`~ ${s.slug} (L${s.linesBefore} \u2192 L${s.linesAfter}, ${delta} lines, ${charDelta} chars)`);
+          if (s.firstChangedLine) {
+            lines.push(`  First change: "${s.firstChangedLine}"`);
+          }
+          lines.push(`  ${s.sourceUrl}`);
+        }
+        lines.push("");
+      }
+      const total = diff.added.length + diff.removed.length + diff.modified.length;
+      lines.push("---");
+      lines.push(`${diff.added.length} added, ${diff.removed.length} removed, ${diff.modified.length} modified, ${diff.unchanged} unchanged (${total} total changes)`);
+      lines.push("Run refresh_official_docs() to update current to latest.");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "search_official_docs",
+    "Search the official Anthropic Claude Code documentation by keyword or topic. Uses the local current snapshot \u2014 no network call. Run init_official_docs() first.",
+    {
+      query: external_exports.string().describe('Search term or topic (e.g. "hooks", "MCP authentication", "cost limits")'),
+      limit: external_exports.number().min(1).max(10).optional().default(5).describe("Max sections to return (default 5)")
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async ({ query, limit }) => {
+      const current = loadIndex("current");
+      if (!current) {
+        return {
+          content: [{
+            type: "text",
+            text: "No snapshot found. Run init_official_docs() first to create a local cache of the official docs."
+          }],
+          isError: true
+        };
+      }
+      const scored = Object.values(current.sections).map((sec) => ({ meta: sec, titleScore: sec.title.toLowerCase().includes(query.toLowerCase()) ? 3 : 0 })).filter((item) => item.titleScore > 0);
+      let finalSlugs;
+      if (scored.length >= (limit ?? 5)) {
+        finalSlugs = scored.sort((a, b) => b.titleScore - a.titleScore).slice(0, limit ?? 5).map((item) => item.meta.slug);
+      } else {
+        const allSlugs = Object.keys(current.sections);
+        const allContents = loadSections("current", allSlugs);
+        const fullScored = Object.values(current.sections).map((sec) => ({
+          meta: sec,
+          score: scoreSection(sec.title, allContents[sec.slug] ?? "", query)
+        })).filter((item) => item.score > 0).sort((a, b) => b.score - a.score).slice(0, limit ?? 5);
+        finalSlugs = fullScored.map((item) => item.meta.slug);
+      }
+      if (finalSlugs.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: `No results for "${query}" in ${current.sectionCount} sections (snapshot: ${formatDate(current.fetchedAt)}).
+
+Try broader terms or run refresh_official_docs() to update the cache.`
+          }]
+        };
+      }
+      const matchingContents = loadSections("current", finalSlugs);
+      const lines = [
+        `# Search: "${query}" \u2014 ${finalSlugs.length} result${finalSlugs.length !== 1 ? "s" : ""} (snapshot: ${formatDate(current.fetchedAt)})`,
+        ""
+      ];
+      for (const slug of finalSlugs) {
+        const meta3 = current.sections[slug];
+        const content = matchingContents[slug] ?? "";
+        const excerpt = extractExcerpt(content, query);
+        lines.push(`## ${meta3.title}`);
+        lines.push(meta3.sourceUrl);
+        lines.push("");
+        lines.push(excerpt);
+        lines.push("");
+      }
+      lines.push("---");
+      lines.push(`Showing ${finalSlugs.length} of ${current.sectionCount} sections. Run refresh_official_docs() to update the cache.`);
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
 // src/resources/index.ts
 function registerResources(server) {
   server.resource(
@@ -15288,6 +15837,7 @@ function createServer() {
   registerGetThreat(server);
   registerListThreats(server);
   registerSearchExamples(server);
+  registerOfficialDocs(server);
   registerResources(server);
   registerPrompts(server);
   return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-ultimate-guide-mcp",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "MCP server for the Claude Code Ultimate Guide — search, read, and explore 20K+ lines of documentation directly from Claude Code",
   "keywords": [
     "mcp",