cut-copy-paste-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.

Project Overview

This is an MCP (Model Context Protocol) server that provides cut, copy, paste, and undo operations for AI-assisted coding agents. The server is designed to be NPX-runnable and uses SQLite for session management and operation logging.

Strict TDD Development Process

This project MUST follow Test-Driven Development strictly. All implementation follows the Red-Green-Refactor cycle:

1. RED: Write failing tests first
2. GREEN: Implement minimum code to pass tests
3. REFACTOR: Improve code while keeping tests green

Never write implementation code before writing the test. Refer to TODO.md for the detailed phase-by-phase TDD implementation plan.

Development Commands

Since the project is not yet initialized, these commands will be needed once setup is complete:

# Install dependencies
npm install

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- path/to/test-file.test.ts

# Build TypeScript
npm run build

# Run linter
npm run lint

# Start MCP server (after build)
npx cut-copy-paste-mcp

Architecture Overview

Core Design Philosophy

The server follows a layered architecture with clear separation of concerns:

MCP Server Layer (protocol handling)
    ↓
Tool Handlers (copy, cut, paste, undo, show_clipboard, get_history)
    ↓
Business Logic Layer (SessionManager, ClipboardManager, FileHandler, OperationLogger)
    ↓
Data Layer (SQLite database)

Key Components

1. Session Manager

• Creates and manages session lifecycle
• Tracks session activity timestamps
• Cleans up expired sessions (24h timeout)
• Session ID is cryptographically secure

2. Clipboard Manager

• One clipboard buffer per session (stored in SQLite)
• Stores content + metadata (source file, line range, operation type)
• Supports copy and cut operations
• Clipboard persists for session lifetime