Scratchpad Mcp

Scratchpad MCP v2

[](https://typescriptlang.org/) [](https://nodejs.org/) [](https://sqlite.org/) [](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides shared scratchpad functionality for Claude Code sub-agents, enabling seamless context sharing and collaboration within workflows.

🚀 TL;DR / Try it now

# Build
npm install && npm run build

# Add to Claude Code (must use startup script)
claude mcp add scratchpad-mcp-v2 -- /absolute/path/to/scratchpad-mcp-v2/start-mcp.sh

// Quick usage: create a workflow, write, and search
const workflow = await mcp.callTool('create-workflow', {
  name: 'AI Research Project',
  description: 'Collaborative research notes and findings',
});

const scratchpad = await mcp.callTool('create-scratchpad', {
  workflow_id: workflow.id,
  title: 'Model Architecture Notes',
  content: 'Initial transformer research findings...',
});

// Retrieve a workflow with optional scratchpad summaries
const workflowDetails = await mcp.callTool('get-workflow', {
  workflow_id: workflow.id,
  include_scratchpads_summary: true,
});

// Multi-mode editing example
await mcp.callTool('update-scratchpad', {
  id: scratchpad.id,
  mode: 'append_section',
  section_marker: '## Research Findings',
  content: 'New discovery about transformer architecture...',
});

// Block-based operations (NEW: semantic content handling)
const lastBlocks = await mcp.callTool('tail-scratchpad', {
  id: scratchpad.id,
  tail_size: { blocks: 2 }, // Get last 2 semantic blocks
});

await mcp.callTool('chop-scratchpad', {
  id: scratchpad.id,
  blocks: 1, // Remove last block precisely
});

// Chinese search example (intelligent tokenization)
const results = await mcp.callTool('search-scratchpads', {
  query: '自然語言處理模型架構',
  limit: 10,
});

⚠️ Important: always use start-mcp.sh

# ✅ CORRECT - use the startup script
./start-mcp.sh

# ❌ INCORRECT - running dist/server.js directly breaks path resolution
node dist/server.js

Why the startup script matters:

• Correct path resolution and database path handling
• Cross-directory support (works from any working directory)
• Proper loading of optional Chinese tokenization extensions

---

🚀 Quick Start

Prerequisites

• Node.js 18.0.0 or newer
• SQLite (FTS5 handled automatically)

Installation

# Clone the repository
git clone 
cd scratchpad-mcp-v2

# Install dependencies
npm install

# Type checking
npm run typecheck

# Run tests
npm test

# Build the server
npm run build

# Make startup script executable
chmod +x start-mcp.sh

Running as MCP Server

# ✅ Production mode - ALWAYS use the startup script
./start-mcp.sh

# ✅ Development mode with hot reload
npm run dev

# ❌ DO NOT run dist/server.js directly

Environment Configuration

# Optional: set a custom database path (relative to project root)
export SCRATCHPAD_DB_PATH="./my-scratchpad.db"

# Required for AI analysis features: OpenAI API key
export OPENAI_API_KEY="your-openai-api-key"

# Optional: disable specific MCP tools for token optimization
export SCRATCHPAD_DISABLED_TOOLS="get-scratchpad,get-scratchpad-outline"

# Or modify start-mcp.sh directly

🧰 Available MCP Tools

• create-workflow - Create workflow containers
• list-workflows - List all workflows
• get-latest-active-workflow - Get the most recently updated active workflow
• get-workflow - Retrieve a workflow by ID with optional scratchpads summary
• update-workflow-status - Activate/deactivate a workflow
• create-scratchpad - Create a scratchpad within a workflow
• get-scratchpad - Retrieve a scratchpad by ID with optional line range and context selection
• get-scratchpad-outline - Parse markdown headers and return structured outline with line numbers
• append-scratchpad - Append content to an existing scratchpad
• tail-scratchpad - Tail content with line/char/block modes, or set full_content=true to get full content
• chop-scratchpad - Remove lines or blocks from the end of a scratchpad (supports semantic block removal)
• update-scratchpad - Multi-mode editing tool with replace/insert/replace-lines/append-section modes
• list-scratchpads - List scratchpads in a workflow
• search-scratchpads - Full-text search with context-aware snippets (grep-like functionality, intelligent Chinese tokenization)
• search-scratchpad-content - Search within a single scratchpad content using string/regex patterns (VS Code Ctrl+F style)
• search-workflows - 🆕 Search workflows with weighted scoring (5/3/3/1) based on name/description/scratchpads content
• extract-workflow-info - Extract specific information from workflows using OpenAI models

---

🔗 Claude Code Integration

Prerequisites

• Node.js 18.0.0 or newer
• Claude Code CLI installed and configured
• Project built: npm run build

⚠️ Critical configuration

Always use an absolute path to start-mcp.sh to ensure correct path resolution and cross-directory compatibility.

Method 1: CLI installation (recommended)

# Build the project first
npm run build

# ✅ Use the startup script path
claude mcp add scratchpad-mcp-v2 -- /absolute/path/to/scratchpad-mcp-v2/start-mcp.sh

# ✅ Project scope (optional)
claude mcp add scratchpad-mcp-v2 --scope project -- /absolute/path/to/scratchpad-mcp-v2/start-mcp.sh

# ❌ INCORRECT - causes path resolution and cross-directory issues
claude mcp add scratchpad-mcp-v2 -- node ./dist/server.js

Method 2: Manual configuration

Project-level .mcp.json (recommended)

{
  "mcpServers": {
    "scratchpad-mcp-v2": {
      "command": "/absolute/path/to/scratchpad-mcp-v2/start-mcp.sh"
    }
  }
}

Global ~/.claude.json

{
  "mcpServers": {
    "scratchpad-mcp-v2": {
      "command": "/absolute/path/to/scratchpad-mcp-v2/start-mcp.sh",
      "env": {
        "SCRATCHPAD_DB_PATH": "./scratchpad-global.db"
      }
    }
  }
}

❌ Invalid configuration examples (do not use)

{
  "mcpServers": {
    "scratchpad-mcp-v2": {
      "command": "node",
      "args": ["./dist/server.js"], // Breaks Chinese tokenization and path resolution
      "cwd": "/path/to/project" // 'cwd' is not a valid MCP parameter
    }
  }
}

Cross-project usage

# Works from any directory - the script handles path resolution
cd /some/other/project
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | /path/to/scratchpad-mcp-v2/start-mcp.sh

Verification

# Check MCP server status
claude mcp list

# View server details
claude mcp get scratchpad-mcp-v2

# Test Chinese tokenization functionality (if installed)
# You should see messages like:
# ✅ Simple 中文分詞擴展載入成功
# ✅ Jieba 結巴分詞功能完全可用

Troubleshooting

• Server does not start: verify Node 18+, run npm run build, ensure start-mcp.sh is executable, use absolute path in MCP config
• Chinese search returns no results: most likely running dist/server.js directly — switch to start-mcp.sh
• Message "Simple 擴展載入失敗": normal when extensions are not installed; system falls back to FTS5/LIKE
• Tools not available: run claude mcp list, reload configuration, verify startup script path

Best practices

• Always use start-mcp.sh
• Prefer absolute paths
• Verify Chinese tokenizer loading messages
• Commit a project-level .mcp.json for teams

---

🌐 Workflow Web Viewer

A standalone HTTP server to browse scratchpad workflows via a web UI.

Quick Start

# Start web viewer (default port 3000)
npm run serve

# Custom port and development mode
npm run serve:dev
# or
node scripts/serve-workflow/server.js --port 3001 --dev

Database path configuration

Priority order:

# 1. Command line parameter (highest priority)
node scripts/serve-workflow/server.js --db-path "/path/to/database.db"

# 2. Environment variable
export SCRATCHPAD_DB_PATH="/path/to/database.db"
npm run serve

# 3. Default: ./scratchpad.v6.db (lowest priority)

Features

• 🔍 Search & filter: full-text search across workflows and scratchpads
• 🎨 Syntax highlighting: Prism.js with automatic dark/light theme
• 📱 Responsive UI with organization and pagination
• ⚡ Live updates

---

🇨🇳 Optional Chinese Text Enhancement

Optional feature to improve Chinese search accuracy (the system works fine without it via FTS5/LIKE fallback).

Installation

1. Create an extensions directory

mkdir -p extensions

1. Download the extension and dictionaries for your platform

macOS

curl -L "https://github.com/wangfenjin/simple/releases/download/v0.5.2/libsimple.dylib" \
     -o extensions/libsimple.dylib
curl -L "https://github.com/wangfenjin/simple/releases/download/v0.5.2/dict.tar.gz" \
     | tar -xz -C extensions/

Linux

curl -L "https://github.com/wangfenjin/simple/releases/download/v0.5.2/libsimple.so" \
     -o extensions/libsimple.so
curl -L "https://github.com/wangfenjin/simple/releases/download/v0.5.2/dict.tar.gz" \
     | tar -xz -C extensions/

1. Create the required symlink for jieba dictionaries (use absolute path)

ln -sf "$(pwd)/extensions/dict" ./dict

1. Use the automated installation script (includes proper symlinks)

chmod +x scripts/install-chinese-support.sh
./scripts/install-chinese-support.sh

1. Verify

ls -la extensions/
ls -la dict  # Should point to the absolute path of extensions/dict

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | ./start-mcp.sh
# Expected messages:
# ✅ Simple 中文分詞擴展載入成功
# ✅ Jieba 結巴分詞功能完全可用

Note: even without extensions installed, all search features work (fallback to FTS5/LIKE).

---

🛠️ MCP Tools API

Workflow Management

create-workflow

Create a new workflow container.

{
  name: string;           // required
  description?: string;   // optional
  project_scope?: string; // optional
}

list-workflows

List all workflows.

{
  project_scope?: string; // optional
}

get-workflow

Retrieve a workflow by ID with optional scratchpads summary.

{
  workflow_id: string;                 // required - workflow identifier
  include_scratchpads_summary?: boolean; // optional - include scratchpad summaries (default: true)
}

Response highlights:

• Returns workflow object with metadata (id, name, description, timestamps, scratchpad_count, project_scope, is_active)
• Includes scratchpads_summary when include_scratchpads_summary is omitted or true
• Provides friendly message indicating whether the workflow was found

get-latest-active-workflow

Get the most recently updated active workflow.

{
  project_scope: string; // required
}

update-workflow-status

Activate or deactivate a workflow.

{
  workflow_id: string; // required
  is_active: boolean; // required
}

Scratchpad Operations

create-scratchpad

Create a scratchpad within a workflow.

{
  workflow_id: string;    // required
  title: string;          // required
  content: string;        // required
  include_content?: boolean; // default: false
}

get-scratchpad

Retrieve a specific scratchpad with optional line range and context selection.

{
  id: string;                 // required
  line_range?: {              // optional - select specific line range
    start: number;            // >= 1 - start line number (1-based)
    end: number;              // >= start - end line number (1-based, inclusive)
  };
  line_context?: {            // optional - context lines around range
    before?: number;          // >= 0 - lines before range (default: 0)
    after?: number;           // >= 0 - lines after range (default: 0)
  };
  include_block?: boolean;    // optional - include block-based context (default: false)
}

Range Selection Features:

• line_range: Extract specific line range from scratchpad content
• line_context: Add context lines before/after the selected range
• include_block: Use semantic block boundaries for more intelligent context extraction

Parameter Conflicts: Cannot use line_range/line_context with include_block - they are mutually exclusive.

get-scratchpad-outline

Parse markdown headers in a scratchpad and return a structured outline with line numbers.

{
  id: string;                    // required - scratchpad ID
  max_depth?: number;            // optional - maximum header depth to include (1-6, default: 6)
  include_content?: boolean;     // optional - include full scratchpad content (default: false)
}

Features:

• Parses markdown headers (# ## ### #### ##### ######) and returns structured outline
• Provides line numbers for each header for precise navigation
• Configurable depth limit to focus on main sections
• Returns hierarchical structure showing header relationships
• Useful for navigation, content organization, and structured content extraction

Response Format:

{
  outline: Array;
  header_count: number;         // Total number of headers found
  max_level: number;            // Deepest header level in content
}

append-scratchpad

Append content to an existing scratchpad.

{
  id: string;             // required
  content: string;        // required
  include_content?: boolean; // default: false
}

tail-scratchpad

Tail content, or return full content with full_content=true. Supports block-based extraction for semantic content handling.

{
  id: string;             // required
  tail_size?: {           // choose either lines, chars, or blocks
    lines?: number;       // >= 1 - extract by line count
    chars?: number;       // >= 1 - extract by character count  
    blocks?: number;      // >= 1 - extract by block count (semantic units)
  };
  include_content?: boolean; // default: true
  full_content?: boolean;    // overrides tail_size
}

Parameter priority: full_content > tail_size > default (50 lines)

Block-based extraction: Uses the new append splitter format (---\n\n) to extract semantic content blocks rather than arbitrary lines. Perfect for retrieving complete logical sections.

chop-scratchpad

Remove content from the end of a scratchpad. Supports both line-based and block-based removal. Does not return content after completion.

{
  id: string;         // required - scratchpad ID
  lines?: number;     // optional - number of lines to remove from end (default: 1)
  blocks?: number;    // optional - number of blocks to remove from end (alternative to lines)
}

Block-based removal: Use blocks parameter to remove complete semantic blocks rather than arbitrary lines. Uses the append splitter format to identify block boundaries. Only one of lines or blocks should be specified.

update-scratchpad

Multi-mode scratchpad editing tool with four precise editing modes.

{
  id: string;                 // required - scratchpad ID
  mode: string;               // required - editing mode: 'replace' | 'insert_at_line' | 'replace_lines' | 'append_section'
  content: string;            // required - content to insert, replace, or append
  include_content?: boolean;  // optional - return content in response (default: false)
  
  // Mode-specific parameters:
  line_number?: number;       // required for 'insert_at_line' - 1-based line number
  start_line?: number;        // required for 'replace_lines' - 1-based start line (inclusive)
  end_line?: number;          // required for 'replace_lines' - 1-based end line (inclusive)
  section_marker?: string;    // required for 'append_section' - markdown section marker (e.g., "## Features")
}

Editing Modes:

• replace: Complete content replacement (no additional parameters)
• insert_at_line: Insert at specif

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pc035860
• Source: pc035860/scratchpad-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.