📝 Scribe MCP Server

Enterprise-grade documentation governance for AI-powered development — by Corta Labs

Drop-in ready • 13+ specialized templates • Zero-config SQLite • Production-tested

✨ Update v2.1.1 (Diff Editor, Readable Output & ANSI Colors)

Scribe MCP 2.1.1 introduces foundational document lifecycle upgrades, including a fully automated YAML frontmatter engine with round-trip safety, canonical metadata defaults, and extensible schema support. Frontmatter is created on first edit if missing, auto-updates last_updated, and supports explicit overrides without breaking existing fields. These changes establish a metadata plane separate from document body content, enabling safe diff operations, deterministic header/TOC tooling, and template-driven document creation.

New: Enhanced Readable Output (Phase 1.5/1.6)

• ANSI Color Support: Tool output now renders with colors in Claude Code/Codex - cyan boxes, green line numbers, bold titles

• Green Line Numbers: Clean 1. content format with dot separator, matching Claude's native Read tool style

• CallToolResult Fix: Workaround for Issue #9962 - returns TextContent-only for proper newline rendering

• Config-Driven Colors: Enable/disable via use_ansi_colors: true in .scribe/config/scribe.yaml

• 5-Char Line Padding: Consistent line number width for improved readability

Structured edits are now the default path: agents express intent, the server compiles and applies deterministic mutations, and diagnostics remain explicit. Structural actions no longer auto-heal doc targets; if doc_name is not registered, the action fails with DOC_NOT_FOUND rather than redirecting the write.

• manage_docs now supports apply_patch and replace_range for precise edits.

• apply_patch auto-detects mode: unified when patch provided, structured when edit provided.

• patch_source_hash enforces stale-source protection for patches.

• Reminder system teaches scaffold-only replace_section, preferring structured/line edits.

• New doc lifecycle actions: normalize_headers, generate_toc, create, validate_crosslinks.

• create is the unified document creation action. Use metadata.doc_type to specify type: custom, research, bug, review, or agent_card. Content goes in metadata.body. Use metadata.register_doc=true to add the doc to the project registry.

• validate_crosslinks is read-only diagnostics (no write, no doc_updates log).

• normalize_headers supports ATX headers with or without space and Setext (==== / ----), skipping fenced code blocks. Output is canonical ATX.

• generate_toc uses GitHub-style anchors (NFKD normalization, ASCII folding, emoji removal, punctuation collapse, de-duped suffixes).

• Structural actions validate doc_name against the registry and fail hard on unknown docs (no silent redirects).

New:

The read_file tool is now a comprehensive code intelligence platform for Python and Markdown files, providing SWE agents with instant codebase understanding without reading full files:

Python Intelligence:

• Full Signature Extraction: Captures complete function/method signatures with type hints, default values, and return types

  • Example: async def fetch_project(self, name: str) -> Optional[ProjectRecord]

• Line Range Analysis: Shows start-end lines for every class, function, and method with line counts for complexity assessment

  • Example: async def _initialise(self) -> None (lines 645-1121 (477)) - instantly identifies a 477-line method needing refactoring

• Class Structure Display: Shows class hierarchy with first 10 methods by default, including async markers

• Structure Filtering: Regex-based search to find specific classes or functions

  • Example: structure_filter="validate" finds all validation functions with full signatures

• Structure Pagination: Browse large classes page-by-page (default: 10 items/page)

  • Navigate through a 62-method class: page 1 shows methods 1-10, page 2 shows 11-20, etc.

• Dependency Analysis: Static import analysis with resolved paths for local modules

Markdown Intelligence:

• Heading Extraction: Complete document outline with all heading levels and line numbers

• Quick Navigation: Jump directly to specific sections using extracted line numbers

Complete Workflow Example:

Key Benefits:

• Token Efficiency: Get complete structural overview without reading full file content

• Instant Complexity Assessment: Line counts reveal 477-line monsters needing refactoring

• Type-Aware Navigation: Full signatures show exactly how to call each function

• Regex Precision: Find all functions matching ^_validate.*|^_sanitize in seconds

• Pagination for Scale: Browse classes with 50+ methods without overwhelming output

Parameters: path, mode (scan_only/chunk/page/line_range/search), structure_filter, structure_page, structure_page_size, include_dependencies, format

• scribe_doctor reports repo root, config, plugin status, and vector readiness for faster diagnostics.

• manage_docs now supports semantic search via action="search" with search_mode="semantic", including doc/log separation and doc_k/log_k overrides.

• Vector indexing now prefers registry-managed docs only; log/rotated-log files are excluded from doc indexing.

• Reindex supports --rebuild (clear index), --safe (low-thread fallback), and --wait-for-drain to block until embeddings are written.

Example (structured mode with edit):

Example (unified diff mode - auto-detected when patch provided):

🚀 Why Scribe MCP?

Scribe transforms how AI agents and developers maintain project documentation. Instead of scattered notes and outdated docs, Scribe provides bulletproof audit trails, automated template generation, and cross-project intelligence that keeps your entire development ecosystem in sync.

Perfect for:

• 🤖 AI Agent Teams - Structured workflows and quality grading

• 🏢 Enterprise Teams - Audit trails and compliance documentation

• 👨‍💻 Solo Developers - Automatic documentation that actually works

• 📚 Research Projects - Structured logs and reproducible reports

Immediate Value:

• ✅ 30-second setup - Drop into any repository and start logging

• 🎯 18+ specialized templates - From architecture guides to bug reports

• 🔍 Cross-project search - Find patterns across your entire codebase

• 📊 Agent report cards - Performance grading for AI workflows

• 🛡️ Bulletproof storage - Atomic operations with crash recovery

⚡ Quick Start

Get Scribe running in under 60 seconds (MCP-first, CLI optional):

1️⃣ Install Dependencies

2️⃣ Add Scribe MCP Server to Claude Code, Codex

• Codex CLI registration example:

  codex mcp add scribe \ --env SCRIBE_STORAGE_BACKEND=sqlite \ -- bash -lc 'cd /home/path/to/scribe_mcp && exec python -m server'

• Claude Code registration example:

  claude mcp add scribe \ --env SCRIBE_STORAGE_BACKEND=sqlite \ -- bash -lc 'cd /home/path/to/scribe_mcp && exec python -m server'

  For Global MCP

  claude mcp add scribe --scope user --env SCRIBE_STORAGE_BACKEND=sqlite -- bash -lc 'cd /home/path/to/scribe_mcp && exec python -m server'

Once connected from Claude / Codex MCP:

• Use set_project to register/select a project and bootstrap dev_plan docs (pass root=/abs/path/to/repo to work in any repo).

• Use append_entry for all logging (single/bulk).

• Use manage_docs for architecture/phase/checklist updates. 2.1.1 introduces diff edits.

• Use read_file for safe, auditable file reads (scan/chunk/page/search).

• Use scribe_doctor for readiness checks (repo root, config, vector index status).

• Use read_recent to resume context after compaction.

Automatic log routing (BUG / SECURITY)

• status=bug (or a bug emoji) will also write to BUG_LOG.md when required meta is present (severity, component, status).

• Security events can also tee to SECURITY_LOG.md (example: use a security emoji, or --meta security_event=true,impact=...,status=...).

• If required meta is missing, Scribe returns a teaching reminder instead of inventing data.

3️⃣ (Optional) Manual CLI Logging

For shell workflows or quick one-off logs, you can call the MCP-aligned CLI:

Under the hood this uses set_project + append_entry, so manual usage stays in sync with the registry, SQLite mirror, and reminder system.

🎯 Try These Examples

Project Management:

Research Workflows:

Team Collaboration:

🛠️ Installation Options

Prerequisites

• Python 3.11+ - Modern Python with async support

• pip - Standard Python package manager

• Optional: PostgreSQL for team deployments (SQLite works out of the box)

Storage Backends

🗄️ SQLite (Default - Zero Config)

• Perfect for solo developers and small teams

• No setup required - just run and go

• Automatic database creation and management

🐘 PostgreSQL (Enterprise)

• Ideal for large teams and production deployments

• Set environment variables before starting:

  export SCRIBE_STORAGE_BACKEND=postgres export SCRIBE_DB_URL=postgresql://user:pass@host:port/database

MCP Integration

In all examples below, REPO_ROOT means the directory that contains the scribe_mcp package (i.e., where scribe_mcp/server.py lives). In your personal setup this might be .../MCP_SPINE, but in the public repo it will typically just be the cloned scribe_mcp directory.

For Claude Desktop (JSON config):

For Codex / Claude Code CLI:

Notes:

• We intentionally do not bake a per-repo root into the MCP config. Scribe is multi-repo: switch repos by calling set_project(name=..., root=/abs/path/to/repo) (no MCP re-register needed).

• The same bash -lc "cd REPO_ROOT && python -m scribe_mcp.server" pattern works for any MCP client that expects a stdio server command.

🌐 Using Scribe Outside This Repo

You can run Scribe from any codebase (not just MCP_SPINE) by pointing it at that project’s root:

1. Start the MCP server from the Scribe codebase (once), then use set_project(..., root=/abs/path/to/your/repo) to target any repository.

2. Optional env vars:

   • SCRIBE_STATE_PATH=/abs/path/to/state.json (per-user; must be writable)

   • SCRIBE_STORAGE_BACKEND=postgres and SCRIBE_DB_URL=postgresql://... if you want Postgres.

3. Ensure PYTHONPATH includes the parent of scribe_mcp so imports work when launched from elsewhere.

🧠 Project Registry & Lifecycle (High-Level)

Scribe includes a SQLite-backed Project Registry that tracks every project’s lifecycle and documentation state:

• Lifecycle states: planning, in_progress, blocked, complete, archived, abandoned.

• Core hooks:

  • set_project – bootstraps docs (ARCHITECTURE_GUIDE, PHASE_PLAN, CHECKLIST, PROGRESS_LOG) and ensures a registry row exists.

  • append_entry – writes progress logs, updates activity metrics, and can auto‑promote planning → in_progress once docs + first entry exist.

  • manage_docs – applies atomic doc updates and records baseline/current hashes and doc‑hygiene flags in the registry.

  • list_projects – surfaces registry data (status, timestamps, counts, tags, meta.activity, meta.docs.flags) with filters like status, tags, and order_by.

At a glance, you can:

• See which projects are fresh, stale, or long inactive.

• Detect when architecture/phase/checklist docs are still at template state.

• Spot drift between implementation logs and documentation.

For full technical details, see docs/whitepapers/scribe_mcp_whitepaper.md.

📜 License & Commercial Use

Scribe MCP is source-available and free to use for:

• Individual developers

• Open-source contributors

• Researchers and educational use

• Small teams and small businesses that:

  • Have fewer than 25 employees, and

  • Generate less than $1,000,000 USD in annual revenue, and

  • Are not selling, hosting, or packaging Scribe MCP (or derivatives) as part of a paid product or service.

You may not use Scribe MCP under the community license if:

• Your organization exceeds the employee or revenue limits above, or

• You embed Scribe MCP into a paid SaaS, internal platform, or commercial agent/orchestration product.

For enterprise or large-scale commercial use, contact licensing@cortalabs.com to obtain a commercial license.

Details:

• Current code is licensed under the Scribe MCP License (Community + Small Business License) in LICENSE.

• Earlier snapshots were MIT-licensed; see LICENSE_HISTORY.md for historical licensing context.

Notes:

• .env is auto-loaded on startup when present (via python-dotenv); shell exports/direnv still work the same.

• Overlap checks only block true path collisions (same progress_log/docs_dir). Sharing one repo root with many dev_plan folders is supported.

🎨 Template System Showcase

Scribe includes 13+ specialized templates that auto-generate professional documentation:

📋 Document Templates

• 📐 Architecture Guides - System design and technical blueprints

• 📅 Phase Plans - Development roadmaps with milestones

• ✅ Checklists - Verification ledgers with acceptance criteria

• 🔬 Research Reports - Structured investigation documentation

• 🐛 Bug Reports - Automated issue tracking with indexing

• 📊 Agent Report Cards - Performance grading and quality metrics

• 📝 Progress Logs - Append-only audit trails with UTC timestamps

• 🔒 Security Logs - Compliance and security event tracking

🚀 Template Features

• 🔒 Security Sandboxing - Jinja2 templates run in restricted environments

• 📝 Template Inheritance - Create custom template families

• 🎯 Smart Discovery - Project → Repository → Built-in template hierarchy (precedence: .scribe/templates → repo custom → project templates → packs → built-ins)

• ⚡ Atomic Generation - Bulletproof template creation with integrity verification

For a deeper dive into available variables and expected metadata per template, see docs/TEMPLATE_VARIABLES.md.

Example: Generate Architecture Guide

💻 CLI Power Tools

Scribe's command-line interface (386 lines of pure functionality) gives you complete control:

🎯 Core Commands

🎨 Rich Features

• 🎭 Emoji Support - Built-in emoji mapping for all status types

• 📊 Metadata Tracking - Rich key=value metadata for organization

• 🔍 Multiple Log Types - Progress, bugs, security, and custom logs

• 📅 Timestamp Control - Override timestamps for bulk imports

• 🎯 Project Discovery - Automatic project configuration detection

Status Types & Emojis

• info ℹ️ - General information and updates

• success ✅ - Completed tasks and achievements

• warn ⚠️ - Warning messages and cautions

• error ❌ - Errors and failures

• bug 🐞 - Bug reports and issues

• plan 📋 - Planning and roadmap entries

🔍 Enterprise Features

📊 Agent Report Cards

Performance grading infrastructure for AI workflows:

• Quality metrics tracking and trend analysis

• Performance levels with UPSERT operations

• Automated agent evaluation and reporting

🔒 Security & Compliance

• 🛡️ Security Sandboxing - Restricted Jinja2 environments with 22+ built-in controls

• 📋 Audit Trails - Complete change tracking with metadata

• 🔐 Access Control - Path validation and input sanitization

• 📊 Compliance Reporting - Structured logs for regulatory requirements

⚡ Advanced Search

Phase 4 Enhanced Search capabilities:

• 🔍 Cross-Project Validation - Find patterns across your entire codebase

• 📊 Relevance Scoring - 0.0-1.0 quality filtering

• 🎯 Code Reference Verification - Validate referenced code exists

• 📅 Temporal Filtering - Search by time ranges ("last_30d", "last_7d")

📝 Documentation Management

Structured doc editing with full schema exposure:

• 🔧 Complete MCP Schema - All manage_docs parameters properly exposed via JSON Schema

• 🎯 Type-Safe Operations - Proper parameter typing for reliable tool discovery and validation

• 📋 Action-Driven Interface - Atomic updates for architecture, phase plans, checklists, and research docs

manage_docs Quick Reference

7 Primary Actions:

Global Optional Params: project, dry_run, target_dir

doc_type Values (INSIDE metadata): custom (default), research, bug, review, agent_card

Create Examples:

Edit Examples:

For complete documentation, see docs/Scribe_Usage.md or the /scribe-mcp-usage skill.

💾 Bulletproof Storage

• 🗄️ Multi-Backend Support - SQLite (zero-config) + PostgreSQL (enterprise)

• ⚡ Atomic Operations - Temp-file-then-rename with fsync guarantees

• 🔄 Write-Ahead Logging - Bulletproof crash recovery with journaling

• ✅ Integrity Verification - Automatic corruption detection and recovery

🧠 Intelligent Reminders

Scribe keeps your documentation in sync with intelligent context awareness:

📋 Smart Reminders

Every MCP tool response includes contextual reminders about:

• 📅 Stale Documentation - When architecture docs need updates

• ⏰ Overdue Logs - Gentle nudges to maintain progress tracking

• 🎯 Project Context - Active project status and recent activity

• 🔄 Drift Detection - When implementation deviates from plans

Reminders are throttled with a short cooldown per (repo_root, agent_id) so you see what matters without constant repetition. If an agent gets confused, you can clear cooldowns with set_project(reset_reminders=true).

If you call a project-bound tool without selecting a project, Scribe returns a “last known project” hint (including last access time) to help you recover quickly.

⚙️ Customization

🌍 Environment Variables

• SCRIBE_REMINDER_IDLE_MINUTES - Work session reset timeout (default: 45)

• SCRIBE_REMINDER_WARMUP_MINUTES - Grace period after resuming (default: 5)

• SCRIBE_REMINDER_DEFAULTS - JSON configuration for all projects

• SCRIBE_REMINDER_CACHE_PATH - Optional path for reminder cooldown cache (default: data/reminder_cooldowns.json)

🏗️ Project Structure

Per-repo output location (dev plans + logs)

• Default: <repo>/.scribe/docs/dev_plans/<project_slug>/...

• Back-compat: if <repo>/docs/dev_plans/<project_slug> exists, Scribe keeps using it.

• Override: set SCRIBE_DEV_PLANS_BASE (example: docs/dev_plans) to force a different base.

🧪 Testing & Quality

Comprehensive testing infrastructure with 79+ test files:

🧪 Run Tests

✅ Quality Assurance

• 🔬 Functional Testing - 69 comprehensive tests covering all core functionality

• ⚡ Performance Testing - Optimized benchmarks for file operations

• 🛡️ Security Testing - Template sandboxing and access control validation

• 🔄 Integration Testing - MCP server protocol compliance verification

🚀 Smoke Test

💡 Real-World Use Cases

🤖 AI Agent Teams

Structured workflows for AI development:

🏢 Enterprise Documentation

Compliance and audit trails:

📚 Research Projects

Structured research documentation:

🔧 Troubleshooting

Common Issues & Solutions

🚨 MCP SDK Missing

🔧 No Tools Returned

🗄️ SQLite Permission Issues

🐍 Python Path Issues

⚡ Server Not Starting

Getting Help

• 📖 Documentation: Check docs/whitepapers/scribe_mcp_whitepaper.md for comprehensive technical details

• 🧪 Test Suite: Run pytest to verify system functionality

• 📋 Project Templates: Use --list-projects to see available configurations

• 🔍 Smoke Test: Run python scripts/test_mcp_server.py for MCP validation

🤝 Contributing

We welcome contributions! Here's how to get started:

🧪 Development Workflow

📋 Development Guidelines

• ✅ Test Coverage: All new features must include tests

• 📝 Documentation: Update relevant documentation sections

• 🔧 Integration: Ensure MCP server compatibility

• 🛡️ Security: Follow security best practices for templates and inputs

🚀 Quality Standards

• 🧪 69+ functional tests must pass

• ⚡ Performance benchmarks for file operations

• 🔒 Security validation for template sandboxing

• 📋 MCP protocol compliance verification

📚 Further Reading

📖 Technical Documentation

• 📄 Whitepaper v2.1 - Comprehensive technical architecture

• 🔧 API Reference - Complete MCP tool documentation

• 🎨 Template Guide - Custom template development

• 🏗️ Architecture Patterns - System design and integration

🌟 Advanced Features

• 🤖 Claude Code Integration - Structured workflows and subagent coordination

• 📊 Agent Report Cards - Performance grading and quality metrics

• 🔍 Vector Search - FAISS integration for semantic search

• 🔐 Security Framework - Comprehensive access control and audit trails

🚀 Production Deployment

• 🐘 PostgreSQL Setup - Enterprise-scale deployment guide

• 📈 Monitoring - Performance tracking and alerting

• 🔄 Backup & Recovery - Data protection strategies

• 🌐 Multi-tenant - Organizational deployment patterns

🙏 Acknowledgments

Built with passion for better documentation and AI-human collaboration. Special thanks to:

• The MCP protocol team for the standardized AI tool interface

• Jinja2 for the powerful and secure templating system

• Our early adopters for invaluable feedback and feature suggestions

🚀 Ready to transform your documentation?

Start Logging • Explore Templates • Read Whitepaper

Join thousands of developers and AI teams using Scribe for bulletproof documentation governance