@telvok/librarian-mcp 1.0.0

package/dist/tools/adopt.js

@@ -0,0 +1,143 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { getLibraryPath, getImportedPath, getLocalPath } from '../library/storage.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const adoptTool = {
+    name: 'adopt',
+    description: `Make imported knowledge ours.
+
+When an entry from an imported package proves useful, adopt it into our
+local library. It graduates from "their knowledge" to "our knowledge" -
+now we can edit and evolve it.
+
+Examples:
+- adopt({ path: "imported/stripe-patterns/webhook-idempotency" })
+- adopt({ path: "imported/auth-patterns/token-refresh", title: "Our token refresh" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: "Path to entry to adopt (e.g., 'imported/package-name/entry-name')",
+            },
+            title: {
+                type: 'string',
+                description: 'New title for adopted entry. Keeps original if not provided.',
+            },
+        },
+        required: ['path'],
+    },
+    async handler(args) {
+        const { path: entryPath, title: newTitle } = args;
+        if (!entryPath) {
+            throw new Error('path is required');
+        }
+        const libraryPath = getLibraryPath();
+        const importedPath = getImportedPath(libraryPath);
+        const localPath = getLocalPath(libraryPath);
+        // Normalize path: strip "imported/" prefix if present, add .md if missing
+        let normalizedPath = entryPath;
+        if (normalizedPath.startsWith('imported/')) {
+            normalizedPath = normalizedPath.slice('imported/'.length);
+        }
+        if (!normalizedPath.endsWith('.md')) {
+            normalizedPath += '.md';
+        }
+        const sourcePath = path.join(importedPath, normalizedPath);
+        // Check if source exists
+        try {
+            await fs.access(sourcePath);
+        }
+        catch {
+            throw new Error(`Entry not found: ${entryPath}`);
+        }
+        // Read source file
+        const content = await fs.readFile(sourcePath, 'utf-8');
+        const { data, content: body } = matter(content);
+        // Extract package name from path
+        const pathParts = normalizedPath.split('/');
+        const packageName = pathParts[0];
+        // Determine title
+        let title = newTitle;
+        if (!title) {
+            // Try to extract from frontmatter or H1
+            title = data.title;
+            if (!title) {
+                const headingMatch = body.match(/^#\s+(.+)$/m);
+                if (headingMatch) {
+                    title = headingMatch[1].trim();
+                }
+                else {
+                    title = path.basename(sourcePath, '.md').replace(/-/g, ' ');
+                }
+            }
+        }
+        // Generate slug for new filename
+        const slug = slugify(title);
+        const now = new Date().toISOString();
+        // Ensure local directory exists
+        await fs.mkdir(localPath, { recursive: true });
+        // Handle filename collisions
+        let filename = `${slug}.md`;
+        let destPath = path.join(localPath, filename);
+        let counter = 1;
+        while (await fileExists(destPath)) {
+            filename = `${slug}-${counter}.md`;
+            destPath = path.join(localPath, filename);
+            counter++;
+        }
+        // Build new frontmatter
+        const newFrontmatter = {
+            ...data,
+            updated: now,
+            source: `adopted from ${packageName}`,
+        };
+        // Update title in frontmatter if changed
+        if (newTitle) {
+            newFrontmatter.title = newTitle;
+        }
+        // Update body if title changed
+        let newBody = body;
+        if (newTitle) {
+            // Replace first H1 if exists
+            const headingMatch = body.match(/^#\s+.+$/m);
+            if (headingMatch) {
+                newBody = body.replace(/^#\s+.+$/m, `# ${newTitle}`);
+            }
+            else {
+                // Prepend title
+                newBody = `# ${newTitle}\n\n${body}`;
+            }
+        }
+        // Write adopted file
+        const fileContent = matter.stringify(newBody, newFrontmatter);
+        await fs.writeFile(destPath, fileContent, 'utf-8');
+        return {
+            success: true,
+            from: path.relative(libraryPath, sourcePath),
+            to: path.relative(libraryPath, destPath),
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools/brief.d.ts

@@ -0,0 +1,34 @@
+export interface BriefEntry {
+    title: string;
+    intent: string | null;
+    context: string | null;
+    preview: string;
+    path: string;
+    created: string;
+}
+export interface BriefResult {
+    entries: BriefEntry[];
+    total: number;
+    message: string;
+    libraryPath: string;
+}
+export declare const briefTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<BriefResult>;
+};

package/dist/tools/brief.js

@@ -0,0 +1,161 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { glob } from 'glob';
+import { getLibraryPath, getLocalPath, getImportedPath } from '../library/storage.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const briefTool = {
+    name: 'brief',
+    description: `Check what we already know before diving in.
+
+We've solved problems before. Before thinking through a problem, making
+decisions, or planning - brief yourself on what past-us figured out.
+Searches intent, insight, context, and examples.
+
+Examples:
+- brief({ query: "stripe webhooks" })
+- brief({ query: "auth token" })
+- brief({}) → returns recent entries`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'What are we working on? Searches our library. Leave empty to see recent entries.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Max entries to return',
+                default: 5,
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { query, limit = 5 } = args;
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        const importedPath = getImportedPath(libraryPath);
+        let allEntries = [];
+        // Read local entries
+        try {
+            const localFiles = await glob(path.join(localPath, '**/*.md'), { nodir: true });
+            for (const filePath of localFiles) {
+                const entry = await readEntry(filePath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+        }
+        catch {
+            // No local files yet
+        }
+        // Read imported entries
+        try {
+            const importedFiles = await glob(path.join(importedPath, '**/*.md'), { nodir: true });
+            for (const filePath of importedFiles) {
+                const entry = await readEntry(filePath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+        }
+        catch {
+            // No imported files
+        }
+        // If no entries at all
+        if (allEntries.length === 0) {
+            return {
+                entries: [],
+                total: 0,
+                message: 'No entries yet. Start recording!',
+                libraryPath: localPath,
+            };
+        }
+        // Filter by query if provided
+        if (query) {
+            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();
+        });
+        const total = allEntries.length;
+        // Apply limit
+        const entries = allEntries.slice(0, limit);
+        // Build message
+        let message;
+        if (query) {
+            message = total === 0
+                ? `No entries found for "${query}".`
+                : `Found ${total} ${total === 1 ? 'entry' : 'entries'} for "${query}".`;
+        }
+        else {
+            message = `${total} ${total === 1 ? 'entry' : 'entries'} in library.`;
+        }
+        return {
+            entries,
+            total,
+            message,
+            libraryPath: localPath,
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+async function readEntry(filePath, libraryPath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const { data, content: body } = matter(content);
+        // Extract title from H1 or filename
+        let title = data.title;
+        if (!title) {
+            const headingMatch = body.match(/^#\s+(.+)$/m);
+            if (headingMatch) {
+                title = headingMatch[1].trim();
+            }
+            else {
+                title = path.basename(filePath, '.md').replace(/-/g, ' ');
+            }
+        }
+        // Extract preview - first 100 chars of body content
+        const bodyText = body.trim();
+        const preview = bodyText.length > 100
+            ? bodyText.slice(0, 100) + '...'
+            : bodyText;
+        return {
+            title,
+            intent: data.intent || null,
+            context: data.context || null,
+            preview,
+            path: path.relative(libraryPath, filePath),
+            created: data.created || new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function matchesSearch(entry, searchTerm) {
+    // Check title
+    if (entry.title.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check intent
+    if (entry.intent && entry.intent.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check context
+    if (entry.context && entry.context.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check preview (basic substring match - Claude does semantic filtering)
+    if (entry.preview.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    return false;
+}

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

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

package/dist/tools/record.d.ts

@@ -0,0 +1,40 @@
+export interface RecordResult {
+    success: boolean;
+    path: string;
+    title: string;
+}
+export declare const recordTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            insight: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                description: string;
+            };
+            reasoning: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            example: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<RecordResult>;
+};

package/dist/tools/record.js

@@ -0,0 +1,186 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getLibraryPath, getLocalPath } from '../library/storage.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const recordTool = {
+    name: 'record',
+    description: `Capture knowledge worth keeping. We're building a library together.
+
+Every session we learn things that evaporate by tomorrow. This catches
+the good stuff - what we learned, why it matters, how it works.
+
+Quality bar: "I wish we knew this yesterday"
+
+Good entries:
+- "Stripe retries webhooks but doesn't dedupe - always check idempotency key"
+- "Clock skew between services - add 30s buffer to token validation"
+- "The staging deploy must happen before prod or the migration breaks"
+
+Not worth recording:
+- Generic docs (we can search those)
+- Temporary hacks
+- Stuff that'll change next week
+
+Examples:
+
+Quick:
+- record({ insight: "Stripe webhooks need idempotency checks" })
+
+Rich:
+- record({
+    intent: "Add Stripe webhook handler",
+    insight: "Stripe retries failed webhooks but doesn't dedupe. Always check idempotency key or you'll process payments twice.",
+    reasoning: "Their retry logic assumes failures, not slow responses",
+    context: "payments",
+    example: "if (await isDuplicate(event.id)) return;"
+  })
+
+WHEN TO CALL THIS:
+- The moment you think "that's useful" - capture it NOW
+- After solving something tricky - what made it work?
+- When you make a decision - why this over alternatives?
+- Before context dies - don't let insights evaporate
+
+Multiple calls welcome - one insight per call. Don't batch, don't wait.
+Context compacts, memories disappear. If it's worth knowing tomorrow,
+record it today.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            insight: {
+                type: 'string',
+                description: 'What did we learn? The knowledge worth keeping.',
+            },
+            intent: {
+                type: 'string',
+                description: 'What were we trying to accomplish?',
+            },
+            reasoning: {
+                type: 'string',
+                description: 'Why does this work? Why this over alternatives?',
+            },
+            context: {
+                type: 'string',
+                description: "Topic, area, or when this applies (e.g., 'auth', 'payments', 'only on Windows')",
+            },
+            example: {
+                type: 'string',
+                description: 'Code snippet or concrete illustration',
+            },
+            title: {
+                type: 'string',
+                description: 'Entry title. Auto-generated from insight if not provided.',
+            },
+        },
+        required: ['insight'],
+    },
+    async handler(args) {
+        const { insight, intent, reasoning, context, example, title: providedTitle } = args;
+        if (!insight) {
+            throw new Error('insight is required');
+        }
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        // Ensure local directory exists
+        await fs.mkdir(localPath, { recursive: true });
+        // Generate title
+        const title = providedTitle || generateTitle(insight, intent);
+        // Generate slug for filename
+        const slug = slugify(title);
+        const created = new Date().toISOString();
+        // Handle filename collisions
+        let filename = `${slug}.md`;
+        let filePath = path.join(localPath, filename);
+        let counter = 1;
+        while (await fileExists(filePath)) {
+            filename = `${slug}-${counter}.md`;
+            filePath = path.join(localPath, filename);
+            counter++;
+        }
+        // Build frontmatter
+        const frontmatterLines = ['---'];
+        if (intent) {
+            frontmatterLines.push(`intent: "${escapeYaml(intent)}"`);
+        }
+        if (context) {
+            frontmatterLines.push(`context: "${escapeYaml(context)}"`);
+        }
+        frontmatterLines.push(`created: "${created}"`);
+        frontmatterLines.push(`updated: "${created}"`);
+        frontmatterLines.push('source: "local"');
+        frontmatterLines.push('---');
+        // Build body
+        const bodyLines = [];
+        bodyLines.push(`# ${title}`);
+        bodyLines.push('');
+        bodyLines.push(insight);
+        if (reasoning) {
+            bodyLines.push('');
+            bodyLines.push('## Reasoning');
+            bodyLines.push('');
+            bodyLines.push(reasoning);
+        }
+        if (example) {
+            bodyLines.push('');
+            bodyLines.push('## Example');
+            bodyLines.push('');
+            // Detect if it looks like code
+            if (example.includes('\n') || example.includes('{') || example.includes('(')) {
+                bodyLines.push('```');
+                bodyLines.push(example);
+                bodyLines.push('```');
+            }
+            else {
+                bodyLines.push('```');
+                bodyLines.push(example);
+                bodyLines.push('```');
+            }
+        }
+        // Combine and write
+        const fileContent = frontmatterLines.join('\n') + '\n\n' + bodyLines.join('\n') + '\n';
+        await fs.writeFile(filePath, fileContent, 'utf-8');
+        const relativePath = path.relative(libraryPath, filePath);
+        return {
+            success: true,
+            path: relativePath,
+            title,
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function generateTitle(insight, intent) {
+    // Try to extract from first sentence of insight
+    const firstSentence = insight.split(/[.!?\n]/)[0].trim();
+    if (firstSentence.length <= 60) {
+        return firstSentence;
+    }
+    // If insight is too long, try intent
+    if (intent && intent.length <= 60) {
+        return intent;
+    }
+    // Truncate insight
+    return firstSentence.slice(0, 57) + '...';
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+function escapeYaml(text) {
+    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@telvok/librarian-mcp",
+  "version": "1.0.0",
+  "description": "Knowledge capture MCP server - remember what you learn with AI",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "librarian-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "knowledge-management",
+    "memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kogbuze/librarian.git"
+  },
+  "author": "Telvok",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "uuid": "^11.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "typescript": "^5.7.0"
+  }
+}