scratchpad_mcp: Instructions file for Claude Code

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

# 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:

# 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.