story-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Document MCP
Document MCP gives writers, researchers, and knowledge-managers first-class control over large-scale Markdown documents with built-in safety features that prevent content loss. Manage books, research papers, and documentation with 37 AI-powered tools including context management, git-backed version history, and semantic search.
Phase 4 Complete ā - v0.0.5 Production Ready (February 26, 2026)
š Quick Start
Option 1: Hosted Service (Recommended)
For Claude Desktop users - No installation required. Just add to your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"document-mcp": {
"url": "https://story-mcp-451560119112.asia-east1.run.app"
}
}
}Restart Claude Desktop. When you first connect:
Your browser opens for Google OAuth authentication
Sign in with your Google account
Claude Desktop securely stores your access token
Start managing documents immediately!
What you get:
37 MCP tools for document management
Your own isolated document storage
Automatic snapshots and git-backed version history
Cross-session context management
Semantic search with embeddings
No setup, no API keys, no maintenance
Option 2: Local Installation (For Claude Code / Developers)
For Claude Code users or those who want local document storage:
pip install story-mcpAdd to your Claude Code MCP settings:
{
"mcpServers": {
"document-mcp": {
"command": "python",
"args": ["-m", "story_mcp.doc_tool_server", "stdio"]
}
}
}See the Package Installation Guide for detailed setup with universal path finding.
Related MCP server: Librarian MCP
š What is Document MCP?
Document MCP provides a structured way to manage large stories and documents composed of multiple chapters. Think of it as a file system specifically designed for novels, screenplays, research papers, documentation, or any content that benefits from being split into manageable sections.
Key Features
37 MCP Tools (Phase 4 Complete ā ):
Story management, chapter operations, paragraph editing
Semantic search with embeddings
Git-backed version history
Cross-session context management (OneContext-inspired)
Entity tracking, metadata, and safety features
Built-in Safety: Git-backed version control, automatic commits, snapshots, and conflict detection
Pagination System: Page-based content access for large documents (50K chars per page)
User Isolation: Each authenticated user gets their own isolated storage (hosted version)
Local-First Option: Keep your stories on your own machine (PyPI version)
Document Organization
.documents_storage/
āāā my_novel/ # A story/document
ā āāā 01-prologue.md # Chapters ordered by filename
ā āāā 02-chapter-one.md
ā āāā 03-chapter-two.md
āāā research_paper/ # Another document
āāā 00-abstract.md
āāā 01-introduction.md
āāā 02-methodology.mdš”ļø Safety Features
Document MCP includes safety features designed to prevent content loss:
Automatic Snapshots: Created before every destructive operation
Named Checkpoints: Create restore points with
snapshot_documentVersion Restoration: Roll back to any previous version with
restore_snapshotConflict Detection: Warns about potential overwrites from external modifications
Audit Trail: Complete modification history with timestamps
š Hosted Service Details
The hosted version runs on Google Cloud Run:
Feature | Details |
Authentication | OAuth 2.1 with PKCE via Google |
Region | asia-east1 (Taiwan) |
Scaling | Auto-scales 0-10 instances based on load |
Cost | Free for users (scales to zero when idle) |
š§ Tool Categories
Document MCP provides 37 tools organized into 10 categories:
Category | Tools | Description |
Document | 6 | Create, delete, list documents; manage summaries |
Chapter | 4 | Add, edit, delete, list chapters with frontmatter |
Paragraph | 4 | Atomic paragraph operations (insert, replace, delete, move) |
Content | 6 | Read, search, replace, statistics, semantic search, entity tracking |
Metadata | 3 | Chapter frontmatter, entities, timeline management |
Safety | 3 | Git history, restore, diff comparison |
Overview | 1 | Document outline with metadata |
Discovery | 1 | Tool search and discovery |
Context | 6 | Store/recall memories, export/import, list memories |
Version | 3 | Get history, checkout version, compare versions |
Discovery | 1 | Tool search and discovery |
š¤ Example Workflows
Basic Document Management
š¤ User: Create a new document called 'My Novel'
š¤ Claude: ā
Created document 'My Novel'
š¤ User: Add a chapter called '01-introduction.md' with content '# Chapter 1\n\nIt was a dark and stormy night...'
š¤ Claude: ā
Created chapter '01-introduction.md' in 'My Novel'
š¤ User: List all my documents
š¤ Claude: ā
Found 1 document: 'My Novel' with 1 chapterSafety Features in Action
š¤ User: Delete paragraph 3 from chapter '02-climax.md' in 'My Novel'
š¤ Claude: ā
Deleted paragraph 3. Automatic snapshot created for recovery.
š¤ User: Actually, restore the last snapshot
š¤ Claude: ā
Restored from snapshot. Paragraph 3 is back.Semantic Search
š¤ User: Find content similar to "the hero's journey" in my novel
š¤ Claude: ā
Found 3 paragraphs with similar themes:
- Chapter 2, paragraph 5 (similarity: 0.89)
- Chapter 4, paragraph 12 (similarity: 0.82)
- Chapter 1, paragraph 3 (similarity: 0.78)š ļø Development
Prerequisites
Python 3.10+
Git
Local Development Setup
# Clone the repository
git clone https://github.com/clchinkc/document-mcp.git
cd document-mcp
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e ".[dev]"Running Tests
# All tests (528 tests)
uv run pytest
# By tier
uv run pytest tests/unit/ # Fast, isolated tests
uv run pytest tests/integration/ # Real MCP, mocked LLM
uv run pytest tests/e2e/ # Full system (requires API keys)
# Code quality
uv run ruff check --fix && uv run ruff format
uv run mypy document_mcp/Running the MCP Server Locally
# Start MCP server
uv run python -m document_mcp.doc_tool_server stdio
# Or with PyPI installation
story-mcp stdioš Documentation
Guide | Description |
PyPI setup for Claude Code | |
Creative writing workflows | |
Production patterns and best practices | |
4-tier testing architecture |
š¤ Contributing
Contributions welcome! Please run the test suite before submitting PRs:
uv run pytest && uv run ruff check && uv run mypy document_mcp/š License
MIT License - see LICENSE for details.
š Acknowledgments
Built with Model Context Protocol (MCP)
Powered by Pydantic AI
Hosted on Google Cloud Run
ā Star this repo if you find it useful!
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
AI research library. Save, organise and reuse notes and webpages as clean markdown context.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables personal project documentation management through local markdown files stored in nested directories. Supports organizing context by project and layer (backend/frontend/fullstack) with search functionality across all documentation files.4MIT
- AlicenseNot gradedqualityAmaintenanceTransforms a folder of Markdown files into a structured, version-controlled knowledge base with semantic search and safe AI editing via draft branches.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to store and retrieve project-aware context as plain Markdown files locally, with no cloud or vector database required.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients like Claude, ChatGPT, and Cursor to search, read, and write back to one cross-model Markdown library of saved articles, videos, PDFs, notes, and conversations. Hosted remote server with OAuth 2.1 or Agent-key auth and read_only, edit, or full permission tiers.MIT