@echoes-io/mcp-server 1.1.0 → 1.2.0

package/README.md

@@ -38,7 +38,9 @@ Then configure:
     "echoes": {
       "command": "echoes-mcp-server",
       "env": {
-        "ECHOES_TIMELINE": "your-timeline-name"
+        "ECHOES_TIMELINE": "your-timeline-name",
+        "ECHOES_RAG_PROVIDER": "e5-small",
+        "ECHOES_CHROMA_URL": "./rag_data"
       }
     }
   }
@@ -47,6 +49,11 @@ Then configure:
 
 **Important:** The `ECHOES_TIMELINE` environment variable must be set to specify which timeline to work with. All tools operate on this timeline.
 
+**Optional RAG Configuration:**
+- `ECHOES_RAG_PROVIDER`: Embedding provider (`e5-small`, `e5-large`, or `gemini`). Default: `e5-small`
+- `ECHOES_GEMINI_API_KEY`: Required if using `gemini` provider
+- `ECHOES_CHROMA_URL`: ChromaDB storage path. Default: `./rag_data`
+
 ## Available Tools
 
 All tools operate on the timeline specified by the `ECHOES_TIMELINE` environment variable.
@@ -88,6 +95,19 @@ All tools operate on the timeline specified by the `ECHOES_TIMELINE` environment
     - `arc: "arc1", episode: 1`: Statistics for specific episode
     - `pov: "Alice"`: Statistics for specific POV across timeline
 
+### RAG (Semantic Search)
+- **`rag-index`** - Index chapters into vector database for semantic search
+  - Input: optional: `arc`, `episode` (to index specific content)
+  - Output: Number of chapters indexed
+  
+- **`rag-search`** - Semantic search across timeline content
+  - Input: `query`, optional: `arc`, `pov`, `maxResults`
+  - Output: Relevant chapters with similarity scores and previews
+  
+- **`rag-context`** - Retrieve relevant context for AI interactions
+  - Input: `query`, optional: `arc`, `pov`, `maxChapters`
+  - Output: Full chapter content for AI context
+
 ## Development
 
 ### Scripts
@@ -128,7 +148,6 @@ npm run lint:fix
 
 ### Planned Features
 - **Book generation** - LaTeX/PDF compilation tools for creating publishable books from timeline content
-- **RAG system** - Retrieval-Augmented Generation integration for AI-assisted writing and content analysis
 
 ## License
 

package/lib/server.d.ts

@@ -1,6 +1,7 @@
+import { RAGSystem } from '@echoes-io/rag';
 import { Tracker } from '@echoes-io/tracker';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-export declare function createServer(tracker: Tracker): Server<{
+export declare function createServer(tracker: Tracker, rag: RAGSystem): Server<{
     method: string;
     params?: {
         [x: string]: unknown;

package/lib/server.js

@@ -1,15 +1,16 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { RAGSystem } from '@echoes-io/rag';
 import { Tracker } from '@echoes-io/tracker';
 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 { zodToJsonSchema } from 'zod-to-json-schema';
-import { chapterDelete, chapterDeleteSchema, chapterInfo, chapterInfoSchema, chapterInsert, chapterInsertSchema, chapterRefresh, chapterRefreshSchema, episodeInfo, episodeInfoSchema, episodeUpdate, episodeUpdateSchema, stats, statsSchema, timelineSync, timelineSyncSchema, wordsCount, wordsCountSchema, } from './tools/index.js';
+import { chapterDelete, chapterDeleteSchema, chapterInfo, chapterInfoSchema, chapterInsert, chapterInsertSchema, chapterRefresh, chapterRefreshSchema, episodeInfo, episodeInfoSchema, episodeUpdate, episodeUpdateSchema, ragContext, ragContextSchema, ragIndex, ragIndexSchema, ragSearch, ragSearchSchema, stats, statsSchema, timelineSync, timelineSyncSchema, wordsCount, wordsCountSchema, } from './tools/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-export function createServer(tracker) {
+export function createServer(tracker, rag) {
     const server = new Server({
         name: pkg.name,
         version: pkg.version,
@@ -66,6 +67,21 @@ export function createServer(tracker) {
                     description: 'Get statistics for timeline, arc, episode, or POV',
                     inputSchema: zodToJsonSchema(statsSchema),
                 },
+                {
+                    name: 'rag-index',
+                    description: 'Index chapters into RAG vector database for semantic search',
+                    inputSchema: zodToJsonSchema(ragIndexSchema),
+                },
+                {
+                    name: 'rag-search',
+                    description: 'Semantic search across timeline content',
+                    inputSchema: zodToJsonSchema(ragSearchSchema),
+                },
+                {
+                    name: 'rag-context',
+                    description: 'Retrieve relevant context for AI interactions',
+                    inputSchema: zodToJsonSchema(ragContextSchema),
+                },
             ],
         };
     });
@@ -90,6 +106,12 @@ export function createServer(tracker) {
                 return await timelineSync(timelineSyncSchema.parse(args), tracker);
             case 'stats':
                 return await stats(statsSchema.parse(args), tracker);
+            case 'rag-index':
+                return await ragIndex(ragIndexSchema.parse(args), tracker, rag);
+            case 'rag-search':
+                return await ragSearch(ragSearchSchema.parse(args), rag);
+            case 'rag-context':
+                return await ragContext(ragContextSchema.parse(args), rag);
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -102,7 +124,16 @@ export async function runServer() {
     const tracker = new Tracker(dbPath);
     await tracker.init();
     console.error(`Tracker database initialized: ${dbPath}`);
-    const server = createServer(tracker);
+    // Initialize RAG system
+    const chromaUrl = process.env.ECHOES_CHROMA_URL || (process.env.NODE_ENV === 'test' ? ':memory:' : './rag_data');
+    const provider = (process.env.ECHOES_RAG_PROVIDER || 'e5-small');
+    const rag = new RAGSystem({
+        provider,
+        chromaUrl,
+        geminiApiKey: process.env.ECHOES_GEMINI_API_KEY,
+    });
+    console.error(`RAG system initialized: ${chromaUrl} (provider: ${provider})`);
+    const server = createServer(tracker, rag);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('Echoes MCP Server running on stdio');

package/lib/tools/index.d.ts

@@ -4,6 +4,9 @@ export { chapterInsert, chapterInsertSchema } from './chapter-insert.js';
 export { chapterRefresh, chapterRefreshSchema } from './chapter-refresh.js';
 export { episodeInfo, episodeInfoSchema } from './episode-info.js';
 export { episodeUpdate, episodeUpdateSchema } from './episode-update.js';
+export { ragContext, ragContextSchema } from './rag-context.js';
+export { ragIndex, ragIndexSchema } from './rag-index.js';
+export { ragSearch, ragSearchSchema } from './rag-search.js';
 export { stats, statsSchema } from './stats.js';
 export { timelineSync, timelineSyncSchema } from './timeline-sync.js';
 export { wordsCount, wordsCountSchema } from './words-count.js';

package/lib/tools/index.js

@@ -4,6 +4,9 @@ export { chapterInsert, chapterInsertSchema } from './chapter-insert.js';
 export { chapterRefresh, chapterRefreshSchema } from './chapter-refresh.js';
 export { episodeInfo, episodeInfoSchema } from './episode-info.js';
 export { episodeUpdate, episodeUpdateSchema } from './episode-update.js';
+export { ragContext, ragContextSchema } from './rag-context.js';
+export { ragIndex, ragIndexSchema } from './rag-index.js';
+export { ragSearch, ragSearchSchema } from './rag-search.js';
 export { stats, statsSchema } from './stats.js';
 export { timelineSync, timelineSyncSchema } from './timeline-sync.js';
 export { wordsCount, wordsCountSchema } from './words-count.js';

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

@@ -0,0 +1,24 @@
+import type { RAGSystem } from '@echoes-io/rag';
+import { z } from 'zod';
+export declare const ragContextSchema: z.ZodObject<{
+    query: z.ZodString;
+    arc: z.ZodOptional<z.ZodString>;
+    pov: z.ZodOptional<z.ZodString>;
+    maxChapters: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    arc?: string | undefined;
+    pov?: string | undefined;
+    maxChapters?: number | undefined;
+}, {
+    query: string;
+    arc?: string | undefined;
+    pov?: string | undefined;
+    maxChapters?: number | undefined;
+}>;
+export declare function ragContext(args: z.infer<typeof ragContextSchema>, rag: RAGSystem): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/lib/tools/rag-context.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const ragContextSchema = z.object({
+    query: z.string().describe('Context query'),
+    arc: z.string().optional().describe('Filter by arc name'),
+    pov: z.string().optional().describe('Filter by POV character'),
+    maxChapters: z.number().optional().describe('Maximum number of chapters (default: 5)'),
+});
+export async function ragContext(args, rag) {
+    try {
+        const timeline = getTimeline();
+        const results = await rag.getContext({
+            query: args.query,
+            timeline,
+            arc: args.arc,
+            pov: args.pov,
+            maxChapters: args.maxChapters,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        query: args.query,
+                        timeline,
+                        filters: {
+                            arc: args.arc || null,
+                            pov: args.pov || null,
+                        },
+                        context: results.map((r) => ({
+                            chapter: {
+                                arc: r.metadata.arcName,
+                                episode: r.metadata.episodeNumber,
+                                chapter: r.metadata.number,
+                                pov: r.metadata.pov,
+                                title: r.metadata.title,
+                            },
+                            similarity: r.similarity,
+                            content: r.content,
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get context: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { RAGSystem } from '@echoes-io/rag';
+import type { Tracker } from '@echoes-io/tracker';
+import { z } from 'zod';
+export declare const ragIndexSchema: z.ZodObject<{
+    arc: z.ZodOptional<z.ZodString>;
+    episode: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    arc?: string | undefined;
+    episode?: number | undefined;
+}, {
+    arc?: string | undefined;
+    episode?: number | undefined;
+}>;
+export declare function ragIndex(args: z.infer<typeof ragIndexSchema>, tracker: Tracker, rag: RAGSystem): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/lib/tools/rag-index.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const ragIndexSchema = z.object({
+    arc: z.string().optional().describe('Index specific arc only'),
+    episode: z.number().optional().describe('Index specific episode only (requires arc)'),
+});
+export async function ragIndex(args, tracker, rag) {
+    try {
+        const timeline = getTimeline();
+        let chapters = [];
+        // Get chapters based on filters
+        if (args.arc && args.episode) {
+            chapters = await tracker.getChapters(timeline, args.arc, args.episode);
+        }
+        else if (args.arc) {
+            const episodes = await tracker.getEpisodes(timeline, args.arc);
+            for (const ep of episodes) {
+                const epChapters = await tracker.getChapters(timeline, args.arc, ep.number);
+                chapters.push(...epChapters);
+            }
+        }
+        else {
+            const arcs = await tracker.getArcs(timeline);
+            for (const arc of arcs) {
+                const episodes = await tracker.getEpisodes(timeline, arc.name);
+                for (const ep of episodes) {
+                    const epChapters = await tracker.getChapters(timeline, arc.name, ep.number);
+                    chapters.push(...epChapters);
+                }
+            }
+        }
+        // Convert to embedding format and add to RAG
+        const embeddingChapters = chapters.map((ch) => ({
+            id: `${ch.timelineName}-${ch.arcName}-${ch.episodeNumber}-${ch.number}`,
+            metadata: ch,
+            content: '', // Content will be loaded by RAG system if needed
+        }));
+        await rag.addChapters(embeddingChapters);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        indexed: embeddingChapters.length,
+                        timeline,
+                        arc: args.arc || 'all',
+                        episode: args.episode || 'all',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to index chapters: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { RAGSystem } from '@echoes-io/rag';
+import { z } from 'zod';
+export declare const ragSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    arc: z.ZodOptional<z.ZodString>;
+    pov: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    arc?: string | undefined;
+    pov?: string | undefined;
+    maxResults?: number | undefined;
+}, {
+    query: string;
+    arc?: string | undefined;
+    pov?: string | undefined;
+    maxResults?: number | undefined;
+}>;
+export declare function ragSearch(args: z.infer<typeof ragSearchSchema>, rag: RAGSystem): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/lib/tools/rag-search.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const ragSearchSchema = z.object({
+    query: z.string().describe('Search query'),
+    arc: z.string().optional().describe('Filter by arc name'),
+    pov: z.string().optional().describe('Filter by POV character'),
+    maxResults: z.number().optional().describe('Maximum number of results (default: 10)'),
+});
+export async function ragSearch(args, rag) {
+    try {
+        const timeline = getTimeline();
+        const results = await rag.search(args.query, {
+            timeline,
+            arc: args.arc,
+            pov: args.pov,
+            maxResults: args.maxResults,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        query: args.query,
+                        timeline,
+                        filters: {
+                            arc: args.arc || null,
+                            pov: args.pov || null,
+                        },
+                        results: results.map((r) => ({
+                            chapter: {
+                                arc: r.metadata.arcName,
+                                episode: r.metadata.episodeNumber,
+                                chapter: r.metadata.number,
+                                pov: r.metadata.pov,
+                                title: r.metadata.title,
+                            },
+                            similarity: r.similarity,
+                            preview: r.content.substring(0, 200) + '...',
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to search: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echoes-io/mcp-server",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Model Context Protocol server for AI integration with Echoes storytelling platform",
   "scripts": {
     "dev": "tsx cli/index.ts",
@@ -81,9 +81,10 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@echoes-io/utils": "^1.1.1",
     "@echoes-io/models": "^1.0.0",
+    "@echoes-io/rag": "^1.0.0",
     "@echoes-io/tracker": "^1.0.0",
+    "@echoes-io/utils": "^1.1.1",
     "@modelcontextprotocol/sdk": "^1.0.0"
   }
 }