AI Scratchpad MCP Server

A secure Model Context Protocol (MCP) server for managing a global AI scratchpad file. Track interruptions, ideas, tasks, and maintain focus across all your projects with a single scratchpad on your Desktop.

🔒 Security Features

• Input Validation: Comprehensive sanitization of all user inputs
• Rate Limiting: 60 requests/minute protection against abuse
• Path Traversal Protection: Workspace boundary enforcement
• Content Size Limits: Max 1MB file size, 500 char notes
• Allowed Directory Restrictions: Only approved locations
• Error Sanitization: Prevents sensitive information disclosure

Features

• 📝 Log Interruptions: Capture ideas without losing focus
• 🎯 Track Current Focus: Update and maintain your current task
• 🔄 Review Later: Queue items for follow-up consideration
• ✅ Mark Completed: Track accomplishments with timestamps
• 🗑️ Archive Items: Dismiss or archive old ideas
• 📊 Auto Statistics: Automatically tracks logged, completed, and archived items
• 🌍 Global Scratchpad: Single scratchpad on Desktop accessible from all projects
• 📋 Organized Storage: Markdown-based scratchpad with sections
• 🔐 Secure by Design: Input validation, rate limiting, path protection
• ⚡ Fast & Lightweight: Minimal dependencies, quick operations

Installation

Prerequisites

• Python 3.8+
• MCP-compatible client (Claude Desktop, etc.)

Setup

1. Clone or download this project:

cd ~/Documents/GitHub/scratchpad

2. Install dependencies:

pip install -r requirements.txt

3. Make the server executable:

chmod +x src/server.py

Usage

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "scratchpad": {
      "command": "python3",
      "args": ["/path/to/scratchpad/src/server.py"]
    }
  }
}

The scratchpad will be created at ~/Desktop/scratchpad/scratchpad.md and accessible from all your projects.

Available Tools

1. scratchpad_create

Create a new scratchpad file at ~/Desktop/scratchpad/scratchpad.md.

No parameters required.

2. scratchpad_get_path

Get the scratchpad file path and check if it exists.

No parameters required.

3. scratchpad_read

Read the entire scratchpad contents.

No parameters required.

4. scratchpad_log_interruption

Log an idea, bug, or interruption.

Parameters:

• note (required): The note to log (max 500 chars)
• type (optional): One of: idea, bug, feature, question, contact, refactor, task, note
• priority (optional): One of: high, medium, low

Example:

{
  "note": "Add error handling to API client",
  "type": "bug",
  "priority": "high"
}

5. scratchpad_update_focus

Update your current focus/task.

Parameters:

• task (required): Description of current task (max 200 chars)

Example:

{
  "task": "Implementing user authentication flow"
}

6. scratchpad_add_to_review_later

Add an item to the "To Review Later" section for follow-up.

Parameters:

• note (required): The item to add (max 500 chars)

Example:

{
  "note": "Research better caching strategy for API calls"
}

7. scratchpad_mark_completed

Mark an item as completed. Adds it to "Completed Today" with timestamp and removes it from Interruptions/Review Later.

Parameters:

• note (required): The completed item (max 500 chars)

Example:

{
  "note": "Fixed authentication bug in login flow"
}

8. scratchpad_archive_item

Archive/dismiss an item. Moves it to "Archived / Dismissed" section and removes it from Interruptions/Review Later.

Parameters:

• note (required): The item to archive (max 500 chars)

Example:

{
  "note": "Old idea that's no longer relevant"
}

🔒 Security Configuration

Scratchpad Location

The scratchpad is always located at:

• Primary: ~/Desktop/scratchpad/scratchpad.md
• Fallback: ~/scratchpad/scratchpad.md (if Desktop doesn't exist)

This fixed location prevents path traversal attacks and unauthorized file access.

File Restrictions

• Extensions: Only .md, .txt, .markdown
• Max size: 1MB
• Path length: 256 characters max

Rate Limiting

• Limit: 60 requests per minute
• Window: Rolling 60-second window
• Scope: Per-process (resets on server restart)

Input Sanitization

All inputs are sanitized to prevent:

• Path traversal attacks (.., ~)
• Command injection (`, $)
• XSS attempts (<script>, javascript:)
• Null byte injection (\x00)

Content Limits

• Notes: 500 characters maximum
• Tasks: 200 characters maximum
• File size: 1MB maximum

Security Best Practices

1. File Permissions

Ensure the scratchpad directory has appropriate permissions:

chmod 755 ~/Desktop/scratchpad
chmod 644 ~/Desktop/scratchpad/scratchpad.md

2. Regular Cleanup

Monitor scratchpad file sizes and archive old content regularly.

3. Error Monitoring

Check stderr output for security warnings:

python3 src/server.py 2>scratchpad-errors.log

Troubleshooting

"Rate limit exceeded" Error

Wait for the specified time or restart the server to reset the rate limiter.

"Scratchpad not found" Error

The scratchpad doesn't exist yet. Use scratchpad_create to create it at ~/Desktop/scratchpad/scratchpad.md.

Desktop Not Found

If ~/Desktop doesn't exist, the scratchpad will be created at ~/scratchpad/scratchpad.md instead.

Development

Testing

Test the server directly:

cd ~/Documents/GitHub/scratchpad
python3 src/server.py

Debugging

The server outputs operational info to stderr:

🔒 Scratchpad MCP initialized
📁 Scratchpad location: /Users/username/Desktop/scratchpad/scratchpad.md
✅ Created scratchpad: /Users/username/Desktop/scratchpad/scratchpad.md
📝 Logged: Bug - Add error handling...

License

MIT License - feel free to use and modify as needed.

Security Reporting

If you discover a security vulnerability, please report it privately rather than creating a public issue.