echoes-io/mcp-server

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
• Semantic Search: Find relevant chapters using natural language queries
• Entity Search: Search for characters, locations, and events
• Relation Search: Explore relationships between entities
• Statistics: Aggregate word counts, POV distribution, and more

Requirements

• Python 3.11-3.13 (3.14 not yet supported by spaCy)
• ~2GB disk space for models (spaCy Italian + embeddings)

Installation

pip install echoes-mcp-server

Or with uv (recommended):

uv add echoes-mcp-server

The Italian spaCy model (it_core_news_lg) is downloaded automatically on first use.

Usage

CLI

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

# Index timeline content
echoes index ./content

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

# Search
echoes search "Alice meets Bob"
echoes search "Alice" --type entities

MCP Server

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

{
  "mcpServers": {
    "echoes": {
      "command": "echoes-mcp-server",
      "cwd": "/path/to/timeline"
    }
  }
}

Or with uvx (no installation required):

{
  "mcpServers": {
    "echoes": {
      "command": "uvx",
      "args": ["echoes-mcp-server"],
      "cwd": "/path/to/timeline"
    }
  }
}

Available Tools

Development

Setup

# Clone the repository
git clone https://github.com/echoes-io/mcp-server.git
cd mcp-server

# Install uv if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv with Python 3.13 (required for spaCy compatibility)
uv venv --python 3.13

# Install dependencies
uv sync --all-extras

# The spaCy model downloads automatically on first use, or install manually:
uv pip install https://github.com/explosion/spacy-models/releases/download/it_core_news_lg-3.8.0/it_core_news_lg-3.8.0-py3-none-any.whl

Commands

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Type check
uv run mypy src/

Demo

Test with real timeline content:

# Create symlinks to timeline repos (adjust paths as needed)
cd demo
ln -s ../../timeline-anima/content anima
ln -s ../../timeline-eros/content eros

# Run demo
uv run python demo/run_demo.py

Example output:

============================================================
📚 Timeline: ANIMA
============================================================
📖 Chapters found: 55
📝 Total words: 199,519
📁 Arcs: ['anima', 'matilde']
👤 POVs: ['nic']

============================================================
📚 Timeline: EROS
============================================================
📖 Chapters found: 465
📝 Total words: 733,034
📁 Arcs: ['ale', 'ele', 'gio', 'ro', 'work']
👤 POVs: ['Ele', 'Nic', 'ale', 'angi', 'gio', 'nic', 'ro', 'vi']

============================================================
🔍 NER Demo (Named Entity Recognition)
============================================================
📄 Sample: anima/ep01/ch001
🏷️  Entities found: 33
   LOC: Malpensa, Terminal 2
   ORG: LinkedIn, Ryanair
   PER: GioGio, Cristo

Project Structure

src/echoes_mcp/
├── __init__.py          # Package version
├── cli.py               # CLI interface (click)
├── server.py            # MCP server
├── database/
│   ├── lancedb.py       # LanceDB operations
│   └── schemas.py       # Pydantic schemas
├── indexer/
│   ├── scanner.py       # Filesystem scanner
│   ├── extractor.py     # Entity extraction (LlamaIndex)
│   ├── embeddings.py    # Embedding models
│   └── spacy_utils.py   # spaCy with auto-download
└── tools/
    ├── words_count.py   # Word counting
    ├── stats.py         # Statistics
    ├── search.py        # Search operations
    └── index.py         # Indexing tool

demo/
├── run_demo.py          # Demo script
├── anima -> ...         # Symlink to timeline-anima/content
└── eros -> ...          # Symlink to timeline-eros/content

Tech Stack

Node.js Comparison

If you're coming from Node.js:

License

MIT

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