@ema.co/mcp-toolkit 2026.4.9-1 → 2026.4.9-2

package/dist/knowledge/pipeline/confidence.js

@@ -85,6 +85,19 @@ export function scoreToLabel(score) {
         return "inferred";
     return "low-confidence";
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Fragment helpers — GitHub-style #fragment on knowledge_ref
+// ─────────────────────────────────────────────────────────────────────────────
+/** Strip #fragment from a knowledge_ref, returning the bare document ID. */
+export function stripFragment(ref) {
+    const idx = ref.indexOf("#");
+    return idx === -1 ? ref : ref.slice(0, idx);
+}
+/** Extract the #fragment from a knowledge_ref, or undefined if none. */
+export function extractFragment(ref) {
+    const idx = ref.indexOf("#");
+    return idx === -1 ? undefined : ref.slice(idx + 1);
+}
 /**
  * Compute confidence adjustment based on the ratio of negative to total feedback.
  *

package/dist/knowledge/pipeline/document.js

@@ -34,20 +34,30 @@ export function toDeDocument(doc) {
     const textContent = doc.structData?.content
         || [doc.structData?.name, doc.structData?.summary, doc.structData?.description].filter(Boolean).join("\n");
     const contentHash = computeContentHash(textContent || doc.id);
+    const now = new Date().toISOString();
     const augmented = {
         ...doc.structData,
         content_hash: contentHash,
-        augmented_at: new Date().toISOString(),
+        augmented_at: now,
         status: doc.structData?.status ?? "active",
         confidence_score: doc.structData?.confidence_score
             ?? computeConfidenceScore(doc.structData?.provenance ?? "inferred"),
+        // Lifecycle timestamps — set once at publish, preserved on re-publish
+        // Aligned with knowledge-service's 3-layer model (produced_at/published_at)
+        published_at: doc.structData?.published_at ?? now,
+        produced_at: doc.structData?.produced_at ?? now,
     };
-    // Compute freshness_tier from TTL if present (set by extraction pipeline from YAML config)
+    // Compute freshness_tier: TTL-based (explicit) or content-age (universal)
     if (doc.structData?.ttl) {
         const tier = computeFreshnessTier(doc.structData.ttl, doc.structData.extracted_at);
         if (tier)
             augmented.freshness_tier = tier;
     }
+    else {
+        const tier = computeContentFreshnessTier(augmented.produced_at);
+        if (tier)
+            augmented.freshness_tier = tier;
+    }
     augmentByType(doc, augmented);
     return {
         id: sanitizeId(doc.id),
@@ -58,6 +68,25 @@ export function toDeDocument(doc) {
         },
     };
 }
+/**
+ * Universal content-age freshness tier (no TTL config required).
+ * Applies to all docs via produced_at — DE's boost-fresh/demote-expired
+ * controls handle the ranking impact.
+ */
+// TODO(knowledge-service): migrate alongside computeFreshnessTier when shared lib is ready
+export function computeContentFreshnessTier(producedAt) {
+    if (!producedAt)
+        return undefined;
+    const ageMs = Date.now() - new Date(producedAt).getTime();
+    if (Number.isNaN(ageMs))
+        return undefined;
+    const ageDays = ageMs / (86_400_000);
+    if (ageDays < 7)
+        return "fresh";
+    if (ageDays >= 90)
+        return "stale";
+    return undefined; // neutral — no boost or penalty
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Type-Dispatched Augmentation
 // ─────────────────────────────────────────────────────────────────────────────

package/dist/mcp/guidance.js

@@ -198,7 +198,7 @@ function formatToolSection(tg) {
     }
     if (tg.toolName === "feedback") {
         extras.push("\nYour feedback is automatically collected and analyzed to improve the toolkit for all agents.");
-        extras.push("Include `knowledge_ref=\"<doc_id>\"` to correlate feedback with specific knowledge documents — this drives automatic confidence scoring (documents with high negative feedback are auto-downgraded).");
+        extras.push("Include `knowledge_ref` to correlate feedback with specific knowledge documents — this drives automatic confidence scoring (documents with high negative feedback are auto-downgraded). Use `#fragment` for sub-document precision: `knowledge_ref=\"topic_auth#L51-L56\"` (lines), `knowledge_ref=\"topic_auth#authentication\"` (section). Same as GitHub URL fragments.");
     }
     return `## ${title}
 Use the \`${tg.toolName}\` tool${tg.quickTip ? `. ${tg.quickTip}` : ""}:

package/dist/mcp/handlers/feedback/index.js

@@ -17,6 +17,7 @@ import { markProbeResponded } from "./probes.js";
 import { appendToOutbox, flushOutbox, getOutboxStats, readLocalMessages } from "./outbox.js";
 import { isRemoteEnabled } from "./remote-store.js";
 import { writeUserEvent } from "../../../knowledge/search-client.js";
+import { stripFragment } from "../../../knowledge/pipeline/confidence.js";
 import { getOrCreateClientId } from "./client-id.js";
 import { getAttributionToken } from "../knowledge/session-state.js";
 import { analyzeGlobal } from "./global-analysis.js";
@@ -134,19 +135,22 @@ async function handleSubmit(args) {
         }
     }
     // Confidence loop: if feedback references a knowledge doc, update its confidence in DE
+    // Strip #fragment — confidence scoring operates at the document level
     let confidenceUpdate;
-    if (knowledgeRef && CONFIDENCE_CATEGORIES.includes(category)) {
+    const docId = knowledgeRef ? stripFragment(knowledgeRef) : undefined;
+    if (docId && CONFIDENCE_CATEGORIES.includes(category)) {
         try {
             const { processConfidenceFeedback } = await import("../knowledge/confidence-loop.js");
-            confidenceUpdate = await processConfidenceFeedback(category, knowledgeRef, qualityData) ?? undefined;
+            confidenceUpdate = await processConfidenceFeedback(category, docId, qualityData) ?? undefined;
         }
         catch {
             // Best-effort — don't block feedback submission
         }
     }
     // UserEvent emission: fire DE conversion/view-item for positive feedback with knowledge_ref.
+    // Strip fragment — DE attribution tokens and document IDs are doc-level.
     // Independent of confidence loop — no guards, no cooldown. Fire-and-forget.
-    if (knowledgeRef) {
+    if (docId) {
         const isSuccess = category === "success";
         const isHighQuality = category === "quality"
             && (qualityData?.accuracy ?? 0) >= 4
@@ -158,13 +162,13 @@ async function handleSubmit(args) {
                     : undefined; // interaction → view-item, no conversionType
             getOrCreateClientId()
                 .then((clientId) => {
-                const token = getAttributionToken(knowledgeRef);
+                const token = getAttributionToken(docId);
                 writeUserEvent({
                     eventType: conversionType ? "conversion" : "view-item",
                     userPseudoId: clientId,
                     ...(token ? { attributionToken: token } : {}),
                     documents: [{
-                            id: knowledgeRef,
+                            id: docId,
                             ...(conversionType ? { conversionValue: isSuccess ? 1.0 : 0.8 } : {}),
                         }],
                     ...(conversionType ? { conversionType } : {}),

package/dist/mcp/handlers/feedback/store.js

@@ -22,7 +22,7 @@ import { SESSION_ID } from "./session.js";
 // Category classification lives in confidence.ts (knowledge pipeline layer)
 // Re-export here so feedback handlers can use it without reaching into pipeline internals
 export { FeedbackSignal, CATEGORY_SIGNAL, } from "../../../knowledge/pipeline/confidence.js";
-import { CATEGORY_SIGNAL, FeedbackSignal } from "../../../knowledge/pipeline/confidence.js";
+import { CATEGORY_SIGNAL, FeedbackSignal, stripFragment, extractFragment } from "../../../knowledge/pipeline/confidence.js";
 /** All valid category names — derived from the signal map */
 export const ALL_CATEGORIES = Object.keys(CATEGORY_SIGNAL);
 /** Categories that affect confidence scoring (negative, positive, or quality) */
@@ -359,28 +359,42 @@ export async function analyzeFeedback(rootOverride) {
     };
     deduplicateEntries(feedback.filter((e) => e.category === "gap"), "Documentation gap");
     deduplicateEntries(feedback.filter((e) => e.category === "confusion"), "Unclear guidance");
-    // Graph-correlated insights: group feedback by knowledge_ref
+    // Graph-correlated insights: group feedback by knowledge_ref (doc-level)
+    // Fragment hotspots tracked per document (e.g., "L51-L56": 3)
     const graphCorrelations = {};
     for (const entry of feedback) {
         const ref = entry.quality_data?.knowledge_ref;
         if (!ref)
             continue;
-        if (!graphCorrelations[ref]) {
-            graphCorrelations[ref] = { count: 0, categories: {} };
+        const docId = stripFragment(ref);
+        const fragment = extractFragment(ref);
+        if (!graphCorrelations[docId]) {
+            graphCorrelations[docId] = { count: 0, categories: {} };
+        }
+        graphCorrelations[docId].count++;
+        graphCorrelations[docId].categories[entry.category] =
+            (graphCorrelations[docId].categories[entry.category] ?? 0) + 1;
+        if (fragment) {
+            if (!graphCorrelations[docId].fragments) {
+                graphCorrelations[docId].fragments = {};
+            }
+            graphCorrelations[docId].fragments[fragment] =
+                (graphCorrelations[docId].fragments[fragment] ?? 0) + 1;
         }
-        graphCorrelations[ref].count++;
-        graphCorrelations[ref].categories[entry.category] =
-            (graphCorrelations[ref].categories[entry.category] ?? 0) + 1;
     }
     // Compute average accuracy for quality-rated nodes
     for (const entry of feedback) {
         const ref = entry.quality_data?.knowledge_ref;
         if (!ref || !entry.quality_data?.accuracy)
             continue;
-        const corr = graphCorrelations[ref];
+        const docId = stripFragment(ref);
+        const corr = graphCorrelations[docId];
         if (!corr)
             continue;
-        const qualityEntries = feedback.filter((e) => e.quality_data?.knowledge_ref === ref && e.quality_data?.accuracy != null);
+        const qualityEntries = feedback.filter((e) => {
+            const eRef = e.quality_data?.knowledge_ref;
+            return eRef && stripFragment(eRef) === docId && e.quality_data?.accuracy != null;
+        });
         corr.avgAccuracy =
             qualityEntries.reduce((sum, e) => sum + (e.quality_data.accuracy ?? 0), 0) /
                 qualityEntries.length;

package/dist/mcp/tools.js

@@ -786,10 +786,11 @@ A **profile** = tenant + environment + auth. Example: "acme-corp-prod" = Acme Co
 - \`feedback(method="submit", category="suggestion", message="...")\` - suggest improvements
 - \`feedback(method="submit", category="probe_response", message="<answer>", context="<probe.id>")\` - respond to a _probe question
 - \`feedback(method="submit", category="quality", message="...", knowledge_ref="topic_authentication")\` - rate knowledge accuracy (drives confidence scoring)
-- \`feedback(method="submit", category="correction", message="...", knowledge_ref="rule_get-before-modify")\` - report wrong information
+- \`feedback(method="submit", category="correction", message="...", knowledge_ref="rule_get-before-modify#L51-L56")\` - report wrong info at specific lines
+- \`feedback(method="submit", category="correction", message="...", knowledge_ref="topic_auth#authentication")\` - report issue in a section
 
 ## Knowledge Confidence
-Include \`knowledge_ref\` to correlate feedback with specific knowledge documents. Documents with high negative feedback are auto-downgraded in search results.
+Include \`knowledge_ref\` to correlate feedback with specific knowledge documents. Use \`#fragment\` for sub-document precision (e.g., \`topic_auth#L51-L56\` for lines, \`topic_auth#authentication\` for sections). Documents with high negative feedback are auto-downgraded in search results.
 
 ## Review Feedback
 - \`feedback(method="list")\` - view recent feedback
@@ -842,7 +843,7 @@ Messages are emitted by MCP response actions (search, publish, deploy) and stay
                     },
                     knowledge_ref: {
                         type: "string",
-                        description: "Knowledge document ID this feedback relates to (e.g. 'topic_authentication', 'rule_get-before-modify'). Drives automatic confidence scoring — documents with negative feedback rank lower in search.",
+                        description: "Knowledge document ID, optionally with #fragment for sub-document precision. Examples: 'topic_auth', 'topic_auth#L51-L56' (lines), 'topic_auth#L51' (single line), 'topic_auth#authentication' (section). Same as GitHub URL fragments. Drives confidence scoring at the document level (fragment stripped for scoring, preserved for reporting).",
                     },
                     severity: {
                         type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.4.9-1",
+  "version": "2026.4.9-2",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",