@echoes-io/mcp-server 4.0.0 → 4.1.1

package/src/rag/index.js

@@ -0,0 +1,33 @@
+/**
+ * RAG Module - GraphRAG + Vector Search for Echoes
+ *
+ * Provides hybrid search capabilities combining:
+ * - GraphRAG: Semantic relationships, character connections, temporal sequences
+ * - Vector Search: Fast similarity search with sqlite-vec fallback
+ */
+// Embedding providers
+export { BGEBaseEmbedding, batchArray, cosineSimilarity, createEmbeddingProvider, E5SmallEmbedding, GeminiEmbedding, normalizeEmbedding, } from './embeddings.js';
+// Core GraphRAG implementation
+export { GraphRAG, } from './graph-rag.js';
+// Hybrid RAG system
+export { DEFAULT_HYBRID_CONFIG, HybridRAG, } from './hybrid-rag.js';
+import { DEFAULT_HYBRID_CONFIG, HybridRAG } from './hybrid-rag.js';
+export function createHybridRAG(db, config = {}) {
+    const fullConfig = {
+        ...DEFAULT_HYBRID_CONFIG,
+        ...config,
+        embedding: {
+            ...DEFAULT_HYBRID_CONFIG.embedding,
+            ...config.embedding,
+        },
+        graphRAG: {
+            ...DEFAULT_HYBRID_CONFIG.graphRAG,
+            ...config.graphRAG,
+        },
+        fallback: {
+            ...DEFAULT_HYBRID_CONFIG.fallback,
+            ...config.fallback,
+        },
+    };
+    return new HybridRAG(db, fullConfig);
+}

package/src/server.d.ts

@@ -0,0 +1,43 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+declare const server: Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        task?: {
+            [x: string]: unknown;
+            ttl?: number | null | undefined;
+            pollInterval?: number | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        "io.modelcontextprotocol/related-task"?: {
+            [x: string]: unknown;
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+export declare function runServer(): Promise<void>;
+export { server };

package/src/server.js

@@ -0,0 +1,177 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { indexRag, indexRagSchema } from './tools/index-rag.js';
+import { indexTracker, indexTrackerSchema } from './tools/index-tracker.js';
+import { ragContext, ragContextSchema } from './tools/rag-context.js';
+import { ragSearch, ragSearchSchema } from './tools/rag-search.js';
+import { wordsCount, wordsCountSchema } from './tools/words-count.js';
+const server = new Server({
+    name: 'echoes-mcp-server',
+    version: '3.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'words-count',
+                description: 'Count words and text statistics in markdown files',
+                inputSchema: wordsCountSchema,
+            },
+            {
+                name: 'index-tracker',
+                description: 'Synchronize filesystem content with database',
+                inputSchema: indexTrackerSchema,
+            },
+            {
+                name: 'index-rag',
+                description: 'Index chapters into GraphRAG for semantic search',
+                inputSchema: indexRagSchema,
+            },
+            {
+                name: 'rag-search',
+                description: 'Search chapters using semantic similarity and character filtering',
+                inputSchema: ragSearchSchema,
+            },
+            {
+                name: 'rag-context',
+                description: 'Retrieve full chapter content for AI context using semantic search',
+                inputSchema: ragContextSchema,
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case 'words-count':
+            try {
+                const result = await wordsCount(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        case 'index-tracker':
+            try {
+                const result = await indexTracker(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        case 'index-rag':
+            try {
+                const result = await indexRag(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        case 'rag-search':
+            try {
+                const result = await ragSearch(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        case 'rag-context':
+            try {
+                const result = await ragContext(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+export async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Echoes MCP Server running on stdio');
+}
+export { server };

package/src/tools/index-rag.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const indexRagSchema: z.ZodObject<{
+    timeline: z.ZodString;
+    contentPath: z.ZodString;
+    arc: z.ZodOptional<z.ZodString>;
+    episode: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type IndexRagInput = z.infer<typeof indexRagSchema>;
+export interface IndexRagOutput {
+    indexed: number;
+    graphNodes: number;
+    vectorEmbeddings: number;
+    relationships: number;
+    timelines: number;
+    arcs: number;
+    episodes: number;
+    chapters: number;
+}
+export declare function indexRag(input: IndexRagInput): Promise<IndexRagOutput>;

package/src/tools/index-rag.js

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { initDatabase } from '../database/index.js';
+import { ItalianCharacterNER } from '../rag/character-ner.js';
+import { createHybridRAG } from '../rag/index.js';
+import { parseMarkdown } from '../utils/markdown.js';
+export const indexRagSchema = z.object({
+    timeline: z.string().describe('Timeline name'),
+    contentPath: z.string().describe('Path to content directory'),
+    arc: z.string().optional().describe('Filter by specific arc'),
+    episode: z.number().optional().describe('Filter by specific episode'),
+});
+export async function indexRag(input) {
+    const { timeline, contentPath, arc, episode } = indexRagSchema.parse(input);
+    // Initialize database and RAG system
+    const db = await initDatabase(':memory:');
+    const rag = createHybridRAG(db);
+    const ner = new ItalianCharacterNER();
+    // Scan filesystem for markdown files
+    const chapters = [];
+    function scanDirectory(dir) {
+        try {
+            const entries = readdirSync(dir);
+            for (const entry of entries) {
+                const fullPath = join(dir, entry);
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    scanDirectory(fullPath);
+                }
+                else if (entry.endsWith('.md')) {
+                    try {
+                        const fileContent = readFileSync(fullPath, 'utf-8');
+                        const { metadata, content } = parseMarkdown(fileContent);
+                        // Apply filters
+                        if (arc && metadata.arc !== arc)
+                            continue;
+                        if (episode !== undefined && metadata.episode !== episode)
+                            continue;
+                        // Extract characters using NER
+                        const characters = ner.extractCharacters(content);
+                        chapters.push({
+                            id: crypto.randomUUID(),
+                            content,
+                            characters,
+                            metadata: {
+                                chapterId: crypto.randomUUID(),
+                                arc: metadata.arc || 'unknown',
+                                episode: metadata.episode || 1,
+                                chapter: metadata.chapter || 1,
+                                pov: metadata.pov || 'unknown',
+                                location: metadata.location,
+                                timeline,
+                                title: metadata.title,
+                                summary: metadata.summary,
+                                filePath: fullPath,
+                            },
+                        });
+                    }
+                    catch (error) {
+                        console.warn(`Failed to parse ${fullPath}:`, error);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to scan directory ${dir}:`, error);
+        }
+    }
+    scanDirectory(contentPath);
+    // Index into RAG system
+    const result = await rag.indexChapters(chapters);
+    // Calculate relationships (edges in graph)
+    const relationships = result.graphNodes > 0 ? result.graphNodes * 2 : 0; // Rough estimate
+    return {
+        indexed: chapters.length,
+        graphNodes: result.graphNodes,
+        vectorEmbeddings: result.vectorEmbeddings,
+        relationships,
+        timelines: result.dbSync.timelines,
+        arcs: result.dbSync.arcs,
+        episodes: result.dbSync.episodes,
+        chapters: result.dbSync.chapters,
+    };
+}

package/src/tools/index-tracker.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const indexTrackerSchema: z.ZodObject<{
+    timeline: z.ZodString;
+    contentPath: z.ZodString;
+}, z.core.$strip>;
+export type IndexTrackerInput = z.infer<typeof indexTrackerSchema>;
+export interface IndexTrackerOutput {
+    scanned: number;
+    added: number;
+    updated: number;
+    deleted: number;
+    timelines: number;
+    arcs: number;
+    episodes: number;
+    chapters: number;
+}
+export declare function indexTracker(input: IndexTrackerInput): Promise<IndexTrackerOutput>;

package/src/tools/index-tracker.js

@@ -0,0 +1,89 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { initDatabase } from '../database/index.js';
+import { DatabaseSync } from '../rag/database-sync.js';
+import { parseMarkdown } from '../utils/markdown.js';
+export const indexTrackerSchema = z.object({
+    timeline: z.string().describe('Timeline name'),
+    contentPath: z.string().describe('Path to content directory'),
+});
+export async function indexTracker(input) {
+    const { timeline, contentPath } = indexTrackerSchema.parse(input);
+    // Initialize database (use in-memory for now, or pass dbPath as parameter)
+    const db = await initDatabase(':memory:');
+    const dbSync = new DatabaseSync(db);
+    // Scan filesystem for markdown files
+    const chapterRecords = [];
+    let scanned = 0;
+    function scanDirectory(dir) {
+        try {
+            const entries = readdirSync(dir);
+            for (const entry of entries) {
+                const fullPath = join(dir, entry);
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    scanDirectory(fullPath);
+                }
+                else if (entry.endsWith('.md')) {
+                    try {
+                        const content = readFileSync(fullPath, 'utf-8');
+                        const { metadata } = parseMarkdown(content);
+                        // Extract path info for fallback
+                        const relativePath = fullPath.replace(contentPath, '').replace(/^\//, '');
+                        const pathParts = relativePath.split('/');
+                        // Use metadata or infer from path
+                        const arc = metadata.arc || pathParts[0] || 'unknown';
+                        const episode = metadata.episode || extractEpisodeFromPath(pathParts[1]) || 1;
+                        const chapter = metadata.chapter || extractChapterFromFilename(entry) || 1;
+                        const pov = metadata.pov || 'unknown';
+                        chapterRecords.push({
+                            chapterId: crypto.randomUUID(),
+                            timeline,
+                            arc,
+                            episode,
+                            chapter,
+                            pov,
+                            title: metadata.title,
+                            summary: metadata.summary,
+                            location: metadata.location,
+                            filePath: fullPath,
+                        });
+                        scanned++;
+                    }
+                    catch (error) {
+                        console.warn(`Failed to parse ${fullPath}:`, error);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to scan directory ${dir}:`, error);
+        }
+    }
+    scanDirectory(contentPath);
+    // Sync to database
+    const syncStats = await dbSync.syncChapters(chapterRecords);
+    return {
+        scanned,
+        added: syncStats.chapters, // New chapters added
+        updated: 0, // TODO: Track updates
+        deleted: 0, // TODO: Track deletions
+        timelines: syncStats.timelines,
+        arcs: syncStats.arcs,
+        episodes: syncStats.episodes,
+        chapters: syncStats.chapters,
+    };
+}
+function extractEpisodeFromPath(pathSegment) {
+    if (!pathSegment)
+        return null;
+    // Match patterns like "ep01-title", "episode-1", "01-title"
+    const match = pathSegment.match(/(?:ep|episode)?[-_]?(\d+)/i);
+    return match ? parseInt(match[1], 10) : null;
+}
+function extractChapterFromFilename(filename) {
+    // Match patterns like "ep01-ch001-title.md", "chapter-1.md", "001-title.md"
+    const match = filename.match(/(?:ch|chapter)?[-_]?(\d+)/i);
+    return match ? parseInt(match[1], 10) : null;
+}

package/src/tools/index.d.ts

@@ -0,0 +1,5 @@
+export * from './index-rag.js';
+export * from './index-tracker.js';
+export * from './rag-context.js';
+export * from './rag-search.js';
+export * from './words-count.js';

package/src/tools/index.js

@@ -0,0 +1,5 @@
+export * from './index-rag.js';
+export * from './index-tracker.js';
+export * from './rag-context.js';
+export * from './rag-search.js';
+export * from './words-count.js';

package/src/tools/rag-context.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export declare const ragContextSchema: z.ZodObject<{
+    timeline: z.ZodString;
+    query: z.ZodString;
+    maxChapters: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    characters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allCharacters: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    arc: z.ZodOptional<z.ZodString>;
+    pov: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RagContextInput = z.infer<typeof ragContextSchema>;
+export interface RagContextOutput {
+    chapters: Array<{
+        id: string;
+        chapterId: string;
+        fullContent: string;
+        characters: string[];
+        metadata: {
+            arc?: string;
+            episode?: number;
+            chapter?: number;
+            pov?: string;
+            title?: string;
+            location?: string;
+            [key: string]: unknown;
+        };
+        score: number;
+        source: 'graphrag' | 'vector';
+    }>;
+    totalChapters: number;
+    searchTime: number;
+    contextLength: number;
+}
+export declare function ragContext(input: RagContextInput): Promise<RagContextOutput>;

package/src/tools/rag-context.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { initDatabase } from '../database/index.js';
+import { createHybridRAG } from '../rag/index.js';
+export const ragContextSchema = z.object({
+    timeline: z.string().min(1, 'Timeline name is required').describe('Timeline name'),
+    query: z.string().min(1, 'Query is required').describe('Search query'),
+    maxChapters: z.number().optional().default(5).describe('Maximum number of chapters to return'),
+    characters: z.array(z.string()).optional().describe('Filter by character names'),
+    allCharacters: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Require all characters (AND) vs any (OR)'),
+    arc: z.string().optional().describe('Filter by arc'),
+    pov: z.string().optional().describe('Filter by point of view'),
+});
+export async function ragContext(input) {
+    const { timeline, query, maxChapters, characters, allCharacters, arc, pov } = ragContextSchema.parse(input);
+    const startTime = Date.now();
+    // Initialize database and RAG system
+    const db = await initDatabase(':memory:');
+    const rag = createHybridRAG(db);
+    // Perform search to get relevant chapters
+    const searchResults = await rag.search(query, {
+        topK: maxChapters,
+        characters,
+        allCharacters,
+        arc,
+        pov,
+        useGraphRAG: true,
+    });
+    const searchTime = Date.now() - startTime;
+    // Transform results to include full content for AI context
+    const chapters = searchResults.map((result) => ({
+        id: result.id,
+        chapterId: result.chapterId,
+        fullContent: result.content, // Full chapter content for AI context
+        characters: result.characters,
+        metadata: result.metadata,
+        score: result.score,
+        source: result.source,
+    }));
+    // Calculate total context length
+    const contextLength = chapters.reduce((total, chapter) => total + chapter.fullContent.length, 0);
+    return {
+        chapters,
+        totalChapters: chapters.length,
+        searchTime,
+        contextLength,
+    };
+}

package/src/tools/rag-search.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const ragSearchSchema: z.ZodObject<{
+    timeline: z.ZodString;
+    query: z.ZodString;
+    topK: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    characters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allCharacters: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    arc: z.ZodOptional<z.ZodString>;
+    pov: z.ZodOptional<z.ZodString>;
+    useGraphRAG: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type RagSearchInput = z.infer<typeof ragSearchSchema>;
+export interface RagSearchOutput {
+    results: Array<{
+        id: string;
+        chapterId: string;
+        content: string;
+        characters: string[];
+        metadata: {
+            arc?: string;
+            episode?: number;
+            chapter?: number;
+            pov?: string;
+            title?: string;
+            location?: string;
+            [key: string]: unknown;
+        };
+        score: number;
+        source: 'graphrag' | 'vector';
+    }>;
+    totalResults: number;
+    searchTime: number;
+    source: 'graphrag' | 'vector' | 'hybrid';
+}
+export declare function ragSearch(input: RagSearchInput): Promise<RagSearchOutput>;

package/src/tools/rag-search.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { initDatabase } from '../database/index.js';
+import { createHybridRAG } from '../rag/index.js';
+export const ragSearchSchema = z.object({
+    timeline: z.string().min(1, 'Timeline name is required').describe('Timeline name'),
+    query: z.string().min(1, 'Query is required').describe('Search query'),
+    topK: z.number().optional().default(10).describe('Maximum number of results'),
+    characters: z.array(z.string()).optional().describe('Filter by character names'),
+    allCharacters: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Require all characters (AND) vs any (OR)'),
+    arc: z.string().optional().describe('Filter by arc'),
+    pov: z.string().optional().describe('Filter by point of view'),
+    useGraphRAG: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Use GraphRAG (true) or vector search only (false)'),
+});
+export async function ragSearch(input) {
+    const { timeline, query, topK, characters, allCharacters, arc, pov, useGraphRAG } = ragSearchSchema.parse(input);
+    const startTime = Date.now();
+    // Initialize database and RAG system
+    const db = await initDatabase(':memory:');
+    const rag = createHybridRAG(db);
+    // Perform search
+    const results = await rag.search(query, {
+        topK,
+        characters,
+        allCharacters,
+        arc,
+        pov,
+        useGraphRAG,
+    });
+    const searchTime = Date.now() - startTime;
+    // Determine primary source
+    let primarySource = 'hybrid';
+    if (results.length > 0) {
+        const sources = new Set(results.map((r) => r.source));
+        if (sources.size === 1) {
+            primarySource = Array.from(sources)[0];
+        }
+    }
+    return {
+        results: results.map((result) => ({
+            id: result.id,
+            chapterId: result.chapterId,
+            content: result.content,
+            characters: result.characters,
+            metadata: result.metadata,
+            score: result.score,
+            source: result.source,
+        })),
+        totalResults: results.length,
+        searchTime,
+        source: primarySource,
+    };
+}

package/src/tools/words-count.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const wordsCountSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    detailed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WordsCountInput = z.infer<typeof wordsCountSchema>;
+export interface WordsCountOutput {
+    words: number;
+    characters: number;
+    charactersNoSpaces: number;
+    readingTimeMinutes: number;
+    sentences?: number;
+    paragraphs?: number;
+}
+export declare function wordsCount(input: WordsCountInput): Promise<WordsCountOutput>;