scribe-mcp 2.2

Scribe MCP server, tooling, and universal CLI

📝 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.2 (Architecture Cleanup)

Scribe MCP v2.2 delivers major architectural improvements:

Performance:

• Connection Pooling: New storage/pool.py with SQLiteConnectionPool delivers 50-80% latency reduction
• Optimized Indexes: New composite indexes for agent/emoji filtering

Code Quality:

• ResponseFormatter Decomposition: Monolithic 2,934-line class split into 7 specialized modules in utils/formatters/
• Database-First State: Session state migrated from state.json to database

Data Management:

• Retention Policy: New scribe_entries_archive table with configurable cleanup (default 90 days)
• Agent Isolation: All tools require agent parameter for session isolation

---

History: 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: read_file - Complete Code Intelligence System (Phase 5)

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:

# Step 1: Find the class (scan_only mode - zero content, pure metadata)
read_file(path="storage/sqlite.py", mode="scan_only", structure_filter="SQLiteStorage")
# → Shows: class SQLiteStorage at lines 32-2334 (2303 lines)
#          Methods (page 1 of 7, showing 1-10 of 62)

# Step 2: Browse methods with pagination
read_file(path="storage/sqlite.py", mode="scan_only",
          structure_filter="SQLiteStorage", structure_page=2)
# → Methods 11-20 with full signatures and line ranges
#   Found: async def fetch_recent_entries(self) -> List[Dict[str, Any]] (lines 338-427 (90))

# Step 3: Read exact method implementation
read_file(path="storage/sqlite.py", mode="line_range", start_line=338, end_line=427)
# → Full method code for analysis

# Step 4: Edit with confidence
Edit(file_path="storage/sqlite.py", old_string="...", new_string="...")

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

New: search - Multi-File Codebase Search (v2.2)

The search tool provides grep/ripgrep-equivalent codebase search directly through MCP, with repo-boundary enforcement and audit logging:

• Regex and Literal Patterns: Full regex by default, with regex=False for literal string matching
• File Filtering: Filter by glob pattern (glob="*.py") or file type (type="py")
• Three Output Modes: content (matching lines with context), files_with_matches (file paths only), count (match counts per file)
• Context Control: Configurable before/after context lines around matches
• Multiline Matching: Patterns can span multiple lines with multiline=True
• Safety Limits: Configurable max matches per file (50), total matches (200), max files (100), and file size cap (10MB)

# Find all async methods in Python files
search(agent="CoderAgent", pattern="async def ", type="py", output_mode="content", context_lines=2)

# Count occurrences of a function across the codebase
search(agent="CoderAgent", pattern="append_entry", output_mode="count")

# Search with glob filter
search(agent="CoderAgent", pattern="class.*Storage", glob="storage/*.py", output_mode="files_with_matches")

Parameters: agent, pattern, path, glob, type, output_mode, format, context_lines, before_context, after_context, case_insensitive, regex, multiline, max_matches_per_file, max_total_matches, max_files, line_numbers, skip_binary, max_file_size_mb

New: edit_file - Safe File Editing with Audit Trail (v2.2)

The edit_file tool provides exact string replacement with built-in safety mechanisms:

• Read-Before-Edit Enforcement: The file MUST have been read with read_file in the current session before editing (tool-enforced)
• Dry-Run by Default: dry_run=True is the default -- you must explicitly set dry_run=False to commit changes
• Exact String Matching: Finds and replaces exact strings (no regex), failing clearly if the target string is not found or is ambiguous
• Replace All Mode: Optional replace_all=True for renaming variables or updating repeated patterns
• Diff Preview: Dry-run mode returns a unified diff preview before committing
• Repo-Boundary Enforcement: Cannot edit files outside the repository root

# Preview a change (dry_run=True is default)
edit_file(agent="CoderAgent", path="config/settings.py", old_string="DEBUG = True", new_string="DEBUG = False")

# Commit a change
edit_file(agent="CoderAgent", path="config/settings.py", old_string="DEBUG = True", new_string="DEBUG = False", dry_run=False)

# Rename across file
edit_file(agent="CoderAgent", path="utils/helpers.py", old_string="old_name", new_string="new_name", replace_all=True, dry_run=False)

Parameters: agent, path, old_string, new_string, replace_all (default: False), dry_run (default: True), 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):

{
  "action": "apply_patch",
  "doc_name": "architecture",
  "edit": {
    "type": "replace_range",
    "start_line": 12,
    "end_line": 12,
    "content": "Updated line\n"
  }
}

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

{
  "action": "apply_patch",
  "doc_name": "architecture",
  "patch": "<compiler output>"
}

🚀 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

# Clone and navigate to Scribe
git clone <your-repo-url>
cd scribe_mcp

# Set up Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install Scribe (editable + dev extras)
python -m pip install -e ".[dev]"

# Optional: verify wheel/non-editable install path too
python -m pip install .

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 scribe-server'
  

• Claude Code registration example:

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

• Global Claude MCP example:

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

Compatibility note: legacy launch python -m server still works during migration.

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 / list_projects 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 Tool Calls

For shell workflows or CI checks, use the unified CLI runtime:

# List all registered MCP tools
python -m scribe_mcp.cli.main tools --json

# Call any tool directly (example: append_entry)
python -m scribe_mcp.cli.main call append_entry \
  --agent Codex \
  --arg message="Scribe CLI call works" \
  --arg status=success

This path uses the same runtime dispatcher as MCP (invoke_tool), so mode/session guard behavior stays aligned.

---

🎯 Try These Examples

Project Management:

# Log project milestones
python -m scribe_mcp.scripts.scribe "Completed authentication module" --status success --meta component=auth,tests=47

# Track bugs and issues
python -m scribe_mcp.scripts.scribe "Fixed JWT token expiry bug" --status bug --meta severity=high,component=security

Research Workflows:

# Document research findings
python -m scribe_mcp.scripts.scribe "Discovered performance bottleneck in database queries" --status info --meta research=true,impact=high

Team Collaboration:

# List all projects
python -m scribe_mcp.scripts.scribe --list-projects

# Switch between projects
python -m scribe_mcp.scripts.scribe "Starting new feature work" --project frontend --status plan

---

🛠️ 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 pyproject.toml for this project (the repo root). The runtime package lives under src/scribe_mcp/.

For Claude Desktop (JSON config):

{
  "mcpServers": {
    "scribe": {
      // Run from REPO_ROOT so `scribe_mcp` imports resolve
      "command": "bash",
      "args": [
        "-lc",
        "cd /absolute/path/to/REPO_ROOT && exec scribe-server"
      ],
      "env": {
        // Optional: override storage backend; SQLite is default
        "SCRIBE_STORAGE_BACKEND": "sqlite"
      }
    }
  }
}

For Codex / Claude Code CLI:

# From anywhere; codex will remember this configuration
codex mcp add scribe \
  --env SCRIBE_STORAGE_BACKEND=sqlite \
  -- bash -lc 'cd /absolute/path/to/REPO_ROOT && exec scribe-server'

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 && scribe-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 (DEPRECATED in v2.2 - sessions now stored in database)
   • SCRIBE_STORAGE_BACKEND=postgres and SCRIBE_DB_URL=postgresql://... if you want Postgres.
3. Prefer launching via installed entry points (scribe-server, scribe) so no manual PYTHONPATH wiring is required.

---

🧠 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 [e-mail] 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

# Auto-generate a complete architecture document
python -m scribe_mcp.scripts.scribe "Generated architecture guide for new project" --status success --meta template=architecture,auto_generated=true

---

💻 CLI Power Tools

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

🎯 Core Commands

# List all available projects
python -m scribe_mcp.scripts.scribe --list-projects

# Log with rich metadata
python -m scribe_mcp.scripts.scribe "Fixed critical bug" \
  --status success \
  --emoji 🔧 \
  --meta component=auth,tests=12,severity=high

# Dry run to preview entries
python -m scribe_mcp.scripts.scribe "Test message" --dry-run

# Switch between projects
python -m scribe_mcp.scripts.scribe "Starting frontend work" \
  --project mobile_app \
  --status plan

🎨 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:

Action	Purpose	Required Params
create	Create new doc (research/bug/custom)	doc_name, metadata.doc_type
replace_section	Replace content by section anchor	doc_name, section, content
apply_patch	Apply unified diff patch	doc_name, patch
replace_range	Replace explicit line range	doc_name, start_line, end_line, content
replace_text	Find/replace text pattern	doc_name, metadata.find, metadata.replace
append	Append content to doc/section	doc_name, content
status_update	Update checklist item status	doc_name, section, metadata

Global Optional Params: project, dry_run, target_dir

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

Create Examples:

# Research doc
manage_docs(
    action="create",
    doc_name="RESEARCH_AUTH_20260119",
    metadata={"doc_type": "research", "research_goal": "Analyze auth flow"}
)

# Bug report (doc_name auto-generated)
manage_docs(
    action="create",
    metadata={
        "doc_type": "bug",
        "category": "logic",
        "slug": "auth_leak",
        "severity": "high",
        "title": "Auth token not invalidated"
    }
)

# Custom doc
manage_docs(
    action="create",
    doc_name="COORDINATION_PROTOCOL",
    metadata={"doc_type": "custom", "body": "# Protocol\n\nContent..."}
)

Edit Examples:

# Replace section
manage_docs(
    action="replace_section",
    doc_name="architecture",
    section="problem_statement",
    content="## Problem Statement\nNew content here..."
)

# Apply unified diff patch (context-aware matching)
manage_docs(
    action="apply_patch",
    doc_name="architecture",
    patch="--- a/file.md\n+++ b/file.md\n@@ -10,3 +10,3 @@\n-old line\n+new line\n context"
)

# Update checklist status
manage_docs(
    action="status_update",
    doc_name="checklist",
    section="phase_1_task_1",
    metadata={"status": "done", "proof": "PR #123 merged"}
)

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

{
  "name": "my_project",
  "defaults": {
    "reminder": {
      "tone": "friendly",
      "log_warning_minutes": 15,
      "log_urgent_minutes": 30,
      "severity_weights": {"warning": 7, "urgent": 10}
    }
  }
}

🌍 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

scribe_mcp/
├── pyproject.toml             # Packaging + console scripts (scribe, scribe-server)
├── src/
│   └── scribe_mcp/
│       ├── server.py          # MCP server runtime
│       ├── __main__.py        # Entry point for scribe-server / scribe-mcp
│       ├── cli/               # Unified CLI (tools/call/session)
│       ├── config/            # Path + runtime configuration
│       ├── tools/             # MCP tool implementations
│       ├── storage/           # SQLite/Postgres backends
│       ├── plugins/           # Vector indexer and plugin registry
│       ├── template_engine/   # Jinja document template engine
│       ├── doc_management/    # manage_docs action pipeline
│       └── templates/         # Built-in templates (documents/fragments)
├── tests/                     # Repo-root test suite (installed-package flow)
├── docs/                      # Curated project docs
└── README.md

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

# Run all functional tests (69 tests)
pytest

# Run performance tests with file size benchmarks
pytest -m performance

# Run specific test categories
pytest tests/test_tools.py
pytest tests/test_storage.py

✅ 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

# Quick MCP server validation
python scripts/test_mcp_server.py

---

💡 Real-World Use Cases

🤖 AI Agent Teams

Structured workflows for AI development:

# Research phase
python -m scribe_mcp.scripts.scribe "Research completed: authentication patterns" --status info --meta phase=research,confidence=0.9

# Architecture phase
python -m scribe_mcp.scripts.scribe "Architecture guide updated with auth design" --status success --meta phase=architecture,sections=5

# Implementation phase
python -m scribe_mcp.scripts.scribe "JWT authentication implemented" --status success --meta phase=implementation,tests=47,coverage=95%

🏢 Enterprise Documentation

Compliance and audit trails:

# Security events
python -m scribe_mcp.scripts.scribe "Security audit completed - all controls verified" --log security --status success --meta auditor=external,findings=0

# Change management
python -m scribe_mcp.scripts.scribe "Production deployment completed" --status success --meta version=v2.1.0,rollback_available=true

📚 Research Projects

Structured research documentation:

# Research findings
python -m scribe_mcp.scripts.scribe "Performance bottleneck identified in database queries" --status info --meta research=true,impact=high,evidence=query_analysis

# Experiment results
python -m scribe_mcp.scripts.scribe "A/B test results: new algorithm 23% faster" --status success --meta experiment=performance_optimization,improvement=23%

---

🔧 Troubleshooting

Common Issues & Solutions

🚨 MCP SDK Missing

# Install the MCP Python SDK
pip install mcp

🔧 No Tools Returned

# Ensure all modules are properly imported
# Check that your virtual environment is active
source .venv/bin/activate

# Verify tool imports
python -c "from scribe_mcp.tools import *; print('All tools loaded')"

🗄️ SQLite Permission Issues

# Check your state/db paths are writable
echo $SCRIBE_STATE_PATH
ls -la $(dirname "$SCRIBE_STATE_PATH")

# Check the target repo is writable (Scribe writes under <repo>/.scribe/ by default)
ls -la /abs/path/to/your/repo
ls -la /abs/path/to/your/repo/.scribe || true

🐍 Python Path / Packaging Issues

# Verify package import and resolved src-root path
python -c "import scribe_mcp; from scribe_mcp.config.paths import package_root; print(package_root())"

# Verify console-script entry points
scribe --help
scribe-server --help

🤖 BertModel / torchvision mismatch warning

If startup logs show Could not import module 'BertModel', your torch and torchvision builds are likely mismatched (common CUDA tag mismatch).

python - <<'PY'
import torch
print('torch:', torch.__version__)
try:
    import torchvision
    print('torchvision:', torchvision.__version__)
except Exception as exc:
    print('torchvision import failed:', exc)
PY

Scribe now guards this case by disabling broken torchvision integration for transformers so text embeddings can still initialize. For a full env-level fix, install matching torch/torchvision builds (same CUDA tag), or remove torchvision if your workload is text-only.

⚡ Server Not Starting

# Ensure package + dev deps are installed
python -m pip install -e ".[dev]"

# Verify server startup
python -m server --help

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

# 1. Run the test suite
pytest

# 2. Verify MCP server functionality
python scripts/test_mcp_server.py

# 3. Test your changes
python -m scribe_mcp.scripts.scribe "Testing new feature" --dry-run

# 4. Log your contribution
python -m scribe_mcp.scripts.scribe "Added new feature: description" --status success --meta contribution=true,feature_type=enhancement

📋 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

🔒 Hooks & Enforcement

• Hooks Setup Guide - Protect managed docs from direct Write/Edit with Claude Code hooks
• Scribe Onboarding Prompt - Full instructional prompt for onboarding any project to Scribe MCP (protocol, tools, manage_docs, hooks)

🌟 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

---

⚠️ Known Limitations

Concurrent Agent Session Collision

MCP Transport Limitation: Session identity is {repo_root}:{transport}:{agent_name}. When multiple agents with the same name work on different Scribe projects within the same repository concurrently, their sessions collide.

Best Practice: Use scoped agent names for concurrent work:

# ❌ Same name = collision
agent="CoderAgent"  # on project_x
agent="CoderAgent"  # on project_y → logs may go to wrong project!

# ✅ Scoped names = safe
agent="CoderAgent-ProjectX"
agent="CoderAgent-ProjectY"

Not affected: Sequential dispatches, different repositories, or single agent switching projects.

See Scribe_Usage.md for details.

---

🙏 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