@echoes-io/mcp-server 1.0.0 → 1.1.0

package/README.md

@@ -15,7 +15,10 @@ 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"],
+      "env": {
+        "ECHOES_TIMELINE": "your-timeline-name"
+      }
     }
   }
 }
@@ -33,21 +36,57 @@ Then configure:
 {
   "mcpServers": {
     "echoes": {
-      "command": "echoes-mcp-server"
+      "command": "echoes-mcp-server",
+      "env": {
+        "ECHOES_TIMELINE": "your-timeline-name"
+      }
     }
   }
 }
 ```
 
-## Usage
-
-Once configured, the server provides tools for:
-- Content management (chapters, episodes, arcs)
-- Word counting and text statistics
-- Database operations via @echoes-io/tracker
-- Timeline synchronization
-
-Available tools will be listed by your MCP client.
+**Important:** The `ECHOES_TIMELINE` environment variable must be set to specify which timeline to work with. All tools operate on this timeline.
+
+## Available Tools
+
+All tools operate on the timeline specified by the `ECHOES_TIMELINE` environment variable.
+
+### Content Operations
+- **`words-count`** - Count words and text statistics in markdown files
+  - Input: `file` (path to markdown file)
+  
+- **`chapter-info`** - Extract chapter metadata from database
+  - Input: `arc`, `episode`, `chapter`
+  
+- **`chapter-refresh`** - Refresh chapter metadata and word counts from file
+  - Input: `file` (path to chapter file)
+  
+- **`chapter-insert`** - Insert new chapter with automatic renumbering
+  - Input: `arc`, `episode`, `after`, `pov`, `title`, optional: `excerpt`, `location`, `outfit`, `kink`, `file`
+  
+- **`chapter-delete`** - Delete chapter from database and optionally from filesystem
+  - Input: `arc`, `episode`, `chapter`, optional: `file` (to delete from filesystem)
+
+### Episode Operations
+- **`episode-info`** - Get episode information and list of chapters
+  - Input: `arc`, `episode`
+  
+- **`episode-update`** - Update episode metadata (description, title, slug)
+  - Input: `arc`, `episode`, optional: `description`, `title`, `slug`
+
+### Timeline Operations
+- **`timeline-sync`** - Synchronize filesystem content with database
+  - Input: `contentPath` (path to content directory)
+
+### Statistics
+- **`stats`** - Get aggregate statistics with optional filters
+  - Input: optional: `arc`, `episode`, `pov`
+  - Output: Total words/chapters, POV distribution, arc/episode breakdown, longest/shortest chapters
+  - Examples:
+    - No filters: Overall timeline statistics
+    - `arc: "arc1"`: Statistics for specific arc
+    - `arc: "arc1", episode: 1`: Statistics for specific episode
+    - `pov: "Alice"`: Statistics for specific POV across timeline
 
 ## Development
 
@@ -73,10 +112,24 @@ npm run lint:fix
 ### Tech Stack
 
 - **Language**: TypeScript (strict mode)
-- **Testing**: Vitest
+- **Testing**: Vitest (97%+ coverage)
 - **Linting**: Biome
 - **Build**: TypeScript compiler
 
+### Architecture
+
+- **MCP Protocol**: Standard Model Context Protocol implementation
+- **Database**: SQLite via @echoes-io/tracker (singleton pattern)
+- **Validation**: Zod schemas for type-safe inputs
+- **Testing**: Comprehensive unit and integration tests
+- **Environment**: Uses `ECHOES_TIMELINE` env var for timeline context
+
+## Roadmap
+
+### 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
 
 MIT

package/lib/server.d.ts

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

package/lib/server.js

@@ -1,12 +1,15 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+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';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-export function createServer() {
+export function createServer(tracker) {
     const server = new Server({
         name: pkg.name,
         version: pkg.version,
@@ -17,16 +20,89 @@ export function createServer() {
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return {
-            tools: [],
+            tools: [
+                {
+                    name: 'words-count',
+                    description: 'Count words and text statistics in a markdown file',
+                    inputSchema: zodToJsonSchema(wordsCountSchema),
+                },
+                {
+                    name: 'chapter-info',
+                    description: 'Extract chapter metadata, content preview, and statistics',
+                    inputSchema: zodToJsonSchema(chapterInfoSchema),
+                },
+                {
+                    name: 'episode-info',
+                    description: 'Get episode information and list of chapters',
+                    inputSchema: zodToJsonSchema(episodeInfoSchema),
+                },
+                {
+                    name: 'episode-update',
+                    description: 'Update episode metadata (description, title, slug)',
+                    inputSchema: zodToJsonSchema(episodeUpdateSchema),
+                },
+                {
+                    name: 'chapter-refresh',
+                    description: 'Refresh chapter metadata and statistics from file',
+                    inputSchema: zodToJsonSchema(chapterRefreshSchema),
+                },
+                {
+                    name: 'chapter-delete',
+                    description: 'Delete chapter from database and optionally from filesystem',
+                    inputSchema: zodToJsonSchema(chapterDeleteSchema),
+                },
+                {
+                    name: 'chapter-insert',
+                    description: 'Insert new chapter and automatically renumber subsequent chapters',
+                    inputSchema: zodToJsonSchema(chapterInsertSchema),
+                },
+                {
+                    name: 'timeline-sync',
+                    description: 'Synchronize timeline content with database',
+                    inputSchema: zodToJsonSchema(timelineSyncSchema),
+                },
+                {
+                    name: 'stats',
+                    description: 'Get statistics for timeline, arc, episode, or POV',
+                    inputSchema: zodToJsonSchema(statsSchema),
+                },
+            ],
         };
     });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        throw new Error(`Unknown tool: ${request.params.name}`);
+        const { name, arguments: args } = request.params;
+        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);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
     });
     return server;
 }
 export async function runServer() {
-    const server = createServer();
+    // 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}`);
+    const server = createServer(tracker);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('Echoes MCP Server running on stdio');

package/lib/tools/chapter-delete.d.ts

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

package/lib/tools/chapter-delete.js

@@ -0,0 +1,49 @@
+import { unlinkSync } from 'node:fs';
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const chapterDeleteSchema = z.object({
+    arc: z.string().describe('Arc name'),
+    episode: z.number().describe('Episode number'),
+    chapter: z.number().describe('Chapter number'),
+    file: z.string().optional().describe('Path to markdown file to delete from filesystem'),
+});
+export async function chapterDelete(args, tracker) {
+    try {
+        const timeline = getTimeline();
+        const existing = await tracker.getChapter(timeline, args.arc, args.episode, args.chapter);
+        if (!existing) {
+            throw new Error(`Chapter not found: ${timeline}/${args.arc}/ep${args.episode}/ch${args.chapter}`);
+        }
+        await tracker.deleteChapter(timeline, args.arc, args.episode, args.chapter);
+        let fileDeleted = false;
+        if (args.file) {
+            unlinkSync(args.file);
+            fileDeleted = true;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        arc: args.arc,
+                        episode: args.episode,
+                        chapter: args.chapter,
+                        deleted: {
+                            pov: existing.pov,
+                            title: existing.title,
+                            words: existing.words,
+                        },
+                        fileDeleted,
+                        message: fileDeleted
+                            ? 'Chapter deleted from database and filesystem'
+                            : 'Chapter deleted from database only',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to delete chapter: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/tools/chapter-info.d.ts

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

package/lib/tools/chapter-info.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const chapterInfoSchema = z.object({
+    arc: z.string().describe('Arc name'),
+    episode: z.number().describe('Episode number'),
+    chapter: z.number().describe('Chapter number'),
+});
+export async function chapterInfo(args, tracker) {
+    try {
+        const timeline = getTimeline();
+        const chapter = await tracker.getChapter(timeline, args.arc, args.episode, args.chapter);
+        if (!chapter) {
+            throw new Error(`Chapter not found: ${timeline}/${args.arc}/ep${args.episode}/ch${args.chapter}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        arc: args.arc,
+                        episode: args.episode,
+                        chapter: args.chapter,
+                        metadata: {
+                            pov: chapter.pov,
+                            title: chapter.title,
+                            date: chapter.date,
+                            excerpt: chapter.excerpt,
+                            location: chapter.location,
+                            outfit: chapter.outfit,
+                            kink: chapter.kink,
+                        },
+                        stats: {
+                            words: chapter.words,
+                            characters: chapter.characters,
+                            charactersNoSpaces: chapter.charactersNoSpaces,
+                            paragraphs: chapter.paragraphs,
+                            sentences: chapter.sentences,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to get chapter info: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/tools/chapter-insert.d.ts

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

package/lib/tools/chapter-insert.js

@@ -0,0 +1,99 @@
+import { getTextStats, parseMarkdown } from '@echoes-io/utils';
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const chapterInsertSchema = z.object({
+    arc: z.string().describe('Arc name'),
+    episode: z.number().describe('Episode number'),
+    after: z.number().describe('Insert after this chapter number'),
+    pov: z.string().describe('Point of view character'),
+    title: z.string().describe('Chapter title'),
+    excerpt: z.string().optional().describe('Chapter excerpt'),
+    location: z.string().optional().describe('Chapter location'),
+    outfit: z.string().optional().describe('Character outfit'),
+    kink: z.string().optional().describe('Content tags'),
+    file: z.string().optional().describe('Path to markdown file to read content from'),
+});
+export async function chapterInsert(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 existingChapters = await tracker.getChapters(timeline, args.arc, args.episode);
+        const newChapterNumber = args.after + 1;
+        const chaptersToRenumber = existingChapters.filter((ch) => ch.number >= newChapterNumber);
+        for (const chapter of chaptersToRenumber) {
+            try {
+                await tracker.updateChapter(timeline, args.arc, args.episode, chapter.number, {
+                    number: chapter.number + 1,
+                });
+            }
+            catch (error) {
+                throw new Error(`Failed to renumber chapter ${chapter.number}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        let words = 0;
+        let characters = 0;
+        let charactersNoSpaces = 0;
+        let paragraphs = 0;
+        let sentences = 0;
+        if (args.file) {
+            const { readFileSync } = await import('node:fs');
+            const content = readFileSync(args.file, 'utf-8');
+            const { content: markdownContent } = parseMarkdown(content);
+            const stats = getTextStats(markdownContent);
+            words = stats.words;
+            characters = stats.characters;
+            charactersNoSpaces = stats.charactersNoSpaces;
+            paragraphs = stats.paragraphs;
+            sentences = stats.sentences;
+        }
+        await tracker.createChapter({
+            timelineName: timeline,
+            arcName: args.arc,
+            episodeNumber: args.episode,
+            partNumber: 1,
+            number: newChapterNumber,
+            pov: args.pov,
+            title: args.title,
+            date: new Date(),
+            excerpt: args.excerpt || '',
+            location: args.location || '',
+            outfit: args.outfit || '',
+            kink: args.kink || '',
+            words,
+            characters,
+            charactersNoSpaces,
+            paragraphs,
+            sentences,
+            readingTimeMinutes: Math.ceil(words / 200),
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        arc: args.arc,
+                        episode: args.episode,
+                        inserted: {
+                            chapter: newChapterNumber,
+                            pov: args.pov,
+                            title: args.title,
+                            words,
+                        },
+                        renumbered: chaptersToRenumber.map((ch) => ({
+                            oldNumber: ch.number,
+                            newNumber: ch.number + 1,
+                            title: ch.title,
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to insert chapter: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/tools/chapter-refresh.d.ts

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

package/lib/tools/chapter-refresh.js

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs';
+import { getTextStats, parseMarkdown } from '@echoes-io/utils';
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const chapterRefreshSchema = z.object({
+    file: z.string().describe('Path to chapter markdown file'),
+});
+export async function chapterRefresh(args, tracker) {
+    try {
+        const content = readFileSync(args.file, 'utf-8');
+        const { metadata, content: markdownContent } = parseMarkdown(content);
+        const stats = getTextStats(markdownContent);
+        const timeline = getTimeline();
+        const arc = metadata.arc;
+        const episode = metadata.episode;
+        const chapter = metadata.chapter;
+        if (!arc || !episode || !chapter) {
+            throw new Error('Missing required metadata: arc, episode, or chapter');
+        }
+        const existing = await tracker.getChapter(timeline, arc, episode, chapter);
+        if (!existing) {
+            throw new Error(`Chapter not found in database: ${timeline}/${arc}/ep${episode}/ch${chapter}`);
+        }
+        const chapterData = {
+            timelineName: timeline,
+            arcName: arc,
+            episodeNumber: episode,
+            partNumber: metadata.part || 1,
+            number: chapter,
+            pov: metadata.pov || 'Unknown',
+            title: metadata.title || 'Untitled',
+            date: new Date(metadata.date || Date.now()),
+            excerpt: metadata.excerpt || '',
+            location: metadata.location || '',
+            outfit: metadata.outfit || '',
+            kink: metadata.kink || '',
+            words: stats.words,
+            characters: stats.characters,
+            charactersNoSpaces: stats.charactersNoSpaces,
+            paragraphs: stats.paragraphs,
+            sentences: stats.sentences,
+            readingTimeMinutes: Math.ceil(stats.words / 200),
+        };
+        await tracker.updateChapter(timeline, arc, episode, chapter, chapterData);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        file: args.file,
+                        timeline,
+                        arc,
+                        episode,
+                        chapter,
+                        updated: {
+                            metadata: {
+                                pov: chapterData.pov,
+                                title: chapterData.title,
+                                date: chapterData.date,
+                                excerpt: chapterData.excerpt,
+                                location: chapterData.location,
+                            },
+                            stats: {
+                                words: stats.words,
+                                characters: stats.characters,
+                                paragraphs: stats.paragraphs,
+                                sentences: stats.sentences,
+                                readingTimeMinutes: chapterData.readingTimeMinutes,
+                            },
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to refresh chapter: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

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

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,9 @@
+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 { 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,9 @@
+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 { stats, statsSchema } from './stats.js';
+export { timelineSync, timelineSyncSchema } from './timeline-sync.js';
+export { wordsCount, wordsCountSchema } from './words-count.js';

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;
+    }[];
+}>;

package/lib/tools/timeline-sync.js

@@ -0,0 +1,183 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { getTextStats, parseMarkdown } from '@echoes-io/utils';
+import { z } from 'zod';
+import { getTimeline } from '../utils.js';
+export const timelineSyncSchema = z.object({
+    contentPath: z.string().describe('Path to content directory'),
+});
+export async function timelineSync(args, tracker) {
+    try {
+        const timeline = getTimeline();
+        let added = 0, updated = 0, deleted = 0, errors = 0;
+        let timelineRecord = await tracker.getTimeline(timeline);
+        if (!timelineRecord) {
+            timelineRecord = await tracker.createTimeline({
+                name: timeline,
+                description: `Timeline ${timeline}`,
+            });
+            added++;
+        }
+        const arcs = readdirSync(args.contentPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        for (const arcName of arcs) {
+            const arcPath = join(args.contentPath, arcName);
+            let arc = await tracker.getArc(timeline, arcName);
+            if (!arc) {
+                arc = await tracker.createArc({
+                    timelineName: timeline,
+                    name: arcName,
+                    number: 1,
+                    description: `Arc ${arcName}`,
+                });
+                added++;
+            }
+            const episodes = readdirSync(arcPath, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('ep'))
+                .map((entry) => ({
+                name: entry.name,
+                number: Number.parseInt(entry.name.match(/ep(\d+)/)?.[1] || '0', 10),
+            }));
+            for (const ep of episodes) {
+                const episodePath = join(arcPath, ep.name);
+                let episode = await tracker.getEpisode(timeline, arcName, ep.number);
+                if (!episode) {
+                    episode = await tracker.createEpisode({
+                        timelineName: timeline,
+                        arcName: arcName,
+                        number: ep.number,
+                        slug: ep.name,
+                        title: ep.name,
+                        description: `Episode ${ep.number}`,
+                    });
+                    added++;
+                }
+                const chapters = readdirSync(episodePath)
+                    .filter((file) => extname(file) === '.md')
+                    .map((file) => {
+                    try {
+                        const filePath = join(episodePath, file);
+                        const content = require('node:fs').readFileSync(filePath, 'utf-8');
+                        const { metadata, content: markdownContent } = parseMarkdown(content);
+                        const stats = getTextStats(markdownContent);
+                        return {
+                            file: filePath,
+                            metadata,
+                            stats,
+                        };
+                    }
+                    catch (_error) {
+                        errors++;
+                        return null;
+                    }
+                })
+                    .filter((ch) => ch !== null);
+                for (const chapterData of chapters) {
+                    if (!chapterData)
+                        continue;
+                    const chNumber = chapterData.metadata.chapter;
+                    if (!chNumber)
+                        continue;
+                    try {
+                        const existing = await tracker.getChapter(timeline, arcName, ep.number, chNumber);
+                        const data = {
+                            timelineName: timeline,
+                            arcName: arcName,
+                            episodeNumber: ep.number,
+                            partNumber: chapterData.metadata.part || 1,
+                            number: chNumber,
+                            pov: chapterData.metadata.pov || 'Unknown',
+                            title: chapterData.metadata.title || 'Untitled',
+                            date: new Date(chapterData.metadata.date || Date.now()),
+                            excerpt: chapterData.metadata.excerpt || '',
+                            location: chapterData.metadata.location || '',
+                            outfit: chapterData.metadata.outfit || '',
+                            kink: chapterData.metadata.kink || '',
+                            words: chapterData.stats.words,
+                            characters: chapterData.stats.characters,
+                            charactersNoSpaces: chapterData.stats.charactersNoSpaces,
+                            paragraphs: chapterData.stats.paragraphs,
+                            sentences: chapterData.stats.sentences,
+                            readingTimeMinutes: Math.ceil(chapterData.stats.words / 200),
+                        };
+                        if (existing) {
+                            await tracker.updateChapter(timeline, arcName, ep.number, chNumber, data);
+                            updated++;
+                        }
+                        else {
+                            await tracker.createChapter(data);
+                            added++;
+                        }
+                    }
+                    catch (_error) {
+                        errors++;
+                    }
+                }
+            }
+        }
+        try {
+            const dbArcs = await tracker.getArcs(timeline);
+            for (const arc of dbArcs) {
+                const dbEpisodes = await tracker.getEpisodes(timeline, arc.name);
+                for (const episode of dbEpisodes) {
+                    const allChapters = await tracker.getChapters(timeline, arc.name, episode.number);
+                    for (const dbChapter of allChapters) {
+                        let fileExists = false;
+                        try {
+                            const arcPath = join(args.contentPath, dbChapter.arcName);
+                            if (existsSync(arcPath)) {
+                                const episodeDirs = readdirSync(arcPath, { withFileTypes: true }).filter((entry) => entry.isDirectory() &&
+                                    entry.name.startsWith(`ep${dbChapter.episodeNumber.toString().padStart(2, '0')}-`));
+                                for (const episodeDir of episodeDirs) {
+                                    const episodePath = join(arcPath, episodeDir.name);
+                                    const chapterFiles = readdirSync(episodePath).filter((file) => file.includes(`ch${dbChapter.number.toString().padStart(3, '0')}`) &&
+                                        file.endsWith('.md'));
+                                    if (chapterFiles.length > 0) {
+                                        fileExists = true;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                        catch (_error) {
+                            fileExists = false;
+                        }
+                        if (!fileExists) {
+                            try {
+                                await tracker.deleteChapter(dbChapter.timelineName, dbChapter.arcName, dbChapter.episodeNumber, dbChapter.number);
+                                deleted++;
+                            }
+                            catch (_error) {
+                                errors++;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (_error) {
+            errors++;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        timeline,
+                        contentPath: args.contentPath,
+                        summary: {
+                            added,
+                            updated,
+                            deleted,
+                            errors,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to sync timeline: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

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

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const wordsCountSchema: z.ZodObject<{
+    file: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+}, {
+    file: string;
+}>;
+export declare function wordsCount(args: z.infer<typeof wordsCountSchema>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/lib/tools/words-count.js

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { getTextStats } from '@echoes-io/utils';
+import { z } from 'zod';
+export const wordsCountSchema = z.object({
+    file: z.string().describe('Path to markdown file'),
+});
+export async function wordsCount(args) {
+    try {
+        const content = readFileSync(args.file, 'utf-8');
+        const stats = getTextStats(content);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        file: args.file,
+                        words: stats.words,
+                        characters: stats.characters,
+                        charactersNoSpaces: stats.charactersNoSpaces,
+                        paragraphs: stats.paragraphs,
+                        sentences: stats.sentences,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to count words: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}

package/lib/utils.d.ts

@@ -0,0 +1 @@
+export declare function getTimeline(): string;

package/lib/utils.js

@@ -0,0 +1,7 @@
+export function getTimeline() {
+    const timeline = process.env.ECHOES_TIMELINE;
+    if (!timeline) {
+        throw new Error('ECHOES_TIMELINE environment variable is not set');
+    }
+    return timeline;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echoes-io/mcp-server",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Model Context Protocol server for AI integration with Echoes storytelling platform",
   "scripts": {
     "dev": "tsx cli/index.ts",