trapper-keeper-mcp

Name: trapper-keeper-mcp
Availability: InStock
Author: Aaron Sachs

Trapper Keeper MCP is an intelligent document extraction and organization system designed to keep your AI context organized. Built with Python and FastMCP, it monitors markdown and text files, extracts categorized content, and organizes it into structured outputs.

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

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:

git clone https://github.com/asachs01/trapper-keeper-mcp.git
cd trapper-keeper-mcp

Install dependencies:

pip install -e .

Copy the example configuration:

cp config.example.yaml config.yaml

Edit config.yaml to match your needs

MCP Integration

Add to your MCP settings:

{
  "mcpServers": {
    "trapper-keeper": {
      "command": "python",
      "args": ["-m", "trapper_keeper.mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/trapper-keeper-mcp/src"
      }
    }
  }
}

🌐 API

CLI Commands

# Process a single file
trapper-keeper process document.md -o ./output

# Process a directory
trapper-keeper process ./docs -c "🏗️ Architecture" -c "🔐 Security" -f json

# Watch a directory
trapper-keeper watch ./docs -p "*.md" -p "*.txt" --recursive

# List categories
trapper-keeper categories

# Run as MCP server
trapper-keeper server

# Show/save configuration
trapper-keeper config
trapper-keeper config -o my-config.yaml

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.

{
    "file_path": "/path/to/document.md",
    "extract_categories": ["🏗️ Architecture", "🔐 Security"],
    "output_format": "markdown"
}

`process_directory`

Process all matching files in a directory.

{
    "directory_path": "/path/to/docs",
    "patterns": ["*.md", "*.txt"],
    "recursive": true,
    "output_dir": "./output",
    "output_format": "json"
}

`watch_directory`

Start watching a directory for changes.

{
    "directory_path": "/path/to/docs",
    "patterns": ["*.md"],
    "recursive": true,
    "process_existing": true
}

`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 port
TRAPPER_KEEPER_MCP_PORT: MCP server port
TRAPPER_KEEPER_OUTPUT_DIR: Default output directory
TRAPPER_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

src/trapper_keeper/
├── core/           # Base classes and types
├── monitoring/     # File monitoring
├── parser/         # Document parsers
├── extractor/      # Content extraction
├── organizer/      # Output organization
├── mcp/           # MCP server
├── cli/           # CLI interface
└── utils/         # Utilities

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 in types.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.