Offers integration with Git through pre-commit hooks for documentation validation and version control friendly organization
Trapper Keeper MCP
Keep your AI context organized like a boss 📚✨
An intelligent document extraction and organization system built as a Model Context Protocol (MCP) server using Python and FastMCP. Trapper Keeper watches directories for markdown and text files, extracts categorized content, and organizes it into structured outputs.
🏗️ Architecture
Trapper Keeper MCP is designed with a modular, event-driven architecture that supports both CLI and MCP server modes:
Key Components
- Core: Base classes, type definitions, and configuration management
- Monitoring: File system monitoring with debouncing and pattern matching
- Parser: Extensible document parsing (currently supports Markdown)
- Extractor: Intelligent content extraction with category detection
- Organizer: Flexible output organization and formatting
- MCP Server: FastMCP-based server implementation
- CLI: Rich command-line interface
✅ Features
Intelligent Content Extraction
- Category Detection: Automatically categorizes content using pattern matching and keywords
- Importance Scoring: Assigns importance scores based on content relevance
- Section Parsing: Preserves document structure with hierarchical sections
- Code Block Extraction: Extracts and categorizes code snippets
- Link Extraction: Groups and organizes document links
Real-time File Monitoring
- Directory Watching: Monitors directories for file changes
- Pattern Matching: Configurable file patterns and ignore rules
- Debouncing: Prevents duplicate processing of rapid changes
- Event System: Async event-driven architecture for scalability
Flexible Organization
- Multiple Output Formats: Markdown, JSON, and YAML
- Grouping Options: By category, document, or custom grouping
- Index Generation: Automatic index creation with statistics
- Metadata Preservation: Maintains source information and timestamps
📋 Setup
Prerequisites
- Python 3.8 or higher
- pip or poetry for dependency management
Installation
- Clone the repository:
- Install dependencies:
- Copy the example configuration:
- Edit
config.yaml
to match your needs
MCP Integration
Add to your MCP settings:
🌐 API
CLI Commands
Category Configuration
The system uses emoji-prefixed categories for easy identification:
- 🏗️ Architecture - System design and structure
- 🗄️ Database - Database schemas and queries
- 🔐 Security - Authentication and security concerns
- ✅ Features - Feature descriptions and requirements
- 📊 Monitoring - Logging and observability
- 🚨 Critical - Urgent issues and blockers
- 📋 Setup - Installation and configuration
- 🌐 API - API endpoints and integrations
- 🧪 Testing - Test cases and strategies
- ⚡ Performance - Optimization and speed
- 📚 Documentation - Guides and references
- 🚀 Deployment - Deployment and CI/CD
- ⚙️ Configuration - Settings and options
- 📦 Dependencies - Package management
MCP Tools Available
The MCP server exposes the following tools:
process_file
Process a single file and extract categorized content.
process_directory
Process all matching files in a directory.
watch_directory
Start watching a directory for changes.
stop_watching
Stop watching a specific directory.
list_watched_directories
Get information about all watched directories.
get_categories
Get list of available extraction categories.
update_config
Update server configuration at runtime.
📊 Monitoring
Trapper Keeper includes Prometheus metrics for monitoring:
- Files processed (success/failure counts)
- Event publications by type
- Content extraction by category
- Processing duration histograms
- Queue sizes and active watchers
Metrics are exposed on port 9090 by default.
🚨 Critical Configuration
Environment Variables
TRAPPER_KEEPER_LOG_LEVEL
: Logging level (DEBUG, INFO, WARNING, ERROR)TRAPPER_KEEPER_METRICS_PORT
: Prometheus metrics portTRAPPER_KEEPER_MCP_PORT
: MCP server portTRAPPER_KEEPER_OUTPUT_DIR
: Default output directoryTRAPPER_KEEPER_MAX_CONCURRENT
: Maximum concurrent file processing
🔐 Security
- File access is restricted to configured paths
- No remote code execution
- Configurable ignore patterns for sensitive files
- All file operations are read-only by default
Development
Project Structure
Adding a New Parser
- Create a new parser class inheriting from
Parser
- Implement required methods:
parse()
,can_parse()
- Register in
parser_factory.py
Adding a New Category
- Add to
ExtractionCategory
enum intypes.py
- Add detection patterns in
category_detector.py
Plugin System
The architecture supports plugins through the Plugin
protocol. Plugins can:
- Process documents
- Add new extraction categories
- Implement custom output formats
Why "Trapper Keeper"?
Named after the iconic 90s school organizer, Trapper Keeper MCP does for your code documentation what those colorful binders did for school papers - keeps everything organized, accessible, and prevents the chaos of loose papers (or in our case, sprawling documentation) from taking over your project.
Documentation
Getting Started
- Quick Start Guide - Get up and running in 5 minutes
- Installation Guide - Detailed installation instructions
- Configuration Reference - All configuration options
User Guides
- CLI Guide - Complete CLI command reference
- MCP Tools Reference - Using MCP tools effectively
- API Reference - Python API documentation
- Troubleshooting Guide - Common issues and solutions
Tutorials
- Basic Usage - Step-by-step tutorials
- Advanced Workflows - Complex use cases
- Integration Guide - Integrate with other tools
- Custom Categories - Create custom categories
Architecture & Development
- Architecture Overview - System design
- Contributing Guide - How to contribute
- Plugin Development - Extend functionality
Examples
- Example Configurations - Configuration examples
- Python Scripts - API usage examples
- Docker Setup - Docker deployment examples
- CLAUDE.md Examples - Sample documentation files
License
MIT License - see LICENSE file for details.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server that automatically manages and organizes project documentation using the document reference pattern, keeping CLAUDE.md files clean and under 500 lines while maintaining full context for AI assistants.
Related MCP Servers
- AsecurityFlicenseAqualityAn MCP server that intelligently chunks large documents for Claude, enabling efficient context-aware processing and summary generation for enhanced document comprehension.Last updated -12JavaScript
- -securityAlicense-qualityThe MCP server provides access to Clever Cloud's documentation, allowing users to query and interact with it through Model Context Protocol clients like Claude Desktop.Last updated -TypeScriptMIT License
- -securityAlicense-qualityAn MCP server that implements Claude Code-like functionality, allowing the AI to analyze codebases, modify files, execute commands, and manage projects through direct file system interactions.Last updated -179PythonMIT License
- -securityFlicense-qualityAn MCP server that integrates with Claude to provide smart documentation search capabilities across multiple AI/ML libraries, allowing users to retrieve and process technical information through natural language queries.Last updated -Python