📝 Scribe MCP Server

Tests Version License

Enterprise-grade documentation governance for AI-powered development

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

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

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 16 production-ready dependencies pip install -r requirements.txt

2️⃣ Start Logging Immediately

# From the parent directory (MCP_SPINE/) python -m scribe_mcp.scripts.scribe "🚀 My project is ready!" --status success --emoji 🎉

That's it! You've just created your first structured log entry. Scribe automatically:

✅ Created a project configuration
✅ Generated documentation templates
✅ Started your progress log
✅ Provided intelligent reminders

3️⃣ Launch MCP Server (Optional)

# Start the MCP server for Claude/Claude Code integration export SCRIBE_ROOT=$(pwd) # Set your project root python -m scribe_mcp.server

🎯 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

For Claude Desktop:

{ "mcpServers": { "scribe": { "command": "python", "args": ["/absolute/path/to/scribe_mcp/server.py"], "env": { "SCRIBE_ROOT": "/absolute/path/to/scribe_mcp", "SCRIBE_STORAGE_BACKEND": "sqlite" } } } }

For Claude Code CLI:

codex mcp add scribe \ --env SCRIBE_ROOT=/path/to/scribe_mcp \ --env SCRIBE_STORAGE_BACKEND=sqlite \ -- python -m scribe_mcp.server

🎨 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
⚡ Atomic Generation - Bulletproof template creation with integrity verification

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")

💾 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

⚙️ 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

🏗️ Project Structure

scribe_mcp/ # 🏛️ Main Scribe MCP server ├── 📁 config/ │ ├── 📁 projects/ # Per-project configurations │ └── 📄 mcp_config.json # Sample MCP configuration ├── 📁 docs/dev_plans/ # Auto-generated documentation │ ├── 📄 ARCHITECTURE_GUIDE.md │ ├── 📄 PHASE_PLAN.md │ ├── 📄 CHECKLIST.md │ └── 📄 PROGRESS_LOG.md ├── 📁 templates/ # 🎨 Jinja2 template system │ ├── 📁 documents/ # 13+ specialized templates │ ├── 📁 fragments/ # Reusable template pieces │ └── 📁 custom/ # Your custom templates ├── 📁 tools/ # 🔧 MCP tool implementations ├── 📁 storage/ # 💾 Multi-backend storage layer ├── 📁 scripts/ # 💻 CLI utilities ├── 📁 tests/ # 🧪 Comprehensive test suite └── 📄 server.py # 🚀 MCP server entrypoint

🧪 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 SCRIBE_ROOT is writable ls -la $SCRIBE_ROOT # Set proper permissions if needed chmod 755 $SCRIBE_ROOT

🐍 Python Path Issues

# Ensure you're running from the correct directory # Run from MCP_SPINE parent directory, not inside scribe_mcp/ pwd # Should show .../MCP_SPINE/ # Test import path python -c "import sys; sys.path.insert(0, '.'); from scribe_mcp.config.settings import settings; print('✅ Imports working')"

⚡ Server Not Starting

# Check required dependencies pip install -r requirements.txt # Verify server startup with timeout timeout 5 python -m scribe_mcp.server || echo "✅ Server starts correctly"

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

🌟 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

📄 License

MIT License - see LICENSE file 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