# MCP Scratchpad Server

[![PyPI](https://img.shields.io/pypi/v/mcp-server-scratchpad)](https://pypi.org/project/mcp-server-scratchpad/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) server that provides a "think" tool for structured reasoning, based on the [Anthropic blog post](https://www.anthropic.com/engineering/claude-think-tool).

## Overview

The Scratchpad MCP server allows Claude and other LLMs to add dedicated thinking steps during complex tool use scenarios. This improves problem-solving by creating space for structured reasoning and helps the model carefully process tool call outputs.

## Features

- **Think Tool**: Add thoughts to a timestamped log for structured reasoning
- **Thoughts Log Resource**: View all logged thoughts in JSON format
- **Clear Tool**: Reset the thinking log when needed
- **Structured Thinking Prompt**: Template for systematic problem-solving

## Installation

### Quick Start (Recommended)

Run directly with uvx (no installation needed):
```bash
uvx mcp-server-scratchpad
```

### PyPI Installation

Install globally with pip or uv:
```bash
# Using pip
pip install mcp-server-scratchpad

# Using uv
uv pip install mcp-server-scratchpad
```

### Development Installation

For local development:
```bash
# Clone the repository
git clone https://github.com/JoshuaOliphant/scratchpad_mcp.git
cd scratchpad_mcp

# Install dependencies
uv sync

# Run the server
uv run mcp-server-scratchpad
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration:

On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

Using uvx:
```json
{
  "mcpServers": {
    "scratchpad": {
      "command": "uvx",
      "args": ["mcp-server-scratchpad"]
    }
  }
}
```

Using pip installation:
```json
{
  "mcpServers": {
    "scratchpad": {
      "command": "mcp-server-scratchpad"
    }
  }
}
```

### Testing with MCP Inspector

For development and testing:
```bash
# Using uvx
uvx mcp-server-scratchpad

# Using MCP Inspector (if developing locally)
uv run mcp dev src/mcp_server_scratchpad/server.py
```

## Tools

### think
Add a thinking step to the log.

**Parameters:**
- `thought` (string): The thought to log

**Example:**
```json
{
  "thought": "I need to break this problem into smaller parts..."
}
```

### clear_thoughts
Clear all thoughts from the log.

**No parameters required**

## Resources

### log://thoughts
Returns all logged thoughts as a JSON array with timestamps.

**Example output:**
```json
[
  {
    "timestamp": "2024-01-20T10:30:45.123456",
    "thought": "First, I need to understand the requirements..."
  },
  {
    "timestamp": "2024-01-20T10:31:02.789012",
    "thought": "The main components are X, Y, and Z..."
  }
]
```

## Prompts

### Structured Thinking
A template for systematic problem-solving using the think tool.

**Parameters:**
- `topic` (string): The topic or problem to think through

## Use Cases

The scratchpad tool is particularly useful for:

1. **Long chains of tool calls**: Keep track of intermediate results and reasoning
2. **Complex problem-solving**: Break down problems systematically
3. **Policy-heavy environments**: Verify compliance with guidelines
4. **Sequential decision making**: Document the reasoning process
5. **Edge case handling**: Think through unusual scenarios

## Example Workflow

1. Start with a complex problem
2. Use the "Structured Thinking" prompt to set up the approach
3. Use the `think` tool multiple times to log reasoning steps
4. Check progress with the `log://thoughts` resource
5. Clear the log when starting a new problem

## Best Practices

- Use descriptive thoughts that explain the "why" not just the "what"
- Break complex problems into smaller, manageable parts
- Validate reasoning at each step
- Summarize conclusions at the end
- Clear the log between unrelated tasks

## Development

To modify the server:

1. Fork the repository
2. Make your changes to `src/mcp_server_scratchpad/server.py`
3. Test with `uv run mcp dev src/mcp_server_scratchpad/server.py`
4. Submit a pull request

## Future Enhancements

Potential improvements:
- Persist thoughts to a file
- Add search/filter capabilities
- Support for thought categories or tags
- Export thoughts in different formats
- Integration with other reasoning tools

## License

MIT License - see LICENSE file for details

## Credits

Based on the thinking tool concept from [Anthropic's blog post](https://www.anthropic.com/engineering/claude-think-tool)