Scratchpad MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview This is an MCP (Model Context Protocol) server that implements a "think" tool for structured reasoning, based on the Anthropic blog post about improving Claude's problem-solving capabilities through dedicated thinking steps. ## Project Structure ``` scratchpad_mcp/ ├── src/ │ └── mcp_server_scratchpad/ │ ├── __init__.py # Entry point with main() function │ ├── __main__.py # Module runner │ └── server.py # Core server implementation ├── pyproject.toml # Package configuration and dependencies ├── README.md # User documentation └── LICENSE # MIT license ``` ## Development Commands ```bash # Install dependencies uv sync # Run the server directly uv run mcp-server-scratchpad # Run development server with MCP Inspector uv run mcp dev src/mcp_server_scratchpad/server.py # Run tests (when added) uv run pytest # Format code uv run ruff format # Check code style uv run ruff check ``` ## Package Distribution This package is designed to be distributed via PyPI and run with uvx: ```bash # Run without installation (recommended) uvx mcp-server-scratchpad # Or install globally pip install mcp-server-scratchpad ``` ## Architecture The codebase uses the low-level MCP server API: - `src/mcp_server_scratchpad/server.py`: Main server implementation - Uses in-memory storage for thoughts (list: `thoughts_log`) - Implements three MCP primitives: - **Tools**: `think()` for logging thoughts, `clear_thoughts()` for resetting - **Resources**: `read_resource()` exposes thoughts at `log://thoughts` - **Prompts**: `get_prompt()` provides structured thinking template - Uses stdio transport for communication ## Key Implementation Details 1. **Server Type**: Uses the low-level `mcp.server.Server` API (not FastMCP) for maximum control and compatibility with packaging standards. 2. **Thought Storage**: Currently uses an in-memory list that resets when the server restarts. Future enhancement could persist to JSON file. 3. **Tool Design**: The `think` tool follows the blog post specification exactly - it only logs thoughts without obtaining new information or changing any database. 4. **Resource URI**: Uses the `log://` scheme for the thoughts resource to indicate it's a log-type resource. 5. **Timestamp Format**: Uses ISO format timestamps for each thought entry. 6. **Entry Point**: The `mcp-server-scratchpad` command is defined in `pyproject.toml` and points to `mcp_server_scratchpad:main`. ## Testing Approach When modifying the server: 1. Use MCP Inspector (`uv run mcp dev`) to interactively test tools and resources 2. Verify the think tool properly logs thoughts with timestamps 3. Check the resource returns valid JSON 4. Test the clear function resets the log 5. Ensure the structured thinking prompt provides helpful guidance 6. Test the packaged version with `uv run mcp-server-scratchpad`