oscar64-mcp-docs 1.1.3 → 1.1.4

package/README.md

@@ -76,7 +76,7 @@ The executable entry is built to `dist/stdio.js`.
 
 Primary tools:
 
-- `search(query, limit, type, system, strict, min_confidence, debug_scoring)` -> unified manual/code search with agent-facing hit fields (`result_type`, `uri`, `title`, `preview`, `confidence`, `match_reasons`, `classification_summary`), optional `referenced_files` as `code://...` URIs readable by `read_uri`; `strict` suppresses broad fallback-only results, `min_confidence` applies threshold filtering, and strict/threshold no-match responses return `quality_status`, `failure_reasons`, and `suggested_refinement`; `debug_scoring=true` adds per-hit scoring diagnostics
+- `search(query, limit, type, system, strict, min_confidence, debug_scoring)` -> unified manual/code search with agent-facing hit fields (`result_type`, `uri`, `title`, `preview`, `confidence`, `confidence_level`, `match_reasons`, `classification_summary`), optional `referenced_files` as `code://...` URIs readable by `read_uri`; `strict` requires at least one exact/API match reason (symbol/include/anchor/address/API token), `min_confidence` applies threshold filtering, and insufficient-quality responses return `quality_status`, `failure_reasons`, and `suggested_refinement`; `debug_scoring=true` adds per-hit scoring diagnostics
 - `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
 
@@ -94,4 +94,3 @@ Standard tool output envelope:
 Index discovery:
 
 - `list_indexes(type)` returns only `docs://` and `code://` URIs that can be read directly with `read_uri`.
-

package/dist/stdio.js

@@ -421,6 +421,7 @@ var searchHitDebugScoringSchema = z.object({
   base_score: z.number().describe("Original backend search score for this hit."),
   confidence_raw: z.number().describe("Unclamped confidence before range enforcement.")
 });
+var confidenceLevelSchema = z.enum(["high", "medium", "low"]).describe("Deterministic confidence bucket derived from confidence.");
 var searchHitSchema = z.object({
   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."),
@@ -428,6 +429,7 @@ var searchHitSchema = z.object({
   preview: searchPreviewSchema.describe("Structured preview fields for relevance evaluation."),
   referenced_files: z.array(z.string()).optional().describe("Referenced `code://...` URIs that can be read with `read_uri` (for example from #embed or #include)."),
   confidence: z.number().min(0).max(1).describe("Normalized confidence score in range 0..1."),
+  confidence_level: confidenceLevelSchema,
   match_reasons: z.array(matchReasonSchema).min(1).describe("Deterministic ordered reason list for this hit."),
   debug_scoring: searchHitDebugScoringSchema.optional().describe("Per-hit scoring diagnostics, only present when debug_scoring=true."),
   classification_summary: classificationSummarySchema.describe("Compact classification metadata always returned.")
@@ -2057,6 +2059,13 @@ var REASON_WEIGHTS = {
   topic_semantic_match: 0.18,
   fallback_broad_match: 0.08
 };
+var STRICT_ACCEPTED_REASON_CODES = /* @__PURE__ */ new Set([
+  "exact_symbol_match",
+  "exact_include_path_match",
+  "exact_manual_anchor_match",
+  "register_or_address_exact_match",
+  "api_name_token_match"
+]);
 function pushReason(out, code) {
   if (out.some((item) => item.code === code)) return;
   out.push({ code, weight: REASON_WEIGHTS[code] });
@@ -2065,6 +2074,11 @@ function toDeterministicConfidence(value) {
   const clamped = Math.max(0.02, Math.min(0.99, value));
   return Number(clamped.toFixed(3));
 }
+function toConfidenceLevel(confidence) {
+  if (confidence >= 0.8) return "high";
+  if (confidence >= 0.55) return "medium";
+  return "low";
+}
 function computeScoredReasons(hit) {
   const reasons = [];
   const uriLower = hit.uri.toLowerCase();
@@ -2190,6 +2204,7 @@ async function executeSearch(context) {
           preview,
           ...referencedUris ? { referenced_files: referencedUris } : {},
           confidence: scored.confidence,
+          confidence_level: toConfidenceLevel(scored.confidence),
           match_reasons: scored.reasons,
           ...debugScoring ? {
             debug_scoring: {
@@ -2210,7 +2225,7 @@ async function executeSearch(context) {
   }).filter((entry) => requestedType === "all" || entry.hit.result_type === requestedType).filter((entry) => matchesSystemFilter(entry.systems, system));
   const filteredHits = candidateHits.filter((entry) => !(entry.matchReasons.length === 1 && entry.matchReasons[0]?.code === "fallback_broad_match")).filter((entry) => {
     if (!strict) return true;
-    return !(entry.matchReasons.length === 1 && entry.matchReasons[0]?.code === "fallback_broad_match");
+    return entry.matchReasons.some((reason) => STRICT_ACCEPTED_REASON_CODES.has(reason.code));
   }).filter((entry) => typeof minConfidence === "number" ? entry.confidence >= minConfidence : true).sort((a, b) => b.confidence - a.confidence || a.hit.uri.localeCompare(b.hit.uri)).slice(0, limit);
   if (filteredHits.length === 0) {
     const reasonCounts = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oscar64-mcp-docs",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "private": false,
   "type": "module",
   "engines": {