@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/library 2/query.js

@@ -0,0 +1,104 @@
+// ============================================================================
+// Query Utilities
+// ============================================================================
+/**
+ * Score how well an entry matches a search term.
+ */
+export function scoreMatch(entry, searchTerm) {
+    const term = searchTerm.toLowerCase();
+    let score = 0;
+    // Topic matches (highest weight)
+    for (const topic of entry.topics) {
+        if (topic.toLowerCase() === term) {
+            score += 10; // Exact match
+        }
+        else if (topic.toLowerCase().includes(term)) {
+            score += 5; // Partial match
+        }
+    }
+    // Content matches
+    const contentLower = entry.content.toLowerCase();
+    if (contentLower.includes(term)) {
+        // Count occurrences
+        const matches = contentLower.split(term).length - 1;
+        score += Math.min(matches * 2, 8); // Cap at 8
+    }
+    return score;
+}
+/**
+ * Detect potential conflicts between entries.
+ * Returns true if entries on the same topic give contradictory advice.
+ */
+export function detectConflict(entries) {
+    if (entries.length < 2)
+        return false;
+    // Simple heuristic: look for negation patterns
+    const negationPatterns = [
+        /don't|dont|never|avoid|stop/i,
+        /always|must|should/i,
+    ];
+    let hasNegation = false;
+    let hasAffirmation = false;
+    for (const entry of entries) {
+        if (negationPatterns[0].test(entry.content)) {
+            hasNegation = true;
+        }
+        if (negationPatterns[1].test(entry.content)) {
+            hasAffirmation = true;
+        }
+    }
+    // This is a very simple heuristic - could be improved with semantic analysis
+    return hasNegation && hasAffirmation;
+}
+/**
+ * Generate a conflict summary.
+ */
+export function generateConflictSummary(entries) {
+    if (entries.length < 2)
+        return '';
+    const sources = entries.map(e => {
+        if (e.imported_from) {
+            return `imported/${e.imported_from}`;
+        }
+        return e.source;
+    });
+    const uniqueSources = [...new Set(sources)];
+    return `Found ${entries.length} entries that may conflict. Sources: ${uniqueSources.join(', ')}. Review and decide which to keep.`;
+}
+/**
+ * Filter entries by topic.
+ */
+export function filterByTopic(entries, topic) {
+    const term = topic.toLowerCase();
+    return entries.filter(entry => entry.topics.some(t => t.toLowerCase().includes(term)));
+}
+/**
+ * Sort entries by relevance to search term.
+ */
+export function sortByRelevance(entries, searchTerm) {
+    return [...entries].sort((a, b) => {
+        const scoreA = scoreMatch(a, searchTerm);
+        const scoreB = scoreMatch(b, searchTerm);
+        return scoreB - scoreA;
+    });
+}
+/**
+ * Group entries by source.
+ */
+export function groupBySource(entries) {
+    const groups = {
+        local: [],
+        imported: [],
+        archived: [],
+    };
+    for (const entry of entries) {
+        const key = entry.source;
+        if (groups[key]) {
+            groups[key].push(entry);
+        }
+        else {
+            groups.local.push(entry); // Default to local
+        }
+    }
+    return groups;
+}

package/dist/library 2/schemas.d.ts

@@ -0,0 +1,324 @@
+import { z } from 'zod';
+export declare const SourceTypeSchema: z.ZodEnum<["local", "imported", "archived"]>;
+export type SourceType = z.infer<typeof SourceTypeSchema>;
+export declare const EntrySourceSchema: z.ZodEnum<["manual", "precompact", "imported"]>;
+export type EntrySource = z.infer<typeof EntrySourceSchema>;
+export declare const LibraryEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    topics: z.ZodArray<z.ZodString, "many">;
+    content: z.ZodString;
+    created: z.ZodString;
+    source: z.ZodEnum<["local", "imported", "archived"]>;
+    origin: z.ZodOptional<z.ZodEnum<["manual", "precompact", "imported"]>>;
+    imported_from: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    created: string;
+    source: "local" | "imported" | "archived";
+    id: string;
+    topics: string[];
+    origin?: "imported" | "manual" | "precompact" | undefined;
+    imported_from?: string | undefined;
+}, {
+    content: string;
+    created: string;
+    source: "local" | "imported" | "archived";
+    id: string;
+    topics: string[];
+    origin?: "imported" | "manual" | "precompact" | undefined;
+    imported_from?: string | undefined;
+}>;
+export type LibraryEntry = z.infer<typeof LibraryEntrySchema>;
+export declare const FrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    topics: z.ZodArray<z.ZodString, "many">;
+    created: z.ZodString;
+    source: z.ZodOptional<z.ZodEnum<["manual", "precompact", "imported"]>>;
+    imported_from: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    created: string;
+    id: string;
+    topics: string[];
+    source?: "imported" | "manual" | "precompact" | undefined;
+    imported_from?: string | undefined;
+}, {
+    created: string;
+    id: string;
+    topics: string[];
+    source?: "imported" | "manual" | "precompact" | undefined;
+    imported_from?: string | undefined;
+}>;
+export type Frontmatter = z.infer<typeof FrontmatterSchema>;
+export declare const BriefParamsSchema: z.ZodObject<{
+    topic: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    context?: string | undefined;
+}, {
+    topic: string;
+    context?: string | undefined;
+}>;
+export type BriefParams = z.infer<typeof BriefParamsSchema>;
+export declare const RecordParamsSchema: z.ZodObject<{
+    topics: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    topics: string | string[];
+}, {
+    content: string;
+    topics: string | string[];
+}>;
+export type RecordParams = z.infer<typeof RecordParamsSchema>;
+export declare const AdoptParamsSchema: z.ZodObject<{
+    entry_id: z.ZodString;
+    library_name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entry_id: string;
+    library_name?: string | undefined;
+}, {
+    entry_id: string;
+    library_name?: string | undefined;
+}>;
+export type AdoptParams = z.infer<typeof AdoptParamsSchema>;
+export declare const BriefResultSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        topics: z.ZodArray<z.ZodString, "many">;
+        content: z.ZodString;
+        created: z.ZodString;
+        source: z.ZodEnum<["local", "imported", "archived"]>;
+        origin: z.ZodOptional<z.ZodEnum<["manual", "precompact", "imported"]>>;
+        imported_from: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }>, "many">;
+    conflict: z.ZodOptional<z.ZodBoolean>;
+    conflict_summary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }[];
+    conflict?: boolean | undefined;
+    conflict_summary?: string | undefined;
+}, {
+    entries: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }[];
+    conflict?: boolean | undefined;
+    conflict_summary?: string | undefined;
+}>;
+export type BriefResult = z.infer<typeof BriefResultSchema>;
+export declare const ImportedLibrarySchema: z.ZodObject<{
+    name: z.ZodString;
+    entry_count: z.ZodNumber;
+    purchased_at: z.ZodString;
+    sync_preference: z.ZodOptional<z.ZodEnum<["auto", "manual", "pinned"]>>;
+    last_synced: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    entry_count: number;
+    purchased_at: string;
+    last_synced?: string | undefined;
+    sync_preference?: "pinned" | "manual" | "auto" | undefined;
+}, {
+    name: string;
+    entry_count: number;
+    purchased_at: string;
+    last_synced?: string | undefined;
+    sync_preference?: "pinned" | "manual" | "auto" | undefined;
+}>;
+export type ImportedLibrary = z.infer<typeof ImportedLibrarySchema>;
+export declare const StateResultSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        topics: z.ZodArray<z.ZodString, "many">;
+        content: z.ZodString;
+        created: z.ZodString;
+        source: z.ZodEnum<["local", "imported", "archived"]>;
+        origin: z.ZodOptional<z.ZodEnum<["manual", "precompact", "imported"]>>;
+        imported_from: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }>, "many">;
+    imported_libraries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        entry_count: z.ZodNumber;
+        purchased_at: z.ZodString;
+        sync_preference: z.ZodOptional<z.ZodEnum<["auto", "manual", "pinned"]>>;
+        last_synced: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        entry_count: number;
+        purchased_at: string;
+        last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
+    }, {
+        name: string;
+        entry_count: number;
+        purchased_at: string;
+        last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }[];
+    imported_libraries: {
+        name: string;
+        entry_count: number;
+        purchased_at: string;
+        last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
+    }[];
+}, {
+    entries: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }[];
+    imported_libraries: {
+        name: string;
+        entry_count: number;
+        purchased_at: string;
+        last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
+    }[];
+}>;
+export type StateResult = z.infer<typeof StateResultSchema>;
+export declare const RecordResultSchema: z.ZodObject<{
+    entry: z.ZodObject<{
+        id: z.ZodString;
+        topics: z.ZodArray<z.ZodString, "many">;
+        content: z.ZodString;
+        created: z.ZodString;
+        source: z.ZodEnum<["local", "imported", "archived"]>;
+        origin: z.ZodOptional<z.ZodEnum<["manual", "precompact", "imported"]>>;
+        imported_from: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }, {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    }>;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    entry: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    };
+}, {
+    path: string;
+    entry: {
+        content: string;
+        created: string;
+        source: "local" | "imported" | "archived";
+        id: string;
+        topics: string[];
+        origin?: "imported" | "manual" | "precompact" | undefined;
+        imported_from?: string | undefined;
+    };
+}>;
+export type RecordResult = z.infer<typeof RecordResultSchema>;
+export declare const ExtractedEntrySchema: z.ZodObject<{
+    topics: z.ZodArray<z.ZodString, "many">;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    topics: string[];
+}, {
+    content: string;
+    topics: string[];
+}>;
+export type ExtractedEntry = z.infer<typeof ExtractedEntrySchema>;
+export declare const ExtractionResultSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        topics: z.ZodArray<z.ZodString, "many">;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        topics: string[];
+    }, {
+        content: string;
+        topics: string[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        content: string;
+        topics: string[];
+    }[];
+}, {
+    entries: {
+        content: string;
+        topics: string[];
+    }[];
+}>;
+export type ExtractionResult = z.infer<typeof ExtractionResultSchema>;

package/dist/library 2/schemas.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+// ============================================================================
+// Core Types
+// ============================================================================
+export const SourceTypeSchema = z.enum(['local', 'imported', 'archived']);
+export const EntrySourceSchema = z.enum(['manual', 'precompact', 'imported']);
+// ============================================================================
+// Library Entry
+// ============================================================================
+export const LibraryEntrySchema = z.object({
+    id: z.string().uuid(),
+    topics: z.array(z.string().min(1)).min(1),
+    content: z.string().min(1),
+    created: z.string().datetime(),
+    source: SourceTypeSchema,
+    origin: EntrySourceSchema.optional(),
+    imported_from: z.string().optional(),
+});
+// ============================================================================
+// File Frontmatter (YAML)
+// ============================================================================
+export const FrontmatterSchema = z.object({
+    id: z.string().uuid(),
+    topics: z.array(z.string().min(1)).min(1),
+    created: z.string().datetime(),
+    source: EntrySourceSchema.optional(),
+    imported_from: z.string().optional(),
+});
+// ============================================================================
+// MCP Tool Parameters
+// ============================================================================
+export const BriefParamsSchema = z.object({
+    topic: z.string().min(1).describe('What to query (e.g., "deployment", "api-design")'),
+    context: z.string().optional().describe('Additional context to narrow results'),
+});
+export const RecordParamsSchema = z.object({
+    topics: z.union([
+        z.string().min(1),
+        z.array(z.string().min(1)).min(1),
+    ]).describe('Topic tags - string or array (e.g., "deployment" or ["stripe", "webhooks"])'),
+    content: z.string().min(1).describe('The reasoning to record'),
+});
+export const AdoptParamsSchema = z.object({
+    entry_id: z.string().uuid().describe('ID of the imported entry to adopt'),
+    library_name: z.string().optional().describe('Name of the imported library'),
+});
+// ============================================================================
+// MCP Tool Results
+// ============================================================================
+export const BriefResultSchema = z.object({
+    entries: z.array(LibraryEntrySchema),
+    conflict: z.boolean().optional(),
+    conflict_summary: z.string().optional(),
+});
+export const ImportedLibrarySchema = z.object({
+    name: z.string(),
+    entry_count: z.number(),
+    purchased_at: z.string().datetime(),
+    sync_preference: z.enum(['auto', 'manual', 'pinned']).optional(),
+    last_synced: z.string().datetime().optional(),
+});
+export const StateResultSchema = z.object({
+    entries: z.array(LibraryEntrySchema),
+    imported_libraries: z.array(ImportedLibrarySchema),
+});
+export const RecordResultSchema = z.object({
+    entry: LibraryEntrySchema,
+    path: z.string(),
+});
+// ============================================================================
+// Extraction Types
+// ============================================================================
+export const ExtractedEntrySchema = z.object({
+    topics: z.array(z.string().min(1)).min(1),
+    content: z.string().min(1),
+});
+export const ExtractionResultSchema = z.object({
+    entries: z.array(ExtractedEntrySchema),
+});

package/dist/library 2/storage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Get the library root path.
+ * Uses .librarian/ in the current working directory.
+ */
+export declare function getLibraryPath(): string;
+/**
+ * Get the local entries path.
+ */
+export declare function getLocalPath(libraryPath: string): string;
+/**
+ * Get the imported entries path.
+ * @deprecated Use getPackagesPath for marketplace content
+ */
+export declare function getImportedPath(libraryPath: string): string;
+/**
+ * Get the packages path (marketplace content from others).
+ */
+export declare function getPackagesPath(libraryPath: string): string;
+/**
+ * Get the archived entries path.
+ */
+export declare function getArchivedPath(libraryPath: string): string;

package/dist/library 2/storage.js

@@ -0,0 +1,36 @@
+import * as path from 'path';
+// ============================================================================
+// Path Utilities
+// ============================================================================
+/**
+ * Get the library root path.
+ * Uses .librarian/ in the current working directory.
+ */
+export function getLibraryPath() {
+    return path.join(process.cwd(), '.librarian');
+}
+/**
+ * Get the local entries path.
+ */
+export function getLocalPath(libraryPath) {
+    return path.join(libraryPath, 'local');
+}
+/**
+ * Get the imported entries path.
+ * @deprecated Use getPackagesPath for marketplace content
+ */
+export function getImportedPath(libraryPath) {
+    return path.join(libraryPath, 'imported');
+}
+/**
+ * Get the packages path (marketplace content from others).
+ */
+export function getPackagesPath(libraryPath) {
+    return path.join(libraryPath, 'packages');
+}
+/**
+ * Get the archived entries path.
+ */
+export function getArchivedPath(libraryPath) {
+    return path.join(libraryPath, 'archived');
+}

package/dist/library 2/vector-index.d.ts

@@ -0,0 +1,55 @@
+export interface IndexEntry {
+    path: string;
+    title: string;
+    embedding: number[];
+    chunk: number;
+    preview: string;
+}
+export interface VectorIndex {
+    version: number;
+    rebuilt: string;
+    modelId: string;
+    entries: IndexEntry[];
+}
+export interface SemanticMatch {
+    path: string;
+    title: string;
+    similarity: number;
+    preview: string;
+}
+/**
+ * Load the vector index from disk.
+ * Returns empty index if file doesn't exist or is invalid.
+ */
+export declare function loadIndex(): Promise<VectorIndex>;
+/**
+ * Save the vector index to disk.
+ */
+export declare function saveIndex(index: VectorIndex): Promise<void>;
+/**
+ * Add or update an entry in the index.
+ * Chunks the content and generates embeddings for each chunk.
+ */
+export declare function addToIndex(index: VectorIndex, entryPath: string, title: string, content: string): Promise<void>;
+/**
+ * Remove an entry from the index.
+ */
+export declare function removeFromIndex(index: VectorIndex, entryPath: string): void;
+/**
+ * Search the index for entries semantically similar to the query.
+ * Returns paths ranked by similarity, deduped to best chunk per entry.
+ */
+export declare function semanticSearch(index: VectorIndex, query: string, limit?: number): Promise<SemanticMatch[]>;
+/**
+ * Check if the index might be stale (model changed).
+ */
+export declare function isIndexStale(index: VectorIndex): boolean;
+/**
+ * Get index statistics.
+ */
+export declare function getIndexStats(index: VectorIndex): {
+    entryCount: number;
+    chunkCount: number;
+    modelId: string;
+    rebuilt: string;
+};