oscar64-mcp-docs 1.0.0 → 1.0.1

package/README.md

@@ -76,7 +76,7 @@ The executable entry is built to `dist/stdio.js`.
 
 Primary tools:
 
-- `search(query, limit, system, include_details)` -> unified manual/code search with strict hit fields (`source`, `uri`, `title`, `snippet`, `score`, `classification_summary`), optional `referenced_files` as `code://...` URIs readable by `read_uri`, and optional `classification_details`; `system` defaults to `c64` and supports `all` for cross-system results
+- `search(query, limit, type, system, include_details)` -> unified manual/code search with strict hit fields (`source`, `result_type`, `uri`, `title`, `preview`, `score`, `classification_summary`), optional `referenced_files` as `code://...` URIs readable by `read_uri`, and optional `classification_details`; `type` defaults to `all`; `system` defaults to `c64` and supports `all` for cross-system results
 - `read_uri(uri, binary_mode, max_base64_bytes)` -> returns `ok + data` where `data.content_type` is `text` or `binary` for `docs://...` and `code://...`
 - `list_indexes(type, system)` -> lists `topics`/`tutorials`/`samples`/`headers` entries; `type` defaults to `headers`, `system` defaults to `c64`, and `system=all` returns cross-system indexes
 

package/dist/stdio.js

@@ -296,6 +296,7 @@ function matchesSystemFilter(systems, filter) {
 import { z } from "zod";
 var systemFamilySchema = z.enum(["c64", "c128", "vic20", "plus4", "nes", "x16", "pet", "atari", "mega65"]);
 var systemFilterSchema = z.enum(["all", "c64", "c128", "vic20", "plus4", "nes", "x16", "pet", "atari", "mega65"]);
+var searchTypeSchema = z.enum(["all", "topics", "tutorials", "samples", "headers"]);
 var toolErrorCodeSchema = z.enum([
   "INVALID_INPUT",
   "NOT_FOUND",
@@ -343,11 +344,18 @@ var classificationSummarySchema = z.object({
   systems: z.array(systemFamilySchema).describe("Detected target systems for this result; empty means shared/common."),
   scope: z.enum(["tutorial", "sample", "manual"]).describe("Content scope of this result.")
 });
+var searchPreviewSchema = z.object({
+  summary: z.string().describe("Compact preview summary for quick relevance checks."),
+  signature: z.string().optional().describe("Declaration-like line extracted from content when available."),
+  include_path: z.string().optional().describe("Header include path context when relevant."),
+  declaration_context: z.string().optional().describe("Nearby declaration context that helps disambiguate similar APIs.")
+});
 var searchHitSchema = z.object({
   source: z.enum(["manual", "code"]).describe("Where the result came from."),
+  result_type: z.enum(["topics", "tutorials", "samples", "headers"]).describe("Artifact type for this result."),
   uri: z.string().describe("URI to pass into `read_uri` for full content."),
   title: z.string().describe("Short title for the matched result."),
-  snippet: z.string().describe("Preview text to evaluate relevance before reading."),
+  preview: searchPreviewSchema.describe("Structured preview fields for relevance evaluation."),
   score: z.number().describe("Relative relevance score; higher means better match."),
   referenced_files: z.array(z.string()).optional().describe("Referenced `code://...` URIs that can be read with `read_uri` (for example from #embed or #include)."),
   classification_summary: classificationSummarySchema.describe("Compact classification metadata always returned."),
@@ -356,6 +364,7 @@ var searchHitSchema = z.object({
 var searchInputSchema = z.object({
   query: z.string().min(1).describe("Query text, symbol, API name, or error phrase to search for."),
   limit: z.number().int().min(1).max(80).default(20).describe("Maximum number of results to return."),
+  type: searchTypeSchema.default("all").describe("Filter results by artifact type. Defaults to `all`."),
   system: systemFilterSchema.default("c64").describe("Target system filter. Defaults to `c64`; use `all` for cross-system search."),
   include_details: z.boolean().default(false).describe("Set to true to include full classification details and evidence per hit.")
 });
@@ -763,6 +772,29 @@ function inferCombineMode(query) {
 function codeUri(scope, relPath) {
   return `code://${scope}/${relPath.replace(/\\/g, "/")}`;
 }
+function extractDeclarationInfo(text) {
+  const lines = text.split(/\r?\n/);
+  const looksLikeDeclaration = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return false;
+    if (/^#\s*define\s+[A-Za-z_][A-Za-z0-9_]*/.test(trimmed)) return true;
+    if (/^(?:extern|typedef)\b.+;/.test(trimmed)) return true;
+    if (/^[A-Za-z_][A-Za-z0-9_\s\*]+\([^;{}]*\)\s*;/.test(trimmed)) return true;
+    return false;
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (!looksLikeDeclaration(line)) continue;
+    const prev = lines.slice(Math.max(0, i - 1), i).find((v) => v.trim().length > 0)?.trim();
+    const next = lines.slice(i + 1, i + 3).find((v) => v.trim().length > 0)?.trim();
+    const context = [prev, line.trim(), next].filter(Boolean).join(" | ");
+    return {
+      signature: line.trim(),
+      declarationContext: context || void 0
+    };
+  }
+  return {};
+}
 function extractReferencedFiles(text) {
   const refs = /* @__PURE__ */ new Set();
   const addMatches = (regex, group = 1) => {
@@ -790,7 +822,7 @@ function resolveCollectionClassification(entries, relPath) {
 async function buildSearchIndex(state) {
   const ms = new MiniSearch({
     fields: ["title", "body"],
-    storeFields: ["source", "uri", "title", "snippet", "classification", "referencedFiles"],
+    storeFields: ["source", "resultType", "uri", "title", "preview", "body", "classification", "referencedFiles"],
     tokenize: oscarTokenizer,
     processTerm: oscarProcessTerm,
     searchOptions: {
@@ -806,9 +838,12 @@ async function buildSearchIndex(state) {
     docs.push({
       id: `manual:${section.anchor}`,
       source: "manual",
+      resultType: "topics",
       uri: `docs://oscar64/manual#${section.anchor}`,
       title: section.heading,
-      snippet: makeExcerpt(body),
+      preview: {
+        summary: makeExcerpt(body)
+      },
       body,
       classification: classifyV2({
         scope: "manual",
@@ -820,10 +855,16 @@ async function buildSearchIndex(state) {
   }
   const roots = [
     { scope: "tutorial", absRoot: state.tutorialsRoot },
-    { scope: "sample", absRoot: state.samplesRoot, uriPrefix: "samples" }
+    { scope: "sample", absRoot: state.samplesRoot, uriPrefix: "samples" },
+    { scope: "oscar", absRoot: path3.join(state.oscar64Root, "include"), uriPrefix: "include" }
   ];
   for (const root of roots) {
-    const files = await listFilesRecursive(root.absRoot);
+    let files = [];
+    try {
+      files = await listFilesRecursive(root.absRoot);
+    } catch {
+      continue;
+    }
     for (const abs of files) {
       const rel = abs.replace(root.absRoot + "/", "").replace(/\\/g, "/");
       const uriRel = root.uriPrefix ? `${root.uriPrefix}/${rel}` : rel;
@@ -834,18 +875,26 @@ async function buildSearchIndex(state) {
       } catch {
         continue;
       }
-      const collectionClassification = root.scope === "tutorial" ? resolveCollectionClassification(state.tutorials, rel) : resolveCollectionClassification(state.samples, rel);
+      const collectionClassification = root.scope === "tutorial" ? resolveCollectionClassification(state.tutorials, rel) : root.scope === "sample" ? resolveCollectionClassification(state.samples, rel) : null;
+      const declarationInfo = extractDeclarationInfo(text);
+      const resultType = root.scope === "tutorial" ? "tutorials" : root.scope === "sample" ? "samples" : "headers";
       docs.push({
         id: `${root.scope}:${uriRel}`,
         source: "code",
-        uri: root.scope === "sample" && !uriRel.startsWith("samples/") ? codeUri("oscar", uriRel) : codeUri(root.scope, uriRel),
+        resultType,
+        uri: root.scope === "sample" && !uriRel.startsWith("samples/") ? codeUri("oscar", uriRel) : codeUri(root.scope === "oscar" ? "oscar" : root.scope, uriRel),
         title: path3.basename(uriRel),
-        snippet: makeExcerpt(text, 700),
+        preview: {
+          summary: makeExcerpt(text, 700),
+          ...declarationInfo.signature ? { signature: declarationInfo.signature } : {},
+          ...declarationInfo.declarationContext ? { declarationContext: declarationInfo.declarationContext } : {},
+          ...resultType === "headers" ? { includePath: uriRel.replace(/^include\//, "") } : {}
+        },
         body: `${uriRel}
 ${text}`,
         referencedFiles: extractReferencedFiles(text),
         classification: collectionClassification ?? classifyV2({
-          scope: root.scope,
+          scope: root.scope === "oscar" ? "sample" : root.scope,
           title: path3.basename(uriRel),
           relPath: uriRel,
           text
@@ -1605,8 +1654,90 @@ async function resolveReferencedUris(state, sourceUri, refs) {
   }
   return out.length > 0 ? out : void 0;
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function looksLikeDeclarationLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  if (/^#\s*define\s+[A-Za-z_][A-Za-z0-9_]*/.test(trimmed)) return true;
+  if (/^(?:extern|typedef)\b.+;/.test(trimmed)) return true;
+  if (/^[A-Za-z_][A-Za-z0-9_\s\*]+\([^;{}]*\)\s*;/.test(trimmed)) return true;
+  return false;
+}
+function inferResultType(result) {
+  if (result?.resultType === "topics" || result?.resultType === "tutorials" || result?.resultType === "samples" || result?.resultType === "headers") {
+    return result.resultType;
+  }
+  const uri = String(result?.uri ?? "");
+  if (uri.startsWith("docs://")) return "topics";
+  if (uri.startsWith("code://tutorial/")) return "tutorials";
+  if (uri.startsWith("code://sample/")) return "samples";
+  if (uri.startsWith("code://oscar/include/") && uri.toLowerCase().endsWith(".h")) return "headers";
+  return "samples";
+}
+function buildPreview(result, query) {
+  const uri = String(result?.uri ?? "");
+  const body = String(result?.body ?? "");
+  const fallbackSummary = makeExcerpt(String(result?.snippet ?? ""), 700);
+  const basePreview = typeof result?.preview === "object" && result.preview ? result.preview : { summary: fallbackSummary };
+  let signature = typeof basePreview.signature === "string" && basePreview.signature.trim().length > 0 ? basePreview.signature.trim() : void 0;
+  let declarationContext = typeof basePreview.declarationContext === "string" && basePreview.declarationContext.trim().length > 0 ? basePreview.declarationContext.trim() : void 0;
+  if (body && query.trim()) {
+    const queryWord = query.trim().toLowerCase();
+    const matcher = new RegExp(`\\b${escapeRegExp(queryWord)}\\b`);
+    const lines = body.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = String(lines[i] ?? "");
+      const lower = line.toLowerCase();
+      if (!lower.includes(queryWord)) continue;
+      if (!matcher.test(lower) || !looksLikeDeclarationLine(line)) continue;
+      signature = signature ?? line.trim();
+      const prev = lines.slice(Math.max(0, i - 1), i).find((v) => String(v).trim().length > 0)?.trim();
+      const next = lines.slice(i + 1, i + 3).find((v) => String(v).trim().length > 0)?.trim();
+      declarationContext = declarationContext ?? [prev, line.trim(), next].filter(Boolean).join(" | ");
+      break;
+    }
+  }
+  const includePathFromUri = uri.startsWith("code://oscar/include/") ? uri.replace("code://oscar/include/", "") : void 0;
+  const includePath = typeof basePreview.includePath === "string" && basePreview.includePath.trim().length > 0 ? basePreview.includePath.trim() : includePathFromUri;
+  const summaryCandidate = typeof basePreview.summary === "string" && basePreview.summary.trim().length > 0 ? basePreview.summary : fallbackSummary;
+  return {
+    summary: summaryCandidate || makeExcerpt(body || String(result?.title ?? ""), 700),
+    ...signature ? { signature } : {},
+    ...includePath ? { include_path: includePath } : {},
+    ...declarationContext ? { declaration_context: declarationContext } : {}
+  };
+}
+function computeSymbolBoost(result, query) {
+  const symbol = query.trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(symbol)) return 0;
+  const symbolLower = symbol.toLowerCase();
+  let boost = 0;
+  const title = String(result?.title ?? "").toLowerCase();
+  const titleBase = title.replace(/\.[a-z0-9]+$/i, "");
+  if (title === symbolLower || titleBase === symbolLower) boost += 90;
+  const body = String(result?.body ?? "");
+  if (body) {
+    const exactWord = new RegExp(`\\b${escapeRegExp(symbolLower)}\\b`);
+    const lines = body.split(/\r?\n/);
+    for (const line of lines) {
+      const lower = line.toLowerCase();
+      if (!lower.includes(symbolLower)) continue;
+      if (exactWord.test(lower)) {
+        boost = Math.max(boost, looksLikeDeclarationLine(line) ? 70 : 28);
+        break;
+      }
+      boost = Math.max(boost, 10);
+    }
+  }
+  const uri = String(result?.uri ?? "");
+  if (boost > 0 && uri.startsWith("code://oscar/include/")) boost += 12;
+  return boost;
+}
 async function executeSearch(context) {
   const { query, limit, include_details } = context;
+  const requestedType = context.type ?? "all";
   const system = context.system ?? "c64";
   const state = await getStateSnapshot();
   const toFallbackClassification = () => ({
@@ -1672,14 +1803,17 @@ async function executeSearch(context) {
     rawResults.map(async (result) => {
       const details = toDetails(result.classification);
       const referencedUris = await resolveReferencedUris(state, String(result.uri ?? ""), result.referencedFiles);
+      const resultType = inferResultType(result);
+      const rerankBoost = computeSymbolBoost(result, query);
       return {
-        score: result.score ?? 0,
+        score: (result.score ?? 0) + rerankBoost,
         hit: {
           source: result.source === "manual" ? "manual" : "code",
+          result_type: resultType,
           uri: String(result.uri ?? ""),
           title: String(result.title ?? ""),
-          snippet: String(result.snippet ?? ""),
-          score: result.score ?? 0,
+          preview: buildPreview(result, query),
+          score: (result.score ?? 0) + rerankBoost,
           ...referencedUris ? { referenced_files: referencedUris } : {},
           classification_summary: toSummary(details),
           ...include_details ? { classification_details: details } : {}
@@ -1687,7 +1821,7 @@ async function executeSearch(context) {
       };
     })
   );
-  const hits = mapped.filter((entry) => matchesSystemFilter(entry.hit.classification_summary.systems, system)).sort((a, b) => b.score - a.score || a.hit.uri.localeCompare(b.hit.uri)).slice(0, limit);
+  const hits = mapped.filter((entry) => requestedType === "all" || entry.hit.result_type === requestedType).filter((entry) => matchesSystemFilter(entry.hit.classification_summary.systems, system)).sort((a, b) => b.score - a.score || a.hit.uri.localeCompare(b.hit.uri)).slice(0, limit);
   return {
     ok: true,
     data: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oscar64-mcp-docs",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "type": "module",
   "files": [