# 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**:
```bash
cd ~/Documents/GitHub/scratchpad
```

2. **Install dependencies**:
```bash
pip install -r requirements.txt
```

3. **Make the server executable**:
```bash
chmod +x src/server.py
```

## Usage

### As an MCP Server

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

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```bash
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:

```bash
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:

```bash
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.