@echoes-io/mcp-server 1.0.0 → 1.2.0

package/lib/tools/episode-info.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const episodeInfoSchema = z.object({
+    arc: z.string().describe('Arc name'),
+    episode: z.number().describe('Episode number'),
+});
+export async function episodeInfo(args, tracker) {
+    try {
+        const timeline = getTimeline();
+        const episode = await tracker.getEpisode(timeline, args.arc, args.episode);
+        if (!episode) {
+            throw new Error(`Episode not found: ${timeline}/${args.arc}/ep${args.episode}`);
+        }
+        const chapters = await tracker.getChapters(timeline, args.arc, args.episode);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        arc: args.arc,
+                        episodeInfo: {
+                            number: episode.number,
+                            title: episode.title,
+                            slug: episode.slug,
+                            description: episode.description,
+                        },
+                        chapters: chapters.map((ch) => ({
+                            number: ch.number,
+                            pov: ch.pov,
+                            title: ch.title,
+                            words: ch.words,
+                        })),
+                        stats: {
+                            totalChapters: chapters.length,
+                            totalWords: chapters.reduce((sum, ch) => sum + ch.words, 0),
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get episode info: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/tools/episode-update.d.ts

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

package/lib/tools/episode-update.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const episodeUpdateSchema = z.object({
+    arc: z.string().describe('Arc name'),
+    episode: z.number().describe('Episode number'),
+    description: z.string().optional().describe('Episode description'),
+    title: z.string().optional().describe('Episode title'),
+    slug: z.string().optional().describe('Episode slug'),
+});
+export async function episodeUpdate(args, tracker) {
+    try {
+        const timeline = getTimeline();
+        const existing = await tracker.getEpisode(timeline, args.arc, args.episode);
+        if (!existing) {
+            throw new Error(`Episode not found: ${timeline}/${args.arc}/ep${args.episode}`);
+        }
+        const updateData = {};
+        if (args.description !== undefined)
+            updateData.description = args.description;
+        if (args.title !== undefined)
+            updateData.title = args.title;
+        if (args.slug !== undefined)
+            updateData.slug = args.slug;
+        await tracker.updateEpisode(timeline, args.arc, args.episode, updateData);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        arc: args.arc,
+                        episode: args.episode,
+                        updated: updateData,
+                        message: 'Episode successfully updated',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to update episode: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/tools/index.d.ts

@@ -0,0 +1,12 @@
+export { chapterDelete, chapterDeleteSchema } from './chapter-delete.js';
+export { chapterInfo, chapterInfoSchema } from './chapter-info.js';
+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

@@ -0,0 +1,12 @@
+export { chapterDelete, chapterDeleteSchema } from './chapter-delete.js';
+export { chapterInfo, chapterInfoSchema } from './chapter-info.js';
+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/lib/tools/stats.d.ts

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

package/lib/tools/stats.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const statsSchema = z.object({
+    arc: z.string().optional().describe('Filter by arc name'),
+    episode: z.number().optional().describe('Filter by episode number'),
+    pov: z.string().optional().describe('Filter by POV character'),
+});
+export async function stats(args, tracker) {
+    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);
+                }
+            }
+        }
+        // Filter by POV if specified
+        if (args.pov) {
+            chapters = chapters.filter((ch) => ch.pov === args.pov);
+        }
+        // Calculate statistics
+        const totalWords = chapters.reduce((sum, ch) => sum + ch.words, 0);
+        const totalChapters = chapters.length;
+        // POV distribution
+        const povStats = {};
+        for (const ch of chapters) {
+            if (!povStats[ch.pov]) {
+                povStats[ch.pov] = { chapters: 0, words: 0 };
+            }
+            povStats[ch.pov].chapters++;
+            povStats[ch.pov].words += ch.words;
+        }
+        // Arc breakdown (if not filtered by arc)
+        const arcStats = {};
+        if (!args.arc) {
+            for (const ch of chapters) {
+                if (!arcStats[ch.arcName]) {
+                    arcStats[ch.arcName] = { chapters: 0, words: 0, episodes: new Set() };
+                }
+                arcStats[ch.arcName].chapters++;
+                arcStats[ch.arcName].words += ch.words;
+                arcStats[ch.arcName].episodes.add(ch.episodeNumber);
+            }
+        }
+        // Episode breakdown (if filtered by arc but not episode)
+        const episodeStats = {};
+        if (args.arc && !args.episode) {
+            for (const ch of chapters) {
+                if (!episodeStats[ch.episodeNumber]) {
+                    episodeStats[ch.episodeNumber] = { chapters: 0, words: 0 };
+                }
+                episodeStats[ch.episodeNumber].chapters++;
+                episodeStats[ch.episodeNumber].words += ch.words;
+            }
+        }
+        const result = {
+            timeline,
+            filters: {
+                arc: args.arc || null,
+                episode: args.episode || null,
+                pov: args.pov || null,
+            },
+            summary: {
+                totalChapters,
+                totalWords,
+                averageChapterLength: totalChapters > 0 ? Math.round(totalWords / totalChapters) : 0,
+            },
+            povDistribution: Object.entries(povStats).map(([pov, stats]) => ({
+                pov,
+                chapters: stats.chapters,
+                words: stats.words,
+                percentage: totalWords > 0 ? Math.round((stats.words / totalWords) * 100) : 0,
+            })),
+        };
+        if (!args.arc && Object.keys(arcStats).length > 0) {
+            result.arcBreakdown = Object.entries(arcStats).map(([arc, stats]) => ({
+                arc,
+                chapters: stats.chapters,
+                words: stats.words,
+                episodes: stats.episodes.size,
+            }));
+        }
+        if (args.arc && !args.episode && Object.keys(episodeStats).length > 0) {
+            result.episodeBreakdown = Object.entries(episodeStats).map(([episode, stats]) => ({
+                episode: Number(episode),
+                chapters: stats.chapters,
+                words: stats.words,
+            }));
+        }
+        if (totalChapters > 0) {
+            const sortedByWords = [...chapters].sort((a, b) => b.words - a.words);
+            result.extremes = {
+                longest: {
+                    title: sortedByWords[0].title,
+                    pov: sortedByWords[0].pov,
+                    words: sortedByWords[0].words,
+                },
+                shortest: {
+                    title: sortedByWords[sortedByWords.length - 1].title,
+                    pov: sortedByWords[sortedByWords.length - 1].pov,
+                    words: sortedByWords[sortedByWords.length - 1].words,
+                },
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get stats: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

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