Scratchpad MCP v2
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
Related MCP server: Aider MCP Server
๐ Quick Start
Prerequisites
Installation
# Clone the repository
git clone <repository-url>
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
โ ๏ธ 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
๐ 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
Create an extensions directory
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/
Create the required symlink for jieba dictionaries (use absolute path)
ln -sf "$(pwd)/extensions/dict" ./dict
Use the automated installation script (includes proper symlinks)
chmod +x scripts/install-chinese-support.sh
./scripts/install-chinese-support.sh
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<{
level: number; // Header level (1-6)
title: string; // Header text content
line_number: number; // Line number in scratchpad (1-based)
}>;
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<!--- block start --->\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 specific line number (requires line_number)
replace_lines: Replace line range (requires start_line and end_line)
append_section: Smart append after markdown section marker (requires section_marker)
Response includes detailed operation feedback:
list-scratchpads
List scratchpads with pagination and content control.
{
workflow_id: string; // required
limit?: number; // default: 20, max: 50
offset?: number; // default: 0
preview_mode?: boolean; // return truncated content
max_content_chars?: number;
include_content?: boolean;
}
Content control priority: include_content > preview_mode > max_content_chars
Search & Discovery
search-workflows ๐
NEW: Search workflows with intelligent weighted scoring based on scratchpads content. Perfect for finding relevant workflows across projects.
{
query: string; // required - supports mixed English/Chinese
project_scope?: string; // filter by project scope
page?: number; // pagination (default: 1)
limit?: number; // items per page (default: 5, max: 20)
useJieba?: boolean; // force Chinese tokenization
}
Key Features:
Weighted Scoring: workflows.name (5pts) > workflows.description (3pts) = scratchpads.title (3pts) > scratchpads.content (1pt)
Mixed Language: "React็ตไปถ้็ผ" โ English: ["React"] + Chinese: ["็ตไปถ้็ผ"]
Project Isolation: Use project_scope for exact match filtering
Performance Optimized: Search workflows first, then load scratchpads for scoring
// Basic workflow search
const results = await callTool('search-workflows', {
query: 'authentication system'
});
// Project-scoped search
const projectResults = await callTool('search-workflows', {
query: 'user login',
project_scope: 'myapp'
});
// Mixed language with pagination
const mixedResults = await callTool('search-workflows', {
query: 'React็ตไปถ้็ผ',
page: 2,
limit: 10
});
search-scratchpad-content ๐
NEW: Search within a single scratchpad content using string or regex patterns. Similar to VS Code Ctrl+F or grep for a single file. Supports context-aware search results with line-based context.
{
id: string; // required - scratchpad ID
// Search parameters - exactly one must be provided
query?: string; // string search
queryRegex?: string; // regex search pattern
// Context display options
context_lines?: number; // lines before & after (shorthand, 0-50)
context_lines_before?: number; // lines before each match (0-50)
context_lines_after?: number; // lines after each match (0-50)
// Advanced options
max_context_matches?: number; // max matches to show context (default: 5, max: 20)
merge_context?: boolean; // merge overlapping context ranges (default: true)
show_line_numbers?: boolean; // show line numbers in output
// Output control (inherited)
include_content?: boolean; // include content in results
preview_mode?: boolean; // truncated preview
max_content_chars?: number; // character limit
}
Key Features:
VS Code Style Search: Find-in-file functionality with precise line targeting
Dual Search Modes: String literals (query) or regex patterns (queryRegex)
Context Awareness: Show surrounding lines like grep -A -B -C
Smart Snippets: Character-based or context-based snippet generation
Match Details: Line numbers, character positions, and match text extraction
// Basic string search
const stringResults = await callTool('search-scratchpad-content', {
id: 'scratchpad-123',
query: 'authentication'
});
// Regex search with context
const regexResults = await callTool('search-scratchpad-content', {
id: 'scratchpad-123',
queryRegex: 'function\\s+\\w+Auth',
context_lines: 3,
show_line_numbers: true
});
// Advanced context control
const contextResults = await callTool('search-scratchpad-content', {
id: 'scratchpad-123',
query: 'TODO',
context_lines_before: 1,
context_lines_after: 2,
max_context_matches: 10
});
search-scratchpads
Full-text search with automatic Chinese tokenization and graceful fallbacks. Supports context-aware search similar to grep -A -B -C.
{
query: string; // required
workflow_id: string; // required
limit?: number; // default: 10, max: 20
offset?: number; // default: 0
preview_mode?: boolean;
max_content_chars?: number;
include_content?: boolean;
useJieba?: boolean; // defaults to auto detection
// Context search parameters (grep-like functionality)
context_lines_before?: number; // lines before match (0-50)
context_lines_after?: number; // lines after match (0-50)
context_lines?: number; // symmetric context (0-50, takes precedence)
max_context_matches?: number; // limit matches processed (1-20, default: 5)
merge_context?: boolean; // merge overlapping ranges (default: true)
show_line_numbers?: boolean; // show line numbers (default: false)
}
Search intelligence: automatic detection โ jieba โ simple โ FTS5 โ LIKE; target <100ms. Context search provides grep-like functionality with line-based snippets.
AI Analysis
Extract specific information from workflows using OpenAI's GPT models.
{
workflow_id: string; // required - ID of the workflow to analyze
extraction_prompt: string; // required - specific prompt describing what to extract
model?: string; // optional - OpenAI model (default: "gpt-5-nano")
reasoning_effort?: string; // optional - reasoning level (default: "medium")
// valid: "minimal" | "low" | "medium" | "high"
}
Prerequisites: Requires OPENAI_API_KEY environment variable.
Supported Models: gpt-5-nano, gpt-5-mini, gpt-4o, gpt-4o-mini and other OpenAI models. GPT-5 models support the reasoning_effort parameter for enhanced analysis quality.
Returns: Structured analysis based on the extraction prompt, including the model used and number of scratchpads processed.
๐ Usage Examples (more)
Basic Workflow
// 1) Create a project-scoped workflow
const workflow = await callTool('create-workflow', {
name: 'ML Research Project',
description: 'Research notes and experiments',
project_scope: 'ml-research',
});
// 2) Create a scratchpad with Chinese content
const scratchpad = await callTool('create-scratchpad', {
workflow_id: workflow.id,
title: 'Transformer ๆถๆง็ ็ฉถ',
content: 'ๅๅง็่ช็ถ่ช่จ่็ๆจกๅๆถๆง็ ็ฉถ๏ผๅ
ๅซๆณจๆๅๆฉๅถ็่ฉณ็ดฐๅๆ...',
});
// 3) Multi-mode editing examples - demonstrate all four modes
// Replace mode: Complete content replacement
await callTool('update-scratchpad', {
id: scratchpad.id,
mode: 'replace',
content: '## ๆน้ฒ็ Transformer ๆถๆง็ ็ฉถ\n\nๅฎๅ
จ้ๅฏซ็็ ็ฉถ็ญ่จ๏ผๅ
ๅซๆๆฐ็ผ็พ...',
});
// Insert at line mode: Insert at specific position
await callTool('update-scratchpad', {
id: scratchpad.id,
mode: 'insert_at_line',
line_number: 5,
content: '### ้่ฆ็ผ็พ\n้ๆฏไธๅ็ช็ ดๆง็็ผ็พ...',
});
// Replace lines mode: Replace specific line range
await callTool('update-scratchpad', {
id: scratchpad.id,
mode: 'replace_lines',
start_line: 3,
end_line: 5,
content: '### ๆดๆฐ็ๆนๆณ่ซ\nไฝฟ็จๆฐ็่ฉไผฐๆจๆบ\nๅ
ๅซๆๆฐ็ๅฏฆ้ฉ็ตๆ',
});
// Append section mode: Smart append after markdown marker
await callTool('update-scratchpad', {
id: scratchpad.id,
mode: 'append_section',
section_marker: '## ๆน้ฒ็ Transformer ๆถๆง็ ็ฉถ',
content: '\n### ๆๆฐๅฏฆ้ฉ็ตๆ\nๆ่ฝๆๅ 15%๏ผๆบ็ขบๅบฆ้ๅฐ 97.2%',
});
// 4) Parse document structure with get-scratchpad-outline
const outline = await callTool('get-scratchpad-outline', {
id: scratchpad.id,
max_depth: 3, // Only show main sections (H1-H3)
include_content: false,
});
// 5) Range-based content extraction with get-scratchpad
const specificSection = await callTool('get-scratchpad', {
id: scratchpad.id,
line_range: { start: 5, end: 15 },
line_context: { before: 2, after: 2 }, // Add context lines
});
// 6) Block-based content extraction (semantic boundaries)
const blockContent = await callTool('get-scratchpad', {
id: scratchpad.id,
include_block: true, // Use semantic block boundaries instead of line ranges
});
// 7) Intelligent Chinese search (auto-detected jieba)
const results = await callTool('search-scratchpads', {
query: 'ๆณจๆๅๆฉๅถ ่ช็ถ่ช่จ',
workflow_id: workflow.id,
limit: 10,
});
// 8) Force tokenizer mode (English scenario)
const manualResults = await callTool('search-scratchpads', {
query: 'transformer attention',
useJieba: false,
limit: 10,
});
// 9) Context search - basic (like grep -C 3)
const contextResults = await callTool('search-scratchpads', {
query: 'error',
context_lines: 3,
workflow_id: workflow.id,
});
// 10) Context search - asymmetric (like grep -B 2 -A 5)
const asymmetricResults = await callTool('search-scratchpads', {
query: 'function',
context_lines_before: 2,
context_lines_after: 5,
show_line_numbers: true,
});
// 11) Context search - with match limits and line numbers
const limitedResults = await callTool('search-scratchpads', {
query: 'TODO',
context_lines: 1,
max_context_matches: 3,
show_line_numbers: true,
merge_context: false,
});
// 12) Append mixed-language content
await callTool('append-scratchpad', {
id: scratchpad.id,
content: '\n\n## Additional Findings\n\nFrom paper XYZ: ๆฐ็ผ็พ...',
});
// 13) Get full content via tail-scratchpad (alternative to get-scratchpad)
const fullContent = await callTool('tail-scratchpad', {
id: scratchpad.id,
full_content: true,
});
// 14) Traditional tail mode
const recentContent = await callTool('tail-scratchpad', {
id: scratchpad.id,
tail_size: { lines: 10 },
});
// 15) Block-based tail extraction (NEW: semantic content handling)
const lastTwoBlocks = await callTool('tail-scratchpad', {
id: scratchpad.id,
tail_size: { blocks: 2 },
include_content: true,
});
// 16) Block-based content removal (NEW: semantic content management)
await callTool('chop-scratchpad', {
id: scratchpad.id,
blocks: 1, // Remove the last block instead of arbitrary lines
});
// 17) Verify block operations with precise extraction
const remainingBlocks = await callTool('tail-scratchpad', {
id: scratchpad.id,
tail_size: { blocks: 3 }, // Get last 3 blocks for verification
});
// 18) Full content but metadata only
const controlledContent = await callTool('tail-scratchpad', {
id: scratchpad.id,
full_content: true,
include_content: false,
});
Integration with Claude Code (highlights)
Multi-agent collaboration via workflows
Context persistence across conversations
Intelligent search for both Chinese and English content
Project organization through workflows and project scopes
Cross-directory support via the startup script
๐ป Development Guide
Available Scripts
npm run dev # Development (hot reload)
npm run build # Build to dist/
npm test # All tests
npm run test:watch
npm run serve # Start web workflow viewer
npm run typecheck
npm run lint && npm run lint:fix
npm run format
npm run clean
# Cloud sync and database management
node scripts/live-sync.cjs --cloud-dir=~/Dropbox/scratchpad # Real-time sync
node scripts/checkpoint-database.cjs --delete-mode # WAL management
./scripts/install-chinese-support.sh # Chinese support
./start-mcp.sh < test-input.json # Test the startup script
Project Structure
src/
โโโ server.ts # MCP server entry point
โโโ server-helpers.ts # Parameter validation & error handling
โโโ database/
โ โโโ ScratchpadDatabase.ts # Core database operations
โ โโโ schema.ts # SQL schema & FTS5 configuration
โ โโโ types.ts # Database type definitions
โ โโโ index.ts # Database module exports
โโโ tools/
โโโ workflow.ts # Workflow management tools
โโโ scratchpad.ts # Scratchpad CRUD operations
โโโ search.ts # Search functionality
โโโ types.ts # Tool type definitions
โโโ index.ts # Tools module exports
scripts/
โโโ serve-workflow/ # Web UI workflow viewer
โโโ start-mcp.sh # โ ๏ธ Startup script (ALWAYS use this)
โโโ install-chinese-support.sh # Chinese tokenization setup
โโโ live-sync.cjs # ๐ฉ๏ธ Real-time cloud sync (no MCP disconnect needed)
โโโ checkpoint-database.cjs # WAL checkpoint management
โโโ check-search-mode.cjs # FTS5/LIKE search mode diagnostics
tests/
โโโ database.test.ts # Database layer tests
โโโ mcp-tools.test.ts # MCP tools integration tests
โโโ performance.test.ts # Performance benchmarks
โโโ update-scratchpad.test.ts # Multi-mode editing tool tests
โโโ line-editor.test.ts # Line editing algorithm tests
โโโ extraction.test.ts # AI extraction feature tests
โโโ chop-scratchpad.test.ts # Chop functionality tests
โโโ mcp-project-scope.test.ts # Project scope isolation tests
โโโ project-scope.test.ts # Additional project scope tests
โโโ output-control.test.ts # Output control optimization tests
โโโ parameter-conflict.test.ts # Parameter validation conflict tests
โโโ ux-optimization.test.ts # UX optimization tests
โโโ critical-fixes-validation-v2.test.ts # Critical fixes validation
# (18 test files total, 750+ tests passing)
extensions/
โโโ libsimple.dylib # macOS simple tokenizer
โโโ libsimple.so # Linux simple tokenizer
โโโ dict/ # Jieba dictionaries
โโโ jieba.dict.utf8
โโโ hmm_model.utf8
โโโ ...
Testing Strategy
Database layer: CRUD, FTS5, error and edge cases, Chinese tokenization
MCP tools integration: 14 tools parameter validation, scenarios, protocol compliance
Performance: FTS5 <100ms, 1MB content, concurrent access, tokenization performance
Project scope: workflow isolation, cross-project restrictions
Code Quality Standards
TypeScript strict mode (no any)
ESLint + Prettier
95% test coverage
Targets: <100ms search, 1MB content
Path resolution via the startup script
๐ฉ๏ธ Cloud Sync & Database Tools
Real-time Cloud Sync (live-sync.cjs)
Sync your scratchpad database to cloud storage without disconnecting MCP servers, perfect for multi-machine workflows.
Key Features:
โ
No MCP Server disconnection required
โ
Uses passive checkpoint (non-blocking)
โ
Smart sync (only when files change)
โ
Automatic backup with rotation
โ
Works with WAL mode seamlessly
Basic Usage
# One-time sync
node scripts/live-sync.cjs --cloud-dir=~/Dropbox/scratchpad
# Automated sync (add to crontab)
*/30 * * * * cd /path/to/project && node scripts/live-sync.cjs --cloud-dir=~/Dropbox/scratchpad
Advanced Options
# Custom database and backup retention
node scripts/live-sync.cjs --db=scratchpad.v6.db --cloud-dir=~/iCloud/scratchpad --keep=10
# Dry run mode
node scripts/live-sync.cjs --cloud-dir=~/Dropbox/scratchpad --dry-run --verbose
Multi-machine Setup
# On other machines, restore from cloud
cp ~/Dropbox/scratchpad/scratchpad.v6.db ./scratchpad.v6.db
Database Management Tools
Database Migration (migrate-workflows-fts.cjs)
๐ NEW: Migrate existing databases to support the new search-workflows tool with weighted scoring.
Automatic Migration (Recommended):
Manual Migration:
# Migrate default database
node scripts/migrate-workflows-fts.cjs
# Migrate specific database
node scripts/migrate-workflows-fts.cjs /path/to/your/database.db
What's Added:
โ
workflows_fts virtual table for full-text search
โ
Automatic FTS5 triggers for data synchronization
โ
search-workflows tool with 5/3/3/1 weighted scoring
โ
Mixed English/Chinese language support
โ
Project scope filtering and smart pagination
Safety Features:
๐ Automatic backup before migration (.backup.timestamp)
๐ FTS5 graceful fallback to LIKE search if unsupported
โ
Data integrity verification after migration
๐ก๏ธ Rollback support via backup files
WAL Checkpoint (checkpoint-database.cjs)
Handle WAL files and perform database maintenance:
# Process WAL files and switch to DELETE mode
node scripts/checkpoint-database.cjs --delete-mode --db-path=scratchpad.v6.db
Search Mode Diagnostics (check-search-mode.cjs)
Check FTS5/LIKE search mode status:
# Verify search capabilities
node scripts/check-search-mode.cjs
๐ง Advanced Configuration
Startup Script Features
#!/bin/bash
# Ensure correct working directory
cd "$(dirname "$0")"
export SCRATCHPAD_DB_PATH="${SCRATCHPAD_DB_PATH:-./scratchpad.db}"
node dist/server.js "$@"
Benefits: stable working directory, proper extension/dictionary loading, DB path setup, cross-directory support.
FTS5 Configuration
Disabled automatically in test environments
Tokenizer selection: simple/jieba/standard
Fallback strategy: jieba โ simple โ FTS5 โ LIKE
Indexed fields: title and content (with triggers)
Ranking: BM25
Database Optimization
๐ Technical Specifications
Architecture
Server: MCP over stdio
Tools: 16 core tools with comprehensive parameter validation
Database: SQLite with FTS5 full-text search, WAL mode, optional Chinese tokenization
Content Management: Block-based operations with semantic content handling via BlockParser utility
Append System: Enhanced splitter format (---\n<!--- block start --->\n) for clear content separation
Extension layer: optional Chinese word segmentation with cross-directory support
Performance Characteristics
Metric | Target | Implementation |
Search Response | <100ms | FTS5 indexing with prepared statements |
Chinese Search | <150ms | Jieba tokenization with fallback strategy |
Content Limit | 1MB per scratchpad | Validated at tool level |
Workflow Capacity | 50 scratchpads | Enforced by database constraints |
Concurrent Access | Thread-safe | SQLite WAL mode |
Cross-Directory | โ
Supported | Via startup script path resolution |
Data Model
workflows
โโโ id (primary key)
โโโ name
โโโ description
โโโ created_at
โโโ updated_at
โโโ scratchpad_count
โโโ is_active
โโโ project_scope
scratchpads
โโโ id (primary key)
โโโ workflow_id (foreign key)
โโโ title
โโโ content
โโโ size_bytes
โโโ created_at
โโโ updated_at
scratchpads_fts (FTS5 virtual table)
โโโ id (unindexed)
โโโ workflow_id (unindexed)
โโโ title (indexed)
โโโ content (indexed)
โโโ tokenize=simple # with optional jieba
Environment Variables
Variable | Description | Default | Example |
SCRATCHPAD_DB_PATH
| Database file path (relative to project root) | ./scratchpad.db
| ./my-scratchpad.db
|
OPENAI_API_KEY
| OpenAI API key for AI analysis features | - | sk-...
|
SCRATCHPAD_DISABLED_TOOLS
| Comma-separated list of tools to disable for token optimization | "" (all enabled)
| get-scratchpad,get-scratchpad-outline
|
Tool Control Examples
# Disable get-scratchpad tool only
export SCRATCHPAD_DISABLED_TOOLS="get-scratchpad"
# Disable both tools for maximum token savings
export SCRATCHPAD_DISABLED_TOOLS="get-scratchpad,get-scratchpad-outline"
# Enable all tools (default behavior)
unset SCRATCHPAD_DISABLED_TOOLS
Available tools for disabling:
Token Savings:
Disabling get-scratchpad: ~200-300 tokens
Disabling get-scratchpad-outline: ~150-200 tokens
Total potential savings: ~350-500 tokens
Environment Requirements
Dependencies
Core: @modelcontextprotocol/sdk, better-sqlite3
AI Features: openai, tiktoken
Web Viewer: marked, marked-highlight, prismjs
Dev: typescript, tsup, vitest, eslint, prettier
๐ค Contributing
Fork the repository
Create a branch: git checkout -b feature/amazing-feature
Install deps: npm install
Build: npm run build
Test startup script: ./start-mcp.sh
Make changes and add tests
Run tests: npm test
Quality checks: npm run typecheck && npm run lint
Commit: git commit -m 'feat: add amazing feature'
Push: git push origin feature/amazing-feature
Open a PR
Development Standards
New features must include tests; maintain >95% coverage
Follow TypeScript strict mode
Conventional Commits
Update docs for API changes
Use start-mcp.sh for manual testing
๐ License
MIT License (see LICENSE)
๐ Support
Issues: GitHub Issues for bug reports and feature requests
Documentation: inline code docs and tests
Performance: FTS5 target <100ms
Chinese support: ensure tokenizer is loaded via the startup script
Remember: always use ./start-mcp.sh to launch the MCP server. Running dist/server.js directly causes path resolution and cross-directory compatibility issues.
