@telvok/librarian-mcp 1.0.2 → 1.1.0

package/dist/server.js

@@ -5,6 +5,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { briefTool } from './tools/brief.js';
 import { recordTool } from './tools/record.js';
 import { adoptTool } from './tools/adopt.js';
+import { markHitTool } from './tools/mark-hit.js';
 const server = new Server({
     name: 'librarian',
     version: '1.0.0',
@@ -32,6 +33,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: adoptTool.description,
                 inputSchema: adoptTool.inputSchema,
             },
+            {
+                name: markHitTool.name,
+                description: markHitTool.description,
+                inputSchema: markHitTool.inputSchema,
+            },
         ],
     };
 });
@@ -50,6 +56,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'adopt':
                 result = await adoptTool.handler(args);
                 break;
+            case 'mark_hit':
+                result = await markHitTool.handler(args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/tools/brief.d.ts

@@ -5,6 +5,8 @@ export interface BriefEntry {
     preview: string;
     path: string;
     created: string;
+    hits: number;
+    last_hit: string | null;
 }
 export interface BriefResult {
     entries: BriefEntry[];

package/dist/tools/brief.js

@@ -79,10 +79,9 @@ Examples:
             const searchTerm = query.toLowerCase();
             allEntries = allEntries.filter(entry => matchesSearch(entry, searchTerm));
         }
-        // Sort by created date (most recent first)
-        allEntries.sort((a, b) => {
-            return new Date(b.created).getTime() - new Date(a.created).getTime();
-        });
+        // Sort by blended score: 60% recency + 40% hits
+        // Entries that helped before bubble up, but new entries still surface
+        allEntries = rankEntries(allEntries);
         const total = allEntries.length;
         // Apply limit
         const entries = allEntries.slice(0, limit);
@@ -134,6 +133,8 @@ async function readEntry(filePath, libraryPath) {
             preview,
             path: path.relative(libraryPath, filePath),
             created: data.created || new Date().toISOString(),
+            hits: typeof data.hits === 'number' ? data.hits : 0,
+            last_hit: data.last_hit || null,
         };
     }
     catch {
@@ -159,3 +160,31 @@ function matchesSearch(entry, searchTerm) {
     }
     return false;
 }
+// ============================================================================
+// Smart Ranking
+// ============================================================================
+const RECENCY_WEIGHT = 0.6;
+const HITS_WEIGHT = 0.4;
+const RECENCY_DECAY_DAYS = 30; // Entries older than this get minimal recency score
+function rankEntries(entries) {
+    if (entries.length === 0)
+        return entries;
+    const now = Date.now();
+    // Find max hits for normalization (avoid divide by zero)
+    const maxHits = Math.max(1, ...entries.map(e => e.hits));
+    // Calculate scores
+    const scored = entries.map(entry => {
+        // Recency score: 1.0 for today, decays over RECENCY_DECAY_DAYS
+        const ageMs = now - new Date(entry.created).getTime();
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        const recencyScore = Math.max(0, 1 - (ageDays / RECENCY_DECAY_DAYS));
+        // Hits score: normalized 0-1 against max hits in library
+        const hitsScore = entry.hits / maxHits;
+        // Blended score
+        const score = (RECENCY_WEIGHT * recencyScore) + (HITS_WEIGHT * hitsScore);
+        return { entry, score };
+    });
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map(s => s.entry);
+}

package/dist/tools/index.d.ts

@@ -1,3 +1,4 @@
 export { briefTool } from './brief.js';
 export { recordTool } from './record.js';
 export { adoptTool } from './adopt.js';
+export { markHitTool } from './mark-hit.js';

package/dist/tools/index.js

@@ -1,3 +1,4 @@
 export { briefTool } from './brief.js';
 export { recordTool } from './record.js';
 export { adoptTool } from './adopt.js';
+export { markHitTool } from './mark-hit.js';

package/dist/tools/mark-hit.d.ts

@@ -0,0 +1,20 @@
+export interface MarkHitResult {
+    success: boolean;
+    path: string;
+    hits: number;
+}
+export declare const markHitTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<MarkHitResult>;
+};

package/dist/tools/mark-hit.js

@@ -0,0 +1,71 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { getLibraryPath } from '../library/storage.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const markHitTool = {
+    name: 'mark_hit',
+    description: `Mark a library entry as helpful - call this when knowledge from the library helped solve a problem.
+
+When an entry from brief() actually helped you complete a task or make a decision,
+call mark_hit() on it. This helps the library learn which entries are most useful.
+
+Entries with more hits bubble up in future brief() results.
+
+Fire and forget - call it and move on.
+
+Example:
+- mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the entry that helped (from brief() results)',
+            },
+        },
+        required: ['path'],
+    },
+    async handler(args) {
+        const { path: entryPath } = args;
+        if (!entryPath) {
+            throw new Error('path is required');
+        }
+        const libraryPath = getLibraryPath();
+        // Resolve the full path
+        let fullPath;
+        if (path.isAbsolute(entryPath)) {
+            fullPath = entryPath;
+        }
+        else {
+            fullPath = path.join(libraryPath, entryPath);
+        }
+        // Read existing file
+        let content;
+        try {
+            content = await fs.readFile(fullPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`Entry not found: ${entryPath}`);
+        }
+        // Parse frontmatter
+        const { data, content: body } = matter(content);
+        // Increment hits
+        const currentHits = typeof data.hits === 'number' ? data.hits : 0;
+        const newHits = currentHits + 1;
+        // Update frontmatter
+        data.hits = newHits;
+        data.last_hit = new Date().toISOString();
+        // Rebuild file content
+        const updatedContent = matter.stringify(body, data);
+        // Write back
+        await fs.writeFile(fullPath, updatedContent, 'utf-8');
+        return {
+            success: true,
+            path: entryPath,
+            hits: newHits,
+        };
+    },
+};

package/dist/tools/record.js

@@ -36,9 +36,11 @@ Quick:
 
 Rich:
 - record({
+    intent: "Setting up GitHub org for Telvok",
     insight: "GitHub org names are first-come-first-served regardless of domain ownership",
     context: "GitHub, npm, branding",
-    reasoning: "We owned telvok.com but someone squatted telvok org years ago"
+    reasoning: "We owned telvok.com but someone squatted telvok org years ago",
+    example: "Had to use telvokdev instead of telvok"
   })`,
     inputSchema: {
         type: 'object',
@@ -104,6 +106,8 @@ Rich:
         frontmatterLines.push(`created: "${created}"`);
         frontmatterLines.push(`updated: "${created}"`);
         frontmatterLines.push('source: "local"');
+        frontmatterLines.push('hits: 0');
+        frontmatterLines.push('last_hit: null');
         frontmatterLines.push('---');
         // Build body
         const bodyLines = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telvok/librarian-mcp",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Knowledge capture MCP server - remember what you learn with AI",
   "type": "module",
   "main": "dist/server.js",