Echoes MCP Server

Model Context Protocol server for AI integration with Echoes storytelling platform.

Features

• Narrative Knowledge Graph: Automatically extracts characters, locations, events, and their relationships using Gemini AI
• Semantic Search: Find relevant chapters using natural language queries
• Entity Search: Search for characters, locations, and events
• Relation Search: Explore relationships between entities
• Arc Isolation: Each arc is a separate narrative universe - no cross-arc contamination
• Statistics: Aggregate word counts, POV distribution, and more
• Dynamic Prompts: Reusable prompt templates with placeholder substitution

Installation

npm install -g @echoes-io/mcp-server

Or run directly with npx:

npx @echoes-io/mcp-server --help

Requirements

• Node.js 20+
• Gemini API key (for entity extraction)

Usage

CLI

# Count words in a markdown file
echoes words-count ./content/arc1/ep01/ch001.md

# Index timeline content
echoes index ./content

# Index only a specific arc
echoes index ./content --arc bloom

# Get statistics
echoes stats
echoes stats --arc arc1 --pov Alice

# Search (filters by arc to avoid cross-arc contamination)
echoes search "primo incontro" --arc bloom
echoes search "Alice" --type entities --arc bloom

# Check narrative consistency
echoes check-consistency bloom
echoes check-consistency bloom --rules kink-firsts,outfit-claims

MCP Server

Configure in your MCP client (e.g., Claude Desktop, Kiro):

{
  "mcpServers": {
    "echoes": {
      "command": "npx",
      "args": ["@echoes-io/mcp-server"],
      "cwd": "/path/to/timeline",
      "env": {
        "GEMINI_API_KEY": "your_api_key"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	-	API key for Gemini entity extraction
ECHOES_GEMINI_MODEL	No	gemini-2.5-flash	Gemini model for extraction
ECHOES_EMBEDDING_MODEL	No	Xenova/e5-small-v2	HuggingFace embedding model
ECHOES_EMBEDDING_DTYPE	No	fp32	Quantization level: fp32, q8, q4 (see Performance Notes)
HF_TOKEN	No	-	HuggingFace token for gated models

Available Tools

Tool	Description
words-count	Count words and statistics in a markdown file
index	Index timeline content into LanceDB
search	Search chapters, entities, or relations
stats	Get aggregate statistics
check-consistency	Analyze arc for narrative inconsistencies
timeline-overview	Quick overview of all arcs: status, chapters, words, POVs
graph-export	Export knowledge graph in various formats
history	Query character/arc history (kinks, outfits, locations, relations)
review-generate	Generate review file for pending entity/relation extractions
review-status	Show review statistics for an arc
review-apply	Apply corrections from review file to database

Available Prompts

Prompt	Arguments	Description
arc-resume	arc, episode?, lastChapters?	Load complete context for resuming work on an arc
new-chapter	arc, chapter	Create a new chapter
revise-chapter	arc, chapter	Revise an existing chapter
expand-chapter	arc, chapter, target	Expand chapter to target word count
new-character	name	Create a new character sheet
new-episode	arc, episode	Create a new episode outline
new-arc	name	Create a new story arc
revise-arc	arc	Review and fix an entire arc

Architecture

Content Hierarchy

Timeline (content directory)
└── Arc (story universe)
    └── Episode (story event)
        └── Chapter (individual .md file)

Arc Isolation

Each arc is treated as a separate narrative universe:

• Entities are scoped to arcs: bloom:CHARACTER:Alice ≠ work:CHARACTER:Alice
• Relations are internal to arcs
• Searches can be filtered by arc to avoid cross-arc contamination

Data Flow

┌─────────────────────────────────────────────────────────────┐
│                     INDEXING PHASE                          │
├─────────────────────────────────────────────────────────────┤
│  1. Scan content/*.md (filesystem scanner)                  │
│  2. Parse frontmatter + content (gray-matter)               │
│  3. For each chapter:                                       │
│     a. Extract entities/relations with Gemini API           │
│     b. Generate embeddings (Transformers.js ONNX)           │
│     c. Calculate word count and statistics                  │
│  4. Save everything to LanceDB                              │
└─────────────────────────────────────────────────────────────┘

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run typecheck

# Build
npm run build

Tech Stack

Purpose	Tool
Runtime	Node.js 20+
Language	TypeScript
Vector DB	LanceDB
Embeddings	@huggingface/transformers (ONNX)
Entity Extraction	Gemini AI
MCP SDK	@modelcontextprotocol/sdk
Testing	Vitest
Linting	Biome

Performance Notes

Embedding Quantization

The default embedding model (Xenova/e5-small-v2) supports different quantization levels via ECHOES_EMBEDDING_DTYPE:

Level	Speed	Quality	Memory	Recommendation
fp32	Baseline	Best (100%)	High	Production with ample resources
q8	2-3x faster	Excellent (99.6%)	50% less	Recommended - optimal balance
q4	3-4x faster	Good (99.1%)	75% less	Resource-constrained environments

Note: Some models like onnx-community/embeddinggemma-300m-ONNX don't support fp16. Always check model documentation.

Recommended setting:

export ECHOES_EMBEDDING_DTYPE=q8

License

MIT

---

Part of the Echoes project - a multi-POV digital storytelling platform.