oscar64-mcp-docs 0.1.1

package/dist/stdio.js

@@ -0,0 +1,1260 @@
+#!/usr/bin/env node
+
+// src/mcp/server.ts
+import { MCPServer } from "@mastra/mcp";
+
+// src/indexing/tutorials.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+
+// src/config/tutorial-classification.ts
+var DEFAULT_TUTORIAL_CATEGORY = "general";
+var CONCEPT_RULES = [
+  {
+    concept: "timing_interrupts",
+    tests: [
+      { pattern: "#include\\s*<c64/rasterirq\\.h>", flags: "i", reason: "includes rasterirq api", weight: 3 },
+      { pattern: "\\brirq_[a-z0-9_]+\\b", flags: "i", reason: "uses rirq_* routines", weight: 2 },
+      { pattern: "\\birq\\b", flags: "i", reason: "mentions irq", weight: 1 }
+    ]
+  },
+  {
+    concept: "graphics_2d",
+    tests: [
+      { pattern: "#include\\s*<c64/(sprites|vic)\\.h>", flags: "i", reason: "uses c64 graphics headers", weight: 2 },
+      { pattern: "\\b(sprite|bitmap|tile|scroll|parallax|colorram)\\b", flags: "i", reason: "mentions graphics primitives", weight: 1 },
+      { pattern: "\\.(mcimg|spd|ctm)\\b", flags: "i", reason: "references graphics assets", weight: 1 }
+    ]
+  },
+  {
+    concept: "animation",
+    tests: [
+      { pattern: "\\b(animate|anim|moving|bounce|reflect|scroll)\\b", flags: "i", reason: "mentions motion behavior", weight: 1 },
+      { pattern: "\\bvspr_[a-z0-9_]+\\b", flags: "i", reason: "uses virtual sprite animation routines", weight: 2 }
+    ]
+  },
+  {
+    concept: "audio",
+    tests: [
+      { pattern: "#include\\s*<c64/sid\\.h>", flags: "i", reason: "includes sid api", weight: 3 },
+      { pattern: "\\.sid\\b", flags: "i", reason: "references sid asset", weight: 2 },
+      { pattern: "\\b(sid|music|audio|sound)\\b", flags: "i", reason: "mentions audio concepts", weight: 1 }
+    ]
+  },
+  {
+    concept: "memory_management",
+    tests: [
+      { pattern: "#include\\s*<c64/memmap\\.h>", flags: "i", reason: "includes memory map api", weight: 3 },
+      { pattern: "\\bmmap_[a-z0-9_]+\\b", flags: "i", reason: "uses mmap_* routines", weight: 2 },
+      { pattern: "\\b(bank|overlay|layout|resource region|full memory)\\b", flags: "i", reason: "mentions memory layout concepts", weight: 1 }
+    ]
+  },
+  {
+    concept: "math_numerics",
+    tests: [
+      { pattern: "#include\\s*<math\\.h>", flags: "i", reason: "includes math api", weight: 3 },
+      { pattern: "\\b(cordic|atan|cosin|sqrt|float|fixpoint|distance)\\b", flags: "i", reason: "mentions numeric methods", weight: 1 }
+    ]
+  },
+  {
+    concept: "data_structures_game_logic",
+    tests: [
+      { pattern: "\\badventure\\b", flags: "i", reason: "mentions adventure gameplay", weight: 2 },
+      { pattern: "\\b(token|parse|map|items|doors|keys)\\b", flags: "i", reason: "mentions game logic structures", weight: 1 }
+    ]
+  },
+  {
+    concept: "resource_pipeline",
+    tests: [
+      { pattern: "#embed", flags: "i", reason: "uses #embed resource pipeline", weight: 2 },
+      { pattern: "\\.\\./resources/", flags: "i", reason: "references shared resources", weight: 1 },
+      { pattern: "\\.(ctm|spd|sid|bin|mcimg)\\b", flags: "i", reason: "references packed assets", weight: 1 }
+    ]
+  },
+  {
+    concept: "build_tooling",
+    tests: [
+      { pattern: "\\bmake\\.bat\\b", flags: "i", reason: "includes build batch file", weight: 1 },
+      { pattern: "\\b(makefile|build\\.sh|compiler flag|oscar64)\\b", flags: "i", reason: "mentions build tooling", weight: 1 }
+    ]
+  },
+  {
+    concept: "io_storage",
+    tests: [
+      { pattern: "#include\\s*<c64/(kernalio|iecbus)\\.h>", flags: "i", reason: "includes storage/io api", weight: 3 },
+      { pattern: "\\b(file|disk|load|save|read|write|io)\\b", flags: "i", reason: "mentions io/storage operations", weight: 1 }
+    ]
+  },
+  {
+    concept: "input",
+    tests: [
+      { pattern: "#include\\s*<c64/(keyboard|joystick|mouse)\\.h>", flags: "i", reason: "includes input api", weight: 3 },
+      { pattern: "\\b(key|keyboard|joystick|mouse|cursor)\\b", flags: "i", reason: "mentions input handling", weight: 1 }
+    ]
+  }
+];
+var CATEGORY_FROM_CONCEPTS = [
+  { category: "visuals", anyOf: ["graphics_2d", "animation"] },
+  { category: "systems", anyOf: ["timing_interrupts", "memory_management", "resource_pipeline", "build_tooling"] },
+  { category: "logic", anyOf: ["data_structures_game_logic", "math_numerics"] },
+  { category: "platform_io", anyOf: ["io_storage", "input", "audio"] }
+];
+
+// src/search/minisearch.ts
+import MiniSearch from "minisearch";
+
+// src/utils.ts
+import crypto from "crypto";
+import fs from "fs/promises";
+import path2 from "path";
+
+// src/config.ts
+import os from "os";
+import path from "path";
+var CACHE_DIR = process.env.OSCAR_MCP_CACHE_DIR ?? path.join(os.homedir(), ".cache", "oscar-mcp");
+var META_DIR = path.join(CACHE_DIR, "meta");
+var SOURCES_DIR = path.join(CACHE_DIR, "sources");
+var INDEX_DIR = path.join(CACHE_DIR, "index");
+var UPDATE_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAX_TEXT_BYTES = 1e6;
+var GITHUB_API = "https://api.github.com";
+var REPOS = [
+  { key: "oscar64", owner: "drmortalwombat", repo: "oscar64", trackingRef: process.env.OSCAR64_REF ?? "main" },
+  {
+    key: "OscarTutorials",
+    owner: "drmortalwombat",
+    repo: "OscarTutorials",
+    trackingRef: process.env.OSCAR_TUTORIALS_REF ?? "main"
+  }
+];
+var TEXT_EXTS = /* @__PURE__ */ new Set([
+  ".md",
+  ".txt",
+  ".c",
+  ".h",
+  ".cpp",
+  ".s",
+  ".asm",
+  ".inc",
+  ".json",
+  ".yml",
+  ".yaml",
+  ".bat"
+]);
+
+// src/utils.ts
+function slugify(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+}
+function makeExcerpt(text, maxLen = 420) {
+  const compact = text.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxLen) return compact;
+  return `${compact.slice(0, maxLen - 1)}\u2026`;
+}
+function sha256(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+async function readJson(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeJson(filePath, value) {
+  await fs.mkdir(path2.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(value, null, 2), "utf8");
+}
+async function exists(filePath) {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function safeJoin(root, relPath) {
+  const out = path2.resolve(root, relPath);
+  const rootResolved = path2.resolve(root);
+  if (!out.startsWith(rootResolved + path2.sep) && out !== rootResolved) {
+    throw new Error("Path traversal blocked");
+  }
+  return out;
+}
+function isTextPath(filePath) {
+  return TEXT_EXTS.has(path2.extname(filePath).toLowerCase());
+}
+async function safeReadText(filePath) {
+  const stat = await fs.stat(filePath);
+  if (!stat.isFile()) throw new Error("Not a file");
+  if (stat.size > MAX_TEXT_BYTES) throw new Error("File too large");
+  const buf = await fs.readFile(filePath);
+  return buf.toString("utf8");
+}
+async function listFilesRecursive(root) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const abs = path2.join(dir, e.name);
+      if (e.isDirectory()) await walk(abs);
+      else if (e.isFile()) out.push(abs);
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+// src/search/minisearch.ts
+function oscarTokenizer(text) {
+  return text.toLowerCase().split(/[^0-9a-zA-Z_\-$]+/).filter(Boolean);
+}
+function oscarProcessTerm(term) {
+  const t = term.toLowerCase();
+  if (t.startsWith("-") && t.length > 2) return [t, t.slice(1)];
+  if (t.startsWith("$") && t.length > 2) {
+    const hex = t.slice(1);
+    return [t, hex, `0x${hex}`];
+  }
+  return [t];
+}
+function inferCombineMode(query) {
+  return query.trim().split(/\s+/).filter(Boolean).length <= 1 ? "OR" : "AND";
+}
+function expandTaskQuery(task) {
+  const synonyms = {
+    irq: ["interrupt", "raster", "nmi"],
+    sprite: ["sprites", "multiplex", "mux"],
+    scroll: ["scrolling", "scroller"],
+    sid: ["music", "audio", "sound"],
+    vic: ["vic-ii", "video", "raster"],
+    border: ["$d020", "d020"]
+  };
+  const lower = task.toLowerCase();
+  const terms = /* @__PURE__ */ new Set([task]);
+  for (const [base, syns] of Object.entries(synonyms)) {
+    if (lower.includes(base) || syns.some((s) => lower.includes(s))) {
+      terms.add(base);
+      for (const s of syns) terms.add(s);
+    }
+  }
+  return [...terms].join(" ");
+}
+function buildDocsSearch(state) {
+  const ms = new MiniSearch({
+    fields: ["title", "keywords", "body"],
+    storeFields: ["kind", "title", "uri", "excerpt", "repo", "ref", "anchor", "tutorialId"],
+    tokenize: oscarTokenizer,
+    processTerm: oscarProcessTerm,
+    searchOptions: {
+      boost: { title: 6, keywords: 3, body: 1 },
+      prefix: true,
+      fuzzy: 0.12,
+      combineWith: "AND"
+    }
+  });
+  const docs = [];
+  for (const s of state.manualSections) {
+    const body = state.manualLines.slice(s.startLine, s.endLine + 1).join("\n");
+    docs.push({
+      id: `manual:${s.anchor}`,
+      kind: "manual_section",
+      title: s.heading,
+      uri: `docs://oscar64/manual#${s.anchor}`,
+      excerpt: makeExcerpt(body),
+      body,
+      anchor: s.anchor,
+      repo: "oscar64",
+      ref: state.repos.oscar64.resolvedSha
+    });
+  }
+  for (const t of state.tutorials) {
+    const keywords = t.keywords.join(" ");
+    const body = `${t.title}
+${t.files.join("\n")}
+${t.previewText}`;
+    docs.push({
+      id: `tutorial:${t.id}`,
+      kind: "tutorial",
+      title: `${t.id} ${t.title}`,
+      uri: `tutorial://${t.id}/manifest`,
+      excerpt: makeExcerpt(t.previewText || `${t.id} ${t.title}`),
+      body,
+      tutorialId: t.id,
+      keywords,
+      repo: "OscarTutorials",
+      ref: state.repos.OscarTutorials.resolvedSha
+    });
+  }
+  ms.addAll(docs);
+  return ms;
+}
+
+// src/indexing/tutorials.ts
+function parseTutorialIdentity(folderName) {
+  const numeric = folderName.match(/^(\d+)\s+(.+)$/);
+  if (numeric) return { id: numeric[1], title: numeric[2].trim() };
+  return { id: slugify(folderName), title: folderName };
+}
+async function readFirstLines(filePath, maxLines = 120) {
+  const text = await safeReadText(filePath);
+  return text.split(/\r?\n/).slice(0, maxLines).join("\n");
+}
+function pickPrimaryFile(files) {
+  const normalized = files.map((f) => f.replace(/\\/g, "/"));
+  const readme = normalized.find((f) => /^readme(\.[^/]+)?$/i.test(path3.basename(f)));
+  if (readme) return readme;
+  const mainC = normalized.find((f) => f.toLowerCase() === "main.c") ?? normalized.find((f) => f.toLowerCase().endsWith("/main.c"));
+  if (mainC) return mainC;
+  const c = normalized.filter((f) => f.toLowerCase().endsWith(".c")).sort()[0];
+  if (c) return c;
+  const cpp = normalized.filter((f) => f.toLowerCase().endsWith(".cpp")).sort()[0];
+  if (cpp) return cpp;
+  return normalized.sort()[0] ?? null;
+}
+function extractAssetRefs(preview) {
+  const refs = /* @__PURE__ */ new Set();
+  const regex = /\.\.\/Resources\/[^"'\s)]+/g;
+  let match;
+  while ((match = regex.exec(preview)) !== null) refs.add(match[0]);
+  return [...refs];
+}
+function classifyConcepts(input) {
+  const haystack = [input.title, ...input.files, input.previewText, ...input.assetRefs].join("\n").toLowerCase();
+  const evidence = /* @__PURE__ */ new Map();
+  const scores = /* @__PURE__ */ new Map();
+  for (const rule of CONCEPT_RULES) {
+    for (const test of rule.tests) {
+      const re = new RegExp(test.pattern, test.flags ?? "i");
+      if (!re.test(haystack)) continue;
+      if (!evidence.has(rule.concept)) evidence.set(rule.concept, /* @__PURE__ */ new Set());
+      evidence.get(rule.concept).add(test.reason);
+      scores.set(rule.concept, (scores.get(rule.concept) ?? 0) + (test.weight ?? 1));
+    }
+  }
+  const conceptEvidence = {};
+  const conceptScores = {};
+  for (const [concept, reasons] of evidence.entries()) {
+    conceptEvidence[concept] = [...reasons].sort();
+    conceptScores[concept] = scores.get(concept) ?? 0;
+  }
+  const concepts = Object.keys(conceptEvidence).sort((a, b) => {
+    const scoreDiff = (conceptScores[b] ?? 0) - (conceptScores[a] ?? 0);
+    if (scoreDiff !== 0) return scoreDiff;
+    return a.localeCompare(b);
+  });
+  return { concepts, conceptEvidence, conceptScores };
+}
+function deriveCategoryFromConcepts(concepts) {
+  const set = new Set(concepts);
+  for (const group of CATEGORY_FROM_CONCEPTS) {
+    if (group.anyOf.some((concept) => set.has(concept))) return group.category;
+  }
+  return DEFAULT_TUTORIAL_CATEGORY;
+}
+function tutorialManifest(t) {
+  return {
+    id: t.id,
+    title: t.title,
+    slug: t.slug,
+    folder_name: t.folderName,
+    category: t.category,
+    primary_file: t.primaryFile,
+    files: t.files,
+    preview_text: t.previewText,
+    keywords: t.keywords,
+    asset_refs: t.assetRefs,
+    concepts: t.concepts,
+    concept_evidence: t.conceptEvidence
+  };
+}
+async function buildTutorialsIndex(tutorialsRoot) {
+  const entries = await fs2.readdir(tutorialsRoot, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).filter((name) => !name.startsWith(".") && name.toLowerCase() !== "resources").sort((a, b) => a.localeCompare(b, void 0, { numeric: true }));
+  const tutorials = [];
+  for (const folderName of dirs) {
+    const absDir = path3.join(tutorialsRoot, folderName);
+    const filesAbs = await listFilesRecursive(absDir);
+    const files = filesAbs.map((f) => path3.relative(absDir, f));
+    if (files.length === 0) continue;
+    const { id, title } = parseTutorialIdentity(folderName);
+    const primaryFile = pickPrimaryFile(files);
+    let previewText = "";
+    if (primaryFile) {
+      try {
+        previewText = await readFirstLines(path3.join(absDir, primaryFile));
+      } catch {
+        previewText = "";
+      }
+    }
+    const assetRefs = extractAssetRefs(previewText);
+    const { concepts, conceptEvidence } = classifyConcepts({
+      title,
+      files,
+      previewText,
+      assetRefs
+    });
+    const keywords = /* @__PURE__ */ new Set();
+    for (const token of oscarTokenizer(`${title} ${folderName}`)) {
+      for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
+    }
+    for (const rel of files) {
+      for (const token of oscarTokenizer(path3.basename(rel, path3.extname(rel)))) {
+        for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
+      }
+    }
+    for (const token of oscarTokenizer(previewText)) {
+      for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
+    }
+    for (const concept of concepts) {
+      for (const token of oscarTokenizer(concept)) {
+        for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
+      }
+    }
+    tutorials.push({
+      id,
+      title,
+      slug: `${id}-${slugify(title)}`,
+      folderName,
+      absDir,
+      category: deriveCategoryFromConcepts(concepts),
+      primaryFile,
+      files,
+      previewText: makeExcerpt(previewText, 2e3),
+      keywords: [...keywords].slice(0, 220),
+      assetRefs,
+      concepts,
+      conceptEvidence
+    });
+  }
+  return tutorials;
+}
+
+// src/mcp/resources.ts
+function indexContracts() {
+  return JSON.stringify(
+    {
+      tool_response_contract: {
+        ok: "boolean, true when tool call succeeded",
+        data: "object, present on ok=true",
+        error: {
+          code: "INVALID_INPUT|NOT_FOUND|UNSUPPORTED_SCOPE|OFFLINE|INTERNAL_ERROR",
+          message: "human-readable failure summary",
+          hint: "specific recovery action",
+          recoverable: "boolean",
+          suggested_tool_calls: "optional list of {tool,args}"
+        },
+        next_actions: "optional list of recommended follow-up actions",
+        meta: {
+          tool: "tool id",
+          generated_at: "ISO date-time",
+          contract_version: "string"
+        }
+      },
+      tool_intent_map: {
+        search_docs: "Start here for conceptual search over docs/tutorial manifests.",
+        get_doc_section: "Fetch authoritative manual section after search_docs.",
+        search_code: "Find concrete source snippets and line ranges.",
+        get_best_tutorial: "Route task to best tutorial with concept evidence.",
+        refresh_sources: "Refresh synced source snapshots.",
+        get_source_status: "Check source readiness and index sizes."
+      }
+    },
+    null,
+    2
+  );
+}
+function indexToolingGuide() {
+  return [
+    "# Tooling Guide",
+    "",
+    "1. Understand feature intent: `search_docs`",
+    "2. Read authoritative manual: `get_doc_section`",
+    "3. Inspect practical code: `get_best_tutorial` then `search_code`",
+    "",
+    "If a tool returns `ok=false`, use `error.hint` and `suggested_tool_calls`."
+  ].join("\n");
+}
+function indexQuickstart() {
+  return [
+    "# Quickstart",
+    "",
+    "Workflow A: Find manual guidance",
+    "- Call `search_docs` with scope=manual",
+    "- Call `get_doc_section` using a returned anchor",
+    "",
+    "Workflow B: Find matching tutorial",
+    "- Call `get_best_tutorial` with task",
+    "- Read `tutorial://<id>/manifest`",
+    "- Read `tutorial://<id>/file/<path>` for key files",
+    "",
+    "Workflow C: Keep sources current",
+    "- Call `refresh_sources` when you need updated remote docs/examples",
+    "- Call `get_source_status` to verify source readiness"
+  ].join("\n");
+}
+function indexErrors() {
+  return JSON.stringify(
+    {
+      INVALID_INPUT: "Input schema/semantics invalid; fix arguments and retry.",
+      NOT_FOUND: "Requested section/tutorial/path not found; run search tools first.",
+      UNSUPPORTED_SCOPE: "Scope not supported by selected tool.",
+      OFFLINE: "Remote source status unavailable; retry later.",
+      INTERNAL_ERROR: "Unexpected server fault; retry and report if persistent."
+    },
+    null,
+    2
+  );
+}
+function makeResources(getState) {
+  const resourceTemplates = async () => [
+    {
+      uriTemplate: "docs://oscar64/manual#{anchor}",
+      name: "Oscar64 Manual Section",
+      description: "A specific manual section by stable anchor.",
+      mimeType: "text/markdown"
+    },
+    {
+      uriTemplate: "tutorial://{id}/file/{path}",
+      name: "OscarTutorials file",
+      description: "A specific tutorial source file.",
+      mimeType: "text/plain"
+    },
+    {
+      uriTemplate: "repo://oscar64/{path}",
+      name: "oscar64 file",
+      description: "A specific text file from oscar64 repository snapshot.",
+      mimeType: "text/plain"
+    },
+    {
+      uriTemplate: "repo://OscarTutorials/{path}",
+      name: "OscarTutorials file",
+      description: "A specific text file from OscarTutorials repository snapshot.",
+      mimeType: "text/plain"
+    }
+  ];
+  const listResources = async () => {
+    const state = getState();
+    return [
+      { uri: "index://quickstart", name: "Quickstart", description: "Minimal tool call workflows.", mimeType: "text/markdown" },
+      { uri: "index://tooling-guide", name: "Tooling Guide", description: "Tool decision tree for coding agents.", mimeType: "text/markdown" },
+      { uri: "index://contracts", name: "Tool Contracts", description: "Standard input/output contract reference.", mimeType: "application/json" },
+      { uri: "index://errors", name: "Error Codes", description: "Error taxonomy and recovery guidance.", mimeType: "application/json" },
+      { uri: "index://status", name: "Source And Index Status", description: "Source readiness and index sizes", mimeType: "application/json" },
+      { uri: "index://manual-anchors", name: "Manual Anchors", description: "Headings from oscar64 manual", mimeType: "application/json" },
+      { uri: "index://tutorials", name: "Tutorial Index", description: "Normalized OscarTutorials catalog", mimeType: "application/json" },
+      {
+        uri: "docs://oscar64/manual",
+        name: "Oscar64 Manual",
+        description: "Oscar64 compiler manual",
+        mimeType: "text/markdown"
+      }
+    ];
+  };
+  const getResourceContent = async ({ uri }) => {
+    const state = getState();
+    if (uri === "index://quickstart") return { text: indexQuickstart() };
+    if (uri === "index://tooling-guide") return { text: indexToolingGuide() };
+    if (uri === "index://contracts") return { text: indexContracts() };
+    if (uri === "index://errors") return { text: indexErrors() };
+    if (uri === "index://status") {
+      return {
+        text: JSON.stringify(
+          {
+            source_keys: Object.keys(state.repos),
+            source_ready: Object.values(state.repos).every((r) => Boolean(r.rootDir)),
+            tutorial_count: state.tutorials.length,
+            manual_section_count: state.manualSections.length
+          },
+          null,
+          2
+        )
+      };
+    }
+    if (uri === "index://manual-anchors") {
+      return {
+        text: JSON.stringify(
+          {
+            anchors: state.manualSections.map((s) => ({ anchor: s.anchor, heading: s.heading, level: s.level }))
+          },
+          null,
+          2
+        )
+      };
+    }
+    if (uri === "index://tutorials") {
+      return {
+        text: JSON.stringify(
+          {
+            tutorials: state.tutorials.map((t) => tutorialManifest(t))
+          },
+          null,
+          2
+        )
+      };
+    }
+    if (uri === "docs://oscar64/manual") {
+      return {
+        text: state.manualLines.join("\n")
+      };
+    }
+    if (uri.startsWith("docs://oscar64/manual#")) {
+      const anchor = uri.split("#")[1] ?? "";
+      const section = state.manualSections.find((s) => s.anchor === anchor);
+      if (!section) throw new Error(`Unknown anchor: ${anchor}`);
+      const content = state.manualLines.slice(section.startLine, section.endLine + 1).join("\n");
+      return {
+        text: content
+      };
+    }
+    if (uri.startsWith("tutorial://") && uri.endsWith("/manifest")) {
+      const id = uri.replace("tutorial://", "").replace("/manifest", "");
+      const t = state.tutorials.find((x) => x.id === id);
+      if (!t) throw new Error(`Unknown tutorial id: ${id}`);
+      return {
+        text: JSON.stringify(tutorialManifest(t), null, 2)
+      };
+    }
+    if (uri.startsWith("tutorial://") && uri.includes("/file/")) {
+      const rest = uri.replace("tutorial://", "");
+      const [id, , ...parts] = rest.split("/");
+      const rel = parts.join("/");
+      const t = state.tutorials.find((x) => x.id === id);
+      if (!t) throw new Error(`Unknown tutorial id: ${id}`);
+      const abs = safeJoin(t.absDir, rel);
+      const text = await safeReadText(abs);
+      return {
+        text
+      };
+    }
+    if (uri.startsWith("repo://oscar64/")) {
+      const rel = uri.replace("repo://oscar64/", "");
+      const abs = safeJoin(state.oscar64Root, rel);
+      if (!isTextPath(abs)) throw new Error("Only text files are readable");
+      const text = await safeReadText(abs);
+      return {
+        text
+      };
+    }
+    if (uri.startsWith("repo://OscarTutorials/")) {
+      const rel = uri.replace("repo://OscarTutorials/", "");
+      const abs = safeJoin(state.tutorialsRoot, rel);
+      if (!isTextPath(abs)) throw new Error("Only text files are readable");
+      const text = await safeReadText(abs);
+      return {
+        text
+      };
+    }
+    throw new Error(`Unsupported URI: ${uri}`);
+  };
+  return {
+    listResources,
+    getResourceContent,
+    resourceTemplates
+  };
+}
+
+// src/mcp/tools.ts
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// src/mcp/contract.ts
+var CONTRACT_VERSION = "1.0";
+function makeMeta(tool, state) {
+  void state;
+  return {
+    tool,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    contract_version: CONTRACT_VERSION
+  };
+}
+function okResponse(tool, state, data, nextActions = []) {
+  return {
+    ok: true,
+    data,
+    next_actions: nextActions,
+    meta: makeMeta(tool, state)
+  };
+}
+function errorResponse(tool, state, error, nextActions = []) {
+  return {
+    ok: false,
+    error,
+    next_actions: nextActions,
+    meta: makeMeta(tool, state)
+  };
+}
+
+// src/mcp/tools.ts
+function isAllowedScopePath(scope, relPath) {
+  const norm = relPath.replace(/\\/g, "/");
+  if (scope === "compiler") return norm.startsWith("oscar64/");
+  if (scope === "sdk") return norm.startsWith("include/");
+  if (scope === "samples") return norm.startsWith("samples/");
+  if (scope === "autotest") return norm.startsWith("autotest/");
+  if (scope === "tutorials") return true;
+  return true;
+}
+var standardEnvelopeOutput = z.object({
+  ok: z.boolean().describe("True on success, false on error."),
+  data: z.unknown().optional().describe("Tool-specific success payload."),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    hint: z.string(),
+    recoverable: z.boolean(),
+    suggested_tool_calls: z.array(z.object({ tool: z.string(), args: z.record(z.unknown()) })).optional()
+  }).optional(),
+  next_actions: z.array(
+    z.object({
+      action: z.string(),
+      reason: z.string(),
+      tool: z.string().optional(),
+      uri: z.string().optional()
+    })
+  ).optional(),
+  meta: z.object({
+    tool: z.string(),
+    generated_at: z.string(),
+    contract_version: z.string()
+  })
+});
+function makeTools(getState, refreshState) {
+  const searchDocs = createTool({
+    id: "search_docs",
+    description: "Use this first when you need conceptual guidance. Searches manual sections and tutorial manifests, then returns ranked URIs to read next.",
+    inputSchema: z.object({
+      query: z.string().min(1).describe("Natural language query, symbol, or feature name to search for."),
+      limit: z.number().int().min(1).max(50).default(10).describe("Maximum number of ranked matches to return."),
+      scope: z.enum(["manual", "tutorials", "sdk", "samples", "autotest", "all"]).default("all").describe("Search surface. Use 'manual' for docs and 'tutorials' for example routing.")
+    }),
+    outputSchema: standardEnvelopeOutput,
+    execute: async ({ context }) => {
+      const { query, limit, scope } = context;
+      const state = getState();
+      const filter = scope === "all" ? void 0 : (r) => {
+        if (scope === "manual") return r.kind === "manual_section";
+        if (scope === "tutorials") return r.kind === "tutorial";
+        return r.kind === "manual_section";
+      };
+      const results = state.docsSearch.search(query, {
+        combineWith: inferCombineMode(query),
+        prefix: true,
+        fuzzy: 0.12,
+        filter
+      }).slice(0, limit).map((r) => ({
+        uri: r.uri,
+        title: r.title,
+        snippet: r.excerpt,
+        kind: r.kind
+      }));
+      const nextActions = results.slice(0, 2).map((item) => ({
+        action: "Read top match",
+        reason: "Inspect exact source text before generating or modifying code.",
+        uri: item.uri
+      }));
+      return okResponse(
+        "search_docs",
+        state,
+        {
+          query,
+          scope,
+          limit,
+          results
+        },
+        nextActions
+      );
+    }
+  });
+  const getDocSection = createTool({
+    id: "get_doc_section",
+    description: "Use after search_docs when you need authoritative manual text. Resolves anchor/heading and returns a bounded section slice.",
+    inputSchema: z.object({
+      anchor_or_heading: z.string().min(1).describe("Manual anchor (preferred) or heading text to resolve and read."),
+      max_chars: z.number().int().min(1e3).max(25e3).default(12e3).describe("Maximum returned section length to control token usage.")
+    }),
+    outputSchema: standardEnvelopeOutput,
+    execute: async ({ context }) => {
+      const { anchor_or_heading, max_chars } = context;
+      const state = getState();
+      const q = anchor_or_heading.trim();
+      let matchedBy = null;
+      let section = state.manualSections.find((s) => s.anchor === q);
+      if (section) matchedBy = "anchor_exact";
+      if (!section) {
+        section = state.manualSections.find((s) => s.anchor === q.toLowerCase().replace(/\s+/g, "-"));
+        if (section) matchedBy = "anchor_normalized";
+      }
+      if (!section) {
+        section = state.manualSections.find((s) => s.heading.toLowerCase() === q.toLowerCase());
+        if (section) matchedBy = "heading_exact";
+      }
+      if (!section) {
+        section = state.manualSections.find((s) => s.heading.toLowerCase().includes(q.toLowerCase()));
+        if (section) matchedBy = "heading_fuzzy";
+      }
+      if (!section || !matchedBy) {
+        return errorResponse("get_doc_section", state, {
+          code: "NOT_FOUND",
+          message: `No manual section found for '${q}'.`,
+          hint: "Call search_docs first, then pass an exact returned manual URI anchor.",
+          recoverable: true,
+          suggested_tool_calls: [{ tool: "search_docs", args: { query: q, scope: "manual", limit: 5 } }]
+        });
+      }
+      const content = state.manualLines.slice(section.startLine, section.endLine + 1).join("\n").slice(0, max_chars);
+      const uri = `docs://oscar64/manual#${section.anchor}`;
+      return okResponse(
+        "get_doc_section",
+        state,
+        {
+          uri,
+          heading: section.heading,
+          anchor: section.anchor,
+          content,
+          truncated: content.length >= max_chars
+        },
+        [
+          {
+            action: "Search related implementation examples",
+            reason: "Pair manual guidance with concrete code patterns.",
+            tool: "search_code"
+          }
+        ]
+      );
+    }
+  });
+  const searchCode = createTool({
+    id: "search_code",
+    description: "Use when you need concrete source snippets. Returns file URIs plus line ranges and contextual snippets.",
+    inputSchema: z.object({
+      query: z.string().min(1).describe("Text or symbol to find in source files."),
+      scope: z.enum(["tutorials", "sdk", "samples", "autotest", "compiler", "all"]).default("tutorials").describe("Code corpus to search. Default is tutorials for practical examples."),
+      path_glob: z.string().optional().describe("Optional substring filter applied to relative file paths."),
+      limit: z.number().int().min(1).max(80).default(20).describe("Maximum number of snippet hits to return.")
+    }),
+    outputSchema: standardEnvelopeOutput,
+    execute: async ({ context }) => {
+      const { query, scope, path_glob, limit } = context;
+      const state = getState();
+      const q = query.toLowerCase();
+      const hits = [];
+      const roots = [];
+      if (scope === "tutorials" || scope === "all") {
+        roots.push({
+          repo: "OscarTutorials",
+          absRoot: state.tutorialsRoot
+        });
+      }
+      if (scope !== "tutorials") {
+        roots.push({
+          repo: "oscar64",
+          absRoot: state.oscar64Root
+        });
+      }
+      for (const root of roots) {
+        const files = await listFilesRecursive(root.absRoot);
+        for (const abs of files) {
+          if (!isTextPath(abs)) continue;
+          const rel = abs.replace(root.absRoot + "/", "").replace(/\\/g, "/");
+          if (path_glob && !rel.includes(path_glob)) continue;
+          if (root.repo === "oscar64" && scope !== "all" && scope !== "tutorials" && !isAllowedScopePath(scope, rel)) {
+            continue;
+          }
+          let text;
+          try {
+            text = await safeReadText(abs);
+          } catch {
+            continue;
+          }
+          const lines = text.split(/\r?\n/);
+          for (let i = 0; i < lines.length; i += 1) {
+            if (!lines[i].toLowerCase().includes(q)) continue;
+            const start = Math.max(0, i - 2);
+            const end = Math.min(lines.length - 1, i + 2);
+            const uri = root.repo === "oscar64" ? `repo://oscar64/${rel}` : `repo://OscarTutorials/${rel}`;
+            hits.push({
+              uri,
+              line_start: start + 1,
+              line_end: end + 1,
+              snippet: lines.slice(start, end + 1).join("\n").slice(0, 700)
+            });
+            if (hits.length >= limit) break;
+          }
+          if (hits.length >= limit) break;
+        }
+        if (hits.length >= limit) break;
+      }
+      return okResponse(
+        "search_code",
+        state,
+        {
+          query,
+          scope,
+          path_glob: path_glob ?? null,
+          limit,
+          results: hits
+        },
+        hits.length ? [
+          {
+            action: "Open top code hit",
+            reason: "Inspect concrete implementation before adaptation.",
+            uri: hits[0].uri
+          }
+        ] : []
+      );
+    }
+  });
+  const getBestTutorial = createTool({
+    id: "get_best_tutorial",
+    description: "Use to route a development task to the best tutorial starting points. Returns ranked recommendations with concept evidence.",
+    inputSchema: z.object({
+      task: z.string().min(1).describe("Plain-language coding task or feature goal."),
+      limit: z.number().int().min(1).max(10).default(3).describe("Maximum tutorial recommendations to return.")
+    }),
+    outputSchema: standardEnvelopeOutput,
+    execute: async ({ context }) => {
+      const { task, limit } = context;
+      const state = getState();
+      const expanded = expandTaskQuery(task);
+      const combineWith = inferCombineMode(expanded);
+      const scored = state.docsSearch.search(expanded, {
+        combineWith,
+        prefix: true,
+        fuzzy: 0.12,
+        filter: (r) => r.kind === "tutorial"
+      }).map((r) => {
+        const t = state.tutorials.find((x) => x.id === r.tutorialId);
+        return { r, t };
+      }).filter((x) => Boolean(x.t)).sort((a, b) => b.r.score - a.r.score || a.t.id.localeCompare(b.t.id, void 0, { numeric: true })).slice(0, limit).map((x) => ({
+        tutorial_uri: `tutorial://${x.t.id}/manifest`,
+        tutorial_id: x.t.id,
+        title: `${x.t.id} ${x.t.title}`,
+        category: x.t.category,
+        concepts: x.t.concepts,
+        key_files: x.t.files.slice(0, 12),
+        asset_refs: x.t.assetRefs,
+        preview: x.t.previewText.slice(0, 320)
+      }));
+      if (scored.length === 0) {
+        return errorResponse("get_best_tutorial", state, {
+          code: "NOT_FOUND",
+          message: `No tutorial candidates matched '${task}'.`,
+          hint: "Try broader terms or call search_code with scope='tutorials' to inspect raw source hits.",
+          recoverable: true,
+          suggested_tool_calls: [
+            { tool: "search_docs", args: { query: task, scope: "tutorials", limit: 10 } },
+            { tool: "search_code", args: { query: task, scope: "tutorials", limit: 20 } }
+          ]
+        });
+      }
+      return okResponse(
+        "get_best_tutorial",
+        state,
+        {
+          task,
+          recommendations: scored
+        },
+        [
+          {
+            action: "Read top tutorial manifest",
+            reason: "Validate concept fit and inspect key files before coding.",
+            uri: scored[0].tutorial_uri
+          }
+        ]
+      );
+    }
+  });
+  const refreshSources = createTool({
+    id: "refresh_sources",
+    description: "Refresh source snapshots.",
+    inputSchema: z.object({
+      force: z.boolean().default(false).describe("When true, bypass staleness window and force remote refresh checks.")
+    }),
+    outputSchema: standardEnvelopeOutput,
+    execute: async ({ context }) => {
+      const { force } = context;
+      await refreshState(force);
+      const state = getState();
+      return okResponse("refresh_sources", state, {
+        refreshed: true,
+        force,
+        source_keys: Object.keys(state.repos),
+        source_ready: Object.values(state.repos).every((r) => Boolean(r.rootDir))
+      });
+    }
+  });
+  const getSourceStatus = createTool({
+    id: "get_source_status",
+    description: "Get source readiness and index sizes.",
+    inputSchema: z.object({}),
+    outputSchema: standardEnvelopeOutput,
+    execute: async () => {
+      const state = getState();
+      return okResponse("get_source_status", state, {
+        source_keys: Object.keys(state.repos),
+        source_ready: Object.values(state.repos).every((r) => Boolean(r.rootDir)),
+        tutorial_count: state.tutorials.length,
+        manual_section_count: state.manualSections.length
+      });
+    }
+  });
+  return {
+    searchDocs,
+    getDocSection,
+    searchCode,
+    getBestTutorial,
+    refreshSources,
+    getSourceStatus
+  };
+}
+
+// src/state.ts
+import fs4 from "fs/promises";
+import path5 from "path";
+
+// src/indexing/manual.ts
+function parseManualSections(text) {
+  const lines = text.split(/\r?\n/);
+  const headings = [];
+  const seenAnchors = /* @__PURE__ */ new Map();
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!match) continue;
+    const baseAnchor = slugify(match[2]);
+    const seen = seenAnchors.get(baseAnchor) ?? 0;
+    seenAnchors.set(baseAnchor, seen + 1);
+    const anchor = seen === 0 ? baseAnchor : `${baseAnchor}-${seen}`;
+    headings.push({
+      line: i,
+      level: match[1].length,
+      heading: match[2].trim(),
+      anchor
+    });
+  }
+  const sections = headings.map((h, idx) => ({
+    anchor: h.anchor,
+    heading: h.heading,
+    level: h.level,
+    startLine: h.line,
+    endLine: idx + 1 < headings.length ? headings[idx + 1].line - 1 : lines.length - 1
+  }));
+  return { lines, sections };
+}
+
+// src/sync/github-http.ts
+import AdmZip from "adm-zip";
+import fs3 from "fs/promises";
+import path4 from "path";
+function githubHeaders() {
+  const headers = {
+    "User-Agent": "oscar64-mcp-docs",
+    Accept: "application/vnd.github+json"
+  };
+  const token = process.env.GITHUB_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+async function fetchJson(url) {
+  const res = await fetch(url, { headers: githubHeaders() });
+  if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
+  return await res.json();
+}
+async function getRemoteSha(cfg) {
+  const data = await fetchJson(`${GITHUB_API}/repos/${cfg.owner}/${cfg.repo}/commits/${cfg.trackingRef}`);
+  return data.sha;
+}
+async function downloadZip(cfg, ref) {
+  const url = `${GITHUB_API}/repos/${cfg.owner}/${cfg.repo}/zipball/${ref}`;
+  const res = await fetch(url, { headers: githubHeaders(), redirect: "follow" });
+  if (!res.ok) throw new Error(`Zip download failed: HTTP ${res.status}`);
+  const ab = await res.arrayBuffer();
+  return Buffer.from(ab);
+}
+async function unpackZipToDir(zipBuf, targetDir) {
+  const tmpDir = `${targetDir}.tmp`;
+  await fs3.rm(tmpDir, { recursive: true, force: true });
+  await fs3.mkdir(tmpDir, { recursive: true });
+  const zip = new AdmZip(zipBuf);
+  const entries = zip.getEntries();
+  for (const entry of entries) {
+    const normalized = entry.entryName.replace(/\\/g, "/");
+    const parts = normalized.split("/").filter(Boolean);
+    if (parts.length <= 1) continue;
+    const relPath = parts.slice(1).join("/");
+    if (!relPath) continue;
+    const abs = safeJoin(tmpDir, relPath);
+    if (entry.isDirectory) {
+      await fs3.mkdir(abs, { recursive: true });
+      continue;
+    }
+    await fs3.mkdir(path4.dirname(abs), { recursive: true });
+    await fs3.writeFile(abs, entry.getData());
+  }
+  await fs3.rm(targetDir, { recursive: true, force: true });
+  await fs3.rename(tmpDir, targetDir);
+}
+async function syncRepo(cfg, force = false) {
+  await fs3.mkdir(META_DIR, { recursive: true });
+  await fs3.mkdir(SOURCES_DIR, { recursive: true });
+  const metaPath = path4.join(META_DIR, `${cfg.key}.json`);
+  const sourceRoot = path4.join(SOURCES_DIR, cfg.key, "current");
+  const existing = await readJson(metaPath);
+  const now = Date.now();
+  const stale = !existing?.lastCheckedAt || now - existing.lastCheckedAt > UPDATE_TTL_MS;
+  if (!force && !stale && await exists(sourceRoot) && existing?.resolvedSha) {
+    return {
+      key: cfg.key,
+      rootDir: sourceRoot,
+      resolvedSha: existing.resolvedSha,
+      trackingRef: cfg.trackingRef,
+      lastZipHash: existing.lastZipHash,
+      lastCheckedAt: existing.lastCheckedAt,
+      stale: false
+    };
+  }
+  let remoteSha;
+  try {
+    remoteSha = await getRemoteSha(cfg);
+  } catch (error) {
+    if (await exists(sourceRoot) && existing?.resolvedSha) {
+      return {
+        key: cfg.key,
+        rootDir: sourceRoot,
+        resolvedSha: existing.resolvedSha,
+        trackingRef: cfg.trackingRef,
+        lastZipHash: existing.lastZipHash,
+        lastCheckedAt: existing.lastCheckedAt,
+        stale: true
+      };
+    }
+    throw error;
+  }
+  if (!force && remoteSha === existing?.lastRemoteSha && await exists(sourceRoot) && existing?.resolvedSha) {
+    const refreshed = {
+      ...existing,
+      trackingRef: cfg.trackingRef,
+      sourceUrl: `https://github.com/${cfg.owner}/${cfg.repo}`,
+      lastCheckedAt: now
+    };
+    await writeJson(metaPath, refreshed);
+    return {
+      key: cfg.key,
+      rootDir: sourceRoot,
+      resolvedSha: existing.resolvedSha,
+      trackingRef: cfg.trackingRef,
+      lastZipHash: existing.lastZipHash,
+      lastCheckedAt: now,
+      stale: false
+    };
+  }
+  const zipBuf = await downloadZip(cfg, remoteSha);
+  const zipHash = sha256(zipBuf);
+  if (!force && zipHash === existing?.lastZipHash && await exists(sourceRoot) && existing?.resolvedSha) {
+    const refreshed = {
+      ...existing,
+      trackingRef: cfg.trackingRef,
+      sourceUrl: `https://github.com/${cfg.owner}/${cfg.repo}`,
+      lastRemoteSha: remoteSha,
+      lastCheckedAt: now,
+      updatedAt: now
+    };
+    await writeJson(metaPath, refreshed);
+    return {
+      key: cfg.key,
+      rootDir: sourceRoot,
+      resolvedSha: existing.resolvedSha,
+      trackingRef: cfg.trackingRef,
+      lastZipHash: zipHash,
+      lastCheckedAt: now,
+      stale: false
+    };
+  }
+  await unpackZipToDir(zipBuf, sourceRoot);
+  const nextMeta = {
+    sourceUrl: `https://github.com/${cfg.owner}/${cfg.repo}`,
+    trackingRef: cfg.trackingRef,
+    resolvedSha: remoteSha,
+    lastRemoteSha: remoteSha,
+    lastZipHash: zipHash,
+    lastCheckedAt: now,
+    updatedAt: now
+  };
+  await writeJson(metaPath, nextMeta);
+  return {
+    key: cfg.key,
+    rootDir: sourceRoot,
+    resolvedSha: remoteSha,
+    trackingRef: cfg.trackingRef,
+    lastZipHash: zipHash,
+    lastCheckedAt: now,
+    stale: false
+  };
+}
+async function syncAllRepos(force = false) {
+  const states = await Promise.all(REPOS.map((repo) => syncRepo(repo, force)));
+  return Object.fromEntries(states.map((s) => [s.key, s]));
+}
+
+// src/state.ts
+async function initState(forceRefresh = false) {
+  await fs4.mkdir(CACHE_DIR, { recursive: true });
+  await fs4.mkdir(INDEX_DIR, { recursive: true });
+  const repos = await syncAllRepos(forceRefresh);
+  const oscar64Root = repos.oscar64.rootDir;
+  const tutorialsRoot = repos.OscarTutorials.rootDir;
+  const manualPath = path5.join(oscar64Root, "oscar64.md");
+  const manualText = await safeReadText(manualPath);
+  const { lines: manualLines, sections: manualSections } = parseManualSections(manualText);
+  const tutorials = await buildTutorialsIndex(tutorialsRoot);
+  const baseState = {
+    repos,
+    oscar64Root,
+    tutorialsRoot,
+    manualLines,
+    manualSections,
+    tutorials
+  };
+  return {
+    ...baseState,
+    docsSearch: buildDocsSearch(baseState)
+  };
+}
+
+// src/mcp/server.ts
+async function createOscarMcpServer(initialForceRefresh = false) {
+  let state = await initState(initialForceRefresh);
+  const getState = () => state;
+  const refreshState = async (force = false) => {
+    state = await initState(force);
+  };
+  const resources = makeResources(getState);
+  const tools = makeTools(getState, refreshState);
+  const server = new MCPServer({
+    id: "oscar64-docs-examples",
+    name: "Oscar64 Docs And Examples",
+    version: "0.1.0",
+    description: "Local MCP server exposing Oscar64 docs, SDK, samples, and OscarTutorials with HTTP zip sync and hash-based freshness checks.",
+    tools: {
+      search_docs: tools.searchDocs,
+      get_doc_section: tools.getDocSection,
+      search_code: tools.searchCode,
+      get_best_tutorial: tools.getBestTutorial,
+      refresh_sources: tools.refreshSources,
+      get_source_status: tools.getSourceStatus
+    },
+    resources
+  });
+  return { server, getState, refreshState };
+}
+
+// src/stdio.ts
+async function main() {
+  const { server } = await createOscarMcpServer(false);
+  await server.startStdio();
+}
+main().catch((error) => {
+  console.error("Failed to start MCP server:", error);
+  process.exit(1);
+});