@echoes-io/mcp-server 1.4.2 → 1.5.0

package/README.md

@@ -8,6 +8,8 @@ The server is distributed as an npm package and can be used without cloning the
 
 ### Using with MCP Clients
 
+**Important:** The server must be run from the `.github` directory of your Echoes project.
+
 Add to your MCP client configuration (e.g., `~/.config/q/mcp.json` for Amazon Q):
 
 ```json
@@ -15,7 +17,8 @@ Add to your MCP client configuration (e.g., `~/.config/q/mcp.json` for Amazon Q)
   "mcpServers": {
     "echoes": {
       "command": "npx",
-      "args": ["-y", "@echoes-io/mcp-server"]
+      "args": ["-y", "@echoes-io/mcp-server"],
+      "cwd": "/path/to/echoes-io/.github"
     }
   }
 }
@@ -34,9 +37,9 @@ Then configure:
   "mcpServers": {
     "echoes": {
       "command": "echoes-mcp-server",
+      "cwd": "/path/to/echoes-io/.github",
       "env": {
-        "ECHOES_RAG_PROVIDER": "e5-small",
-        "ECHOES_RAG_DB_PATH": "./rag.db"
+        "ECHOES_RAG_PROVIDER": "e5-small"
       }
     }
   }
@@ -46,7 +49,30 @@ Then configure:
 **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_RAG_DB_PATH`: SQLite database path. Default: `./rag.db`
+
+## Multi-Timeline Architecture
+
+The server automatically discovers and manages multiple timelines:
+
+```
+echoes-io/
+  .github/              # Server runs from here
+  timeline-eros/        # Private timeline repo
+    tracker.db          # Timeline-specific database
+    rag.db              # Timeline-specific RAG index
+    content/...
+  timeline-other/       # Another private timeline
+    tracker.db
+    rag.db
+    content/...
+```
+
+**Benefits:**
+- Each timeline has isolated databases in its own repository
+- Timeline repositories can be private while `.github` is public
+- No need to specify `contentPath` - auto-discovered from directory structure
+- Easy to manage access: just share/don't share specific timeline repos
+
 
 ## Available Tools
 
@@ -77,11 +103,12 @@ All tools require a `timeline` parameter to specify which timeline to operate on
 
 ### Timeline Operations
 - **`timeline-sync`** - Synchronize filesystem content with database
-  - Input: `contentPath` (path to content directory)
+  - Input: `timeline` (timeline name)
+  - Note: Content path is auto-discovered from timeline directory structure
 
 ### Statistics
 - **`stats`** - Get aggregate statistics with optional filters
-  - Input: optional: `arc`, `episode`, `pov`
+  - Input: `timeline`, optional: `arc`, `episode`, `pov`
   - Output: Total words/chapters, POV distribution, arc/episode breakdown, longest/shortest chapters
   - Examples:
     - No filters: Overall timeline statistics
@@ -91,24 +118,38 @@ All tools require a `timeline` parameter to specify which timeline to operate on
 
 ### RAG (Semantic Search)
 - **`rag-index`** - Index chapters into vector database for semantic search
-  - Input: `contentPath` (path to content directory, required for full content indexing), optional: `arc`, `episode` (to index specific content)
+  - Input: `timeline`, optional: `arc`, `episode` (to index specific content)
   - Output: Number of chapters indexed
-  - Note: Requires `contentPath` to read and index actual chapter content. Without it, only metadata is indexed.
+  - Note: Content path is auto-discovered from timeline directory structure
+  - Note: Automatically extracts character names using NER (Named Entity Recognition)
   
 - **`rag-search`** - Semantic search across timeline content
-  - Input: `query`, optional: `arc`, `pov`, `maxResults`
-  - Output: Relevant chapters with similarity scores and previews
+  - Input: `timeline`, `query`, optional: `arc`, `pov`, `maxResults`, `characters`, `allCharacters`
+  - Output: Relevant chapters with similarity scores, previews, and character names
+  - Character filtering:
+    - `characters`: Array of character names to filter by
+    - `allCharacters`: If true, all characters must be present (AND). If false, at least one (OR). Default: false
+  - Examples:
+    - `characters: ["Alice", "Bob"], allCharacters: true` - Find chapters where both Alice AND Bob appear
+    - `characters: ["Alice", "Bob"]` - Find chapters where Alice OR Bob appear
   
 - **`rag-context`** - Retrieve relevant context for AI interactions
-  - Input: `query`, optional: `arc`, `pov`, `maxChapters`
-  - Output: Full chapter content for AI context
+  - Input: `timeline`, `query`, optional: `arc`, `pov`, `maxChapters`, `characters`
+  - Output: Full chapter content for AI context with character names
+  - Supports character filtering like `rag-search`
+  
+- **`rag-characters`** - Get all characters that appear in chapters with a specific character
+  - Input: `timeline`, `character` (character name)
+  - Output: List of co-occurring characters sorted alphabetically
+  - Use case: "Who does character X interact with?"
 
 ### Book Generation
 - **`book-generate`** - Generate PDF book from timeline content using LaTeX
-  - Input: `contentPath`, `outputPath`, optional: `episodes`, `format`
+  - Input: `timeline`, `outputPath`, optional: `episodes`, `format`
   - Output: PDF book with Victoria Regia template
   - Formats: `a4` (default), `a5`
   - Requirements: pandoc, LaTeX distribution (pdflatex/xelatex/lualatex)
+  - Note: Content path is auto-discovered from timeline directory structure
 
 ## Development
 

package/lib/server.d.ts

@@ -1,7 +1,12 @@
 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, rag: RAGSystem): Server<{
+interface TimelineContext {
+    tracker: Tracker;
+    rag: RAGSystem;
+    contentPath: string;
+}
+export declare function createServer(timelines: Map<string, TimelineContext>): Server<{
     method: string;
     params?: {
         [x: string]: unknown;
@@ -24,4 +29,10 @@ export declare function createServer(tracker: Tracker, rag: RAGSystem): Server<{
         [x: string]: unknown;
     } | undefined;
 }>;
+interface TimelineContext {
+    tracker: Tracker;
+    rag: RAGSystem;
+    contentPath: string;
+}
 export declare function runServer(): Promise<void>;
+export {};

package/lib/server.js

@@ -7,10 +7,10 @@ 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 { bookGenerate, bookGenerateSchema, 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';
+import { bookGenerate, bookGenerateSchema, chapterDelete, chapterDeleteSchema, chapterInfo, chapterInfoSchema, chapterInsert, chapterInsertSchema, chapterRefresh, chapterRefreshSchema, episodeInfo, episodeInfoSchema, episodeUpdate, episodeUpdateSchema, ragCharacters, ragCharactersSchema, 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, rag) {
+export function createServer(timelines) {
     const server = new Server({
         name: pkg.name,
         version: pkg.version,
@@ -82,6 +82,11 @@ export function createServer(tracker, rag) {
                     description: 'Retrieve relevant context for AI interactions',
                     inputSchema: zodToJsonSchema(ragContextSchema),
                 },
+                {
+                    name: 'rag-characters',
+                    description: 'Get all characters that appear in chapters with a specific character',
+                    inputSchema: zodToJsonSchema(ragCharactersSchema),
+                },
                 {
                     name: 'book-generate',
                     description: 'Generate PDF book from timeline content using LaTeX',
@@ -92,33 +97,82 @@ export function createServer(tracker, rag) {
     });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        // Helper to get timeline context
+        const getContext = (timeline) => {
+            const ctx = timelines.get(timeline);
+            if (!ctx) {
+                throw new Error(`Timeline "${timeline}" not found. Available: ${Array.from(timelines.keys()).join(', ')}`);
+            }
+            return ctx;
+        };
         switch (name) {
             case 'words-count':
                 return await wordsCount(wordsCountSchema.parse(args));
-            case 'chapter-info':
-                return await chapterInfo(chapterInfoSchema.parse(args), tracker);
-            case 'chapter-refresh':
-                return await chapterRefresh(chapterRefreshSchema.parse(args), tracker);
-            case 'chapter-delete':
-                return await chapterDelete(chapterDeleteSchema.parse(args), tracker);
-            case 'chapter-insert':
-                return await chapterInsert(chapterInsertSchema.parse(args), tracker);
-            case 'episode-info':
-                return await episodeInfo(episodeInfoSchema.parse(args), tracker);
-            case 'episode-update':
-                return await episodeUpdate(episodeUpdateSchema.parse(args), tracker);
-            case 'timeline-sync':
-                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);
-            case 'book-generate':
-                return await bookGenerate(bookGenerateSchema.parse(args));
+            case 'chapter-info': {
+                const parsed = chapterInfoSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await chapterInfo(parsed, tracker);
+            }
+            case 'chapter-refresh': {
+                const parsed = chapterRefreshSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await chapterRefresh(parsed, tracker);
+            }
+            case 'chapter-delete': {
+                const parsed = chapterDeleteSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await chapterDelete(parsed, tracker);
+            }
+            case 'chapter-insert': {
+                const parsed = chapterInsertSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await chapterInsert(parsed, tracker);
+            }
+            case 'episode-info': {
+                const parsed = episodeInfoSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await episodeInfo(parsed, tracker);
+            }
+            case 'episode-update': {
+                const parsed = episodeUpdateSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await episodeUpdate(parsed, tracker);
+            }
+            case 'timeline-sync': {
+                const parsed = timelineSyncSchema.parse(args);
+                const { tracker, contentPath } = getContext(parsed.timeline);
+                return await timelineSync({ ...parsed, contentPath }, tracker);
+            }
+            case 'stats': {
+                const parsed = statsSchema.parse(args);
+                const { tracker } = getContext(parsed.timeline);
+                return await stats(parsed, tracker);
+            }
+            case 'rag-index': {
+                const parsed = ragIndexSchema.parse(args);
+                const { tracker, rag, contentPath } = getContext(parsed.timeline);
+                return await ragIndex({ ...parsed, contentPath }, tracker, rag);
+            }
+            case 'rag-search': {
+                const parsed = ragSearchSchema.parse(args);
+                const { rag } = getContext(parsed.timeline);
+                return await ragSearch(parsed, rag);
+            }
+            case 'rag-context': {
+                const parsed = ragContextSchema.parse(args);
+                const { rag } = getContext(parsed.timeline);
+                return await ragContext(parsed, rag);
+            }
+            case 'rag-characters': {
+                const parsed = ragCharactersSchema.parse(args);
+                const { rag } = getContext(parsed.timeline);
+                return await ragCharacters(parsed, rag);
+            }
+            case 'book-generate': {
+                const parsed = bookGenerateSchema.parse(args);
+                const { contentPath } = getContext(parsed.timeline);
+                return await bookGenerate({ ...parsed, contentPath });
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -126,22 +180,59 @@ export function createServer(tracker, rag) {
     return server;
 }
 export async function runServer() {
-    // Initialize tracker database in appropriate location
-    const dbPath = process.env.NODE_ENV === 'test' ? ':memory:' : './tracker.db';
-    const tracker = new Tracker(dbPath);
-    await tracker.init();
-    console.error(`Tracker database initialized: ${dbPath}`);
-    // Initialize RAG system
-    const ragDbPath = process.env.ECHOES_RAG_DB_PATH || (process.env.NODE_ENV === 'test' ? ':memory:' : './rag.db');
-    const provider = (process.env.ECHOES_RAG_PROVIDER || 'e5-small');
-    const rag = new RAGSystem({
-        provider,
-        dbPath: ragDbPath,
-        geminiApiKey: process.env.ECHOES_GEMINI_API_KEY,
-    });
-    console.error(`RAG system initialized: ${ragDbPath} (provider: ${provider})`);
-    const server = createServer(tracker, rag);
+    // Validate we're running from .github directory
+    if (process.env.NODE_ENV !== 'test' && !process.cwd().endsWith('/.github')) {
+        throw new Error('Server must be run from .github directory');
+    }
+    const timelines = new Map();
+    if (process.env.NODE_ENV === 'test') {
+        // Test mode: single in-memory database
+        const tracker = new Tracker(':memory:');
+        await tracker.init();
+        const rag = new RAGSystem({
+            provider: 'e5-small',
+            dbPath: ':memory:',
+        });
+        timelines.set('test', { tracker, rag, contentPath: './test-content' });
+        console.error('Test mode: in-memory databases');
+    }
+    else {
+        // Production: discover timelines and create separate databases
+        const { readdirSync, existsSync, mkdirSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const parentDir = join(process.cwd(), '..');
+        const entries = readdirSync(parentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.startsWith('timeline-')) {
+                const timelineName = entry.name.replace('timeline-', '');
+                const timelinePath = join(parentDir, entry.name);
+                const contentPath = join(timelinePath, 'content');
+                if (!existsSync(contentPath)) {
+                    console.error(`Skipping ${entry.name}: no content directory`);
+                    continue;
+                }
+                // Initialize tracker
+                const trackerPath = join(timelinePath, 'tracker.db');
+                const tracker = new Tracker(trackerPath);
+                await tracker.init();
+                // Initialize RAG
+                const ragPath = join(timelinePath, 'rag.db');
+                const provider = (process.env.ECHOES_RAG_PROVIDER || 'e5-small');
+                const rag = new RAGSystem({
+                    provider,
+                    dbPath: ragPath,
+                    geminiApiKey: process.env.ECHOES_GEMINI_API_KEY,
+                });
+                timelines.set(timelineName, { tracker, rag, contentPath });
+                console.error(`Timeline "${timelineName}" initialized: ${trackerPath}`);
+            }
+        }
+        if (timelines.size === 0) {
+            throw new Error('No timelines found in parent directory');
+        }
+    }
+    const server = createServer(timelines);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('Echoes MCP Server running on stdio');
+    console.error(`Echoes MCP Server running on stdio (${timelines.size} timelines)`);
 }

package/lib/tools/book-generate.d.ts

@@ -1,26 +1,27 @@
 import { z } from 'zod';
 export declare const bookGenerateSchema: z.ZodObject<{
     timeline: z.ZodString;
-    contentPath: z.ZodString;
     outputPath: z.ZodString;
     episodes: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodEnum<["a4", "a5"]>>;
 }, "strip", z.ZodTypeAny, {
     timeline: string;
-    contentPath: string;
     outputPath: string;
     episodes?: string | undefined;
     format?: "a4" | "a5" | undefined;
 }, {
     timeline: string;
-    contentPath: string;
     outputPath: string;
     episodes?: string | undefined;
     format?: "a4" | "a5" | undefined;
 }>;
-export declare function bookGenerate(args: z.infer<typeof bookGenerateSchema>): Promise<{
+type BookGenerateArgs = z.infer<typeof bookGenerateSchema> & {
+    contentPath: string;
+};
+export declare function bookGenerate(args: BookGenerateArgs): Promise<{
     content: {
         type: "text";
         text: string;
     }[];
 }>;
+export {};

package/lib/tools/book-generate.js

@@ -2,7 +2,6 @@ import { generateBook } from '@echoes-io/books-generator';
 import { z } from 'zod';
 export const bookGenerateSchema = z.object({
     timeline: z.string().describe('Timeline name'),
-    contentPath: z.string().describe('Path to timeline content folder'),
     outputPath: z.string().describe('Output PDF file path'),
     episodes: z.string().optional().describe('Comma-separated episode numbers (e.g., "1,2,3")'),
     format: z.enum(['a4', 'a5']).optional().describe('Page format (default: a4)'),

package/lib/tools/index.d.ts

@@ -5,6 +5,7 @@ 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 { ragCharacters, ragCharactersSchema } from './rag-characters.js';
 export { ragContext, ragContextSchema } from './rag-context.js';
 export { ragIndex, ragIndexSchema } from './rag-index.js';
 export { ragSearch, ragSearchSchema } from './rag-search.js';

package/lib/tools/index.js

@@ -5,6 +5,7 @@ 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 { ragCharacters, ragCharactersSchema } from './rag-characters.js';
 export { ragContext, ragContextSchema } from './rag-context.js';
 export { ragIndex, ragIndexSchema } from './rag-index.js';
 export { ragSearch, ragSearchSchema } from './rag-search.js';

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

@@ -0,0 +1,18 @@
+import type { RAGSystem } from '@echoes-io/rag';
+import { z } from 'zod';
+export declare const ragCharactersSchema: z.ZodObject<{
+    timeline: z.ZodString;
+    character: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    timeline: string;
+    character: string;
+}, {
+    timeline: string;
+    character: string;
+}>;
+export declare function ragCharacters(args: z.infer<typeof ragCharactersSchema>, rag: RAGSystem): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/lib/tools/rag-characters.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export const ragCharactersSchema = z.object({
+    timeline: z.string().describe('Timeline name'),
+    character: z.string().describe('Character name to find co-occurrences for'),
+});
+export async function ragCharacters(args, rag) {
+    try {
+        const characters = await rag.getCharacterMentions(args.character);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        character: args.character,
+                        timeline: args.timeline,
+                        coOccurringCharacters: characters.filter((c) => c !== args.character).sort(),
+                        total: characters.length - 1,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get character mentions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

@@ -6,17 +6,20 @@ export declare const ragContextSchema: z.ZodObject<{
     arc: z.ZodOptional<z.ZodString>;
     pov: z.ZodOptional<z.ZodString>;
     maxChapters: z.ZodOptional<z.ZodNumber>;
+    characters: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     timeline: string;
     query: string;
     arc?: string | undefined;
     pov?: string | undefined;
+    characters?: string[] | undefined;
     maxChapters?: number | undefined;
 }, {
     timeline: string;
     query: string;
     arc?: string | undefined;
     pov?: string | undefined;
+    characters?: string[] | undefined;
     maxChapters?: number | undefined;
 }>;
 export declare function ragContext(args: z.infer<typeof ragContextSchema>, rag: RAGSystem): Promise<{

package/lib/tools/rag-context.js

@@ -5,6 +5,10 @@ export const ragContextSchema = z.object({
     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)'),
+    characters: z
+        .array(z.string())
+        .optional()
+        .describe('Filter by character names present in chapter'),
 });
 export async function ragContext(args, rag) {
     try {
@@ -14,6 +18,7 @@ export async function ragContext(args, rag) {
             arc: args.arc,
             pov: args.pov,
             maxChapters: args.maxChapters,
+            characters: args.characters,
         });
         return {
             content: [
@@ -33,6 +38,7 @@ export async function ragContext(args, rag) {
                                 chapter: r.metadata.number,
                                 pov: r.metadata.pov,
                                 title: r.metadata.title,
+                                characters: r.metadata.characterNames || [],
                             },
                             similarity: r.similarity,
                             content: r.content,

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

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

package/lib/tools/rag-index.js

@@ -4,7 +4,6 @@ import { parseMarkdown } from '@echoes-io/utils';
 import { z } from 'zod';
 export const ragIndexSchema = z.object({
     timeline: z.string().describe('Timeline name'),
-    contentPath: z.string().optional().describe('Path to content directory (required for indexing)'),
     arc: z.string().optional().describe('Index specific arc only'),
     episode: z.number().optional().describe('Index specific episode only (requires arc)'),
 });
@@ -35,46 +34,38 @@ export async function ragIndex(args, tracker, rag) {
         // Convert to embedding format and add to RAG
         const embeddingChapters = chapters
             .map((ch) => {
-            // If contentPath is provided, read actual file content
-            if (args.contentPath) {
-                try {
-                    // Find episode directory
-                    const episodeDir = `ep${String(ch.episodeNumber).padStart(2, '0')}`;
-                    const arcPath = join(args.contentPath, ch.arcName);
-                    const episodePath = readdirSync(arcPath, { withFileTypes: true })
-                        .filter((e) => e.isDirectory() && e.name.startsWith(episodeDir))
-                        .map((e) => join(arcPath, e.name))[0];
-                    if (!episodePath) {
-                        console.error(`Episode directory not found for ${ch.arcName}/ep${ch.episodeNumber}`);
-                        return null;
-                    }
-                    // Find chapter file by episode and chapter number (filename-agnostic for title/pov)
-                    const chapterPattern = `ep${String(ch.episodeNumber).padStart(2, '0')}-ch${String(ch.number).padStart(3, '0')}-`;
-                    const chapterFiles = readdirSync(episodePath).filter((f) => f.startsWith(chapterPattern) && f.endsWith('.md'));
-                    if (chapterFiles.length === 0) {
-                        console.error(`Chapter file not found for ${ch.arcName}/ep${ch.episodeNumber}/ch${ch.number}`);
-                        return null;
-                    }
-                    const filePath = join(episodePath, chapterFiles[0]);
-                    const fileContent = readFileSync(filePath, 'utf-8');
-                    const { content } = parseMarkdown(fileContent);
-                    return {
-                        id: `${ch.timelineName}-${ch.arcName}-${ch.episodeNumber}-${ch.number}`,
-                        metadata: ch,
-                        content,
-                    };
+            // Read actual file content
+            try {
+                // Find episode directory
+                const episodeDir = `ep${String(ch.episodeNumber).padStart(2, '0')}`;
+                const arcPath = join(args.contentPath, ch.arcName);
+                const episodePath = readdirSync(arcPath, { withFileTypes: true })
+                    .filter((e) => e.isDirectory() && e.name.startsWith(episodeDir))
+                    .map((e) => join(arcPath, e.name))[0];
+                if (!episodePath) {
+                    console.error(`Episode directory not found for ${ch.arcName}/ep${ch.episodeNumber}`);
+                    return null;
                 }
-                catch (error) {
-                    console.error(`Error reading chapter ${ch.arcName}/ep${ch.episodeNumber}/ch${ch.number}:`, error);
+                // Find chapter file by episode and chapter number (filename-agnostic for title/pov)
+                const chapterPattern = `ep${String(ch.episodeNumber).padStart(2, '0')}-ch${String(ch.number).padStart(3, '0')}-`;
+                const chapterFiles = readdirSync(episodePath).filter((f) => f.startsWith(chapterPattern) && f.endsWith('.md'));
+                if (chapterFiles.length === 0) {
+                    console.error(`Chapter file not found for ${ch.arcName}/ep${ch.episodeNumber}/ch${ch.number}`);
                     return null;
                 }
+                const filePath = join(episodePath, chapterFiles[0]);
+                const fileContent = readFileSync(filePath, 'utf-8');
+                const { content } = parseMarkdown(fileContent);
+                return {
+                    id: `${ch.timelineName}-${ch.arcName}-${ch.episodeNumber}-${ch.number}`,
+                    metadata: ch,
+                    content,
+                };
+            }
+            catch (error) {
+                console.error(`Error reading chapter ${ch.arcName}/ep${ch.episodeNumber}/ch${ch.number}:`, error);
+                return null;
             }
-            // Fallback: no content (for tests or when contentPath not provided)
-            return {
-                id: `${ch.timelineName}-${ch.arcName}-${ch.episodeNumber}-${ch.number}`,
-                metadata: ch,
-                content: '',
-            };
         })
             .filter((ch) => ch !== null);
         await rag.addChapters(embeddingChapters);

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

@@ -6,18 +6,24 @@ export declare const ragSearchSchema: z.ZodObject<{
     arc: z.ZodOptional<z.ZodString>;
     pov: z.ZodOptional<z.ZodString>;
     maxResults: z.ZodOptional<z.ZodNumber>;
+    characters: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allCharacters: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     timeline: string;
     query: string;
     arc?: string | undefined;
     pov?: string | undefined;
+    characters?: string[] | undefined;
     maxResults?: number | undefined;
+    allCharacters?: boolean | undefined;
 }, {
     timeline: string;
     query: string;
     arc?: string | undefined;
     pov?: string | undefined;
+    characters?: string[] | undefined;
     maxResults?: number | undefined;
+    allCharacters?: boolean | undefined;
 }>;
 export declare function ragSearch(args: z.infer<typeof ragSearchSchema>, rag: RAGSystem): Promise<{
     content: {

package/lib/tools/rag-search.js

@@ -5,6 +5,14 @@ export const ragSearchSchema = z.object({
     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)'),
+    characters: z
+        .array(z.string())
+        .optional()
+        .describe('Filter by character names present in chapter'),
+    allCharacters: z
+        .boolean()
+        .optional()
+        .describe('If true, all characters must be present (AND). If false, at least one (OR). Default: false'),
 });
 export async function ragSearch(args, rag) {
     try {
@@ -13,6 +21,8 @@ export async function ragSearch(args, rag) {
             arc: args.arc,
             pov: args.pov,
             maxResults: args.maxResults,
+            characters: args.characters,
+            allCharacters: args.allCharacters,
         });
         return {
             content: [
@@ -32,6 +42,7 @@ export async function ragSearch(args, rag) {
                                 chapter: r.metadata.number,
                                 pov: r.metadata.pov,
                                 title: r.metadata.title,
+                                characters: r.metadata.characterNames || [],
                             },
                             similarity: r.similarity,
                             preview: `${r.content.substring(0, 200)}...`,

package/lib/tools/timeline-sync.d.ts

@@ -2,17 +2,18 @@ import type { Tracker } from '@echoes-io/tracker';
 import { z } from 'zod';
 export declare const timelineSyncSchema: z.ZodObject<{
     timeline: z.ZodString;
-    contentPath: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     timeline: string;
-    contentPath: string;
 }, {
     timeline: string;
-    contentPath: string;
 }>;
-export declare function timelineSync(args: z.infer<typeof timelineSyncSchema>, tracker: Tracker): Promise<{
+type TimelineSyncArgs = z.infer<typeof timelineSyncSchema> & {
+    contentPath: string;
+};
+export declare function timelineSync(args: TimelineSyncArgs, tracker: Tracker): Promise<{
     content: {
         type: "text";
         text: string;
     }[];
 }>;
+export {};

package/lib/tools/timeline-sync.js

@@ -4,7 +4,6 @@ import { getTextStats, parseMarkdown } from '@echoes-io/utils';
 import { z } from 'zod';
 export const timelineSyncSchema = z.object({
     timeline: z.string().describe('Timeline name'),
-    contentPath: z.string().describe('Path to content directory'),
 });
 export async function timelineSync(args, tracker) {
     try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echoes-io/mcp-server",
   "type": "module",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Model Context Protocol server for AI integration with Echoes storytelling platform",
   "scripts": {
     "dev": "tsx cli/index.ts",
@@ -63,30 +63,30 @@
     ]
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.2",
+    "@biomejs/biome": "^2.3.3",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@tsconfig/node22": "^22.0.2",
-    "@types/node": "^24.9.1",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^24.10.0",
+    "@vitest/coverage-v8": "^4.0.6",
     "concurrently": "^9.2.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.5",
     "lockfile-lint": "^4.14.1",
     "ls-engines": "^0.9.3",
     "publint": "^0.3.15",
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.0",
     "semantic-release": "^25.0.1",
     "tsx": "^4.19.2",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.6"
   },
   "dependencies": {
     "@echoes-io/books-generator": "^1.0.1",
-    "@echoes-io/models": "^1.0.2",
-    "@echoes-io/rag": "^1.1.3",
+    "@echoes-io/models": "^1.0.3",
+    "@echoes-io/rag": "^1.2.0",
     "@echoes-io/tracker": "^1.0.1",
     "@echoes-io/utils": "^1.2.0",
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.2"
   }
 }