MCP TipTap Editor

A Model Context Protocol (MCP) server that provides atomic, line/column-level text editing capabilities for AI assistants using TipTap, a headless rich text editor built on ProseMirror.

Overview

This MCP server enables AI language models to perform precise text manipulation operations without regenerating entire paragraphs or sections. Instead of expensive token-heavy operations that rewrite large blocks of text, AI can execute atomic editing commands like:

• Cut/Copy/Paste text from specific line:column positions
• Insert text at precise locations
• Move paragraphs or sections without rewriting them
• Select and manipulate text ranges programmatically
• Search/Replace with position-aware operations
• Format text (bold, italic, headings) at specific positions

Why TipTap for MCP?

Traditional LLM text editing involves regenerating entire sections, which:

• Wastes tokens and API costs
• Risks introducing unintended changes
• Lacks precision for surgical edits

TipTap provides:

• ProseMirror foundation: Robust document model with position tracking
• Headless architecture: No DOM required - perfect for server-side operations
• Virtual document: Instantiate editors in Node.js without a browser
• Atomic operations: Precise transformations tracked by line/column
• Extensible: Rich ecosystem of extensions for various text operations## Use Cases

The primary advantage of this MCP server is token efficiency. By performing surgical, atomic operations, AI assistants can make complex changes to documents with minimal token overhead, leading to faster response times and lower API costs.

Token Savings Examples

| Operation | Traditional Regeneration | TipTap MCP Tool | Token Savings | | :--- | :--- | :--- | :--- | | Move Paragraph | Rewrite section (~500 tokens) | move_lines (~20 tokens) | ~96% | | Rename Variable | Rewrite code block (~300 tokens) | replace_all (~50 tokens) | ~83% | | Indent 10 Lines | Rewrite indented code (~150 tokens) | indent_lines (~20 tokens) | ~87% | | Format 5 Matches| Find & rewrite 5 times (~200 tokens) | apply_formatting_to_matches (~25 tokens) | ~88% |

Common Workflows

• Precise Editing: Change a single word at line: 42, column: 15 without touching the rest of the sentence.
• Structural Reorganization: Move the "Conclusion" section before the "Discussion" section using a single move_block command.
• Code Refactoring: Rename a function across an entire document with one replace_all call.
• Format Preservation: Apply bold to a phrase while preserving all other existing formatting.## MCP Tools

The server provides 9 grouped tools for AI assistants, organized by operation type. Each tool accepts an operation parameter to specify the specific action to perform. This design reduces cognitive load and improves AI discoverability compared to having 65+ individual tools.

Tool Groups Overview

| Tool Group | Operations Count | Purpose | |:-----------|:-----------------|:--------| | document | 8 | Document lifecycle (load, save, get_content, get_info, list, delete, compute_diff, apply_patch) | | edit | 9 | Direct text manipulation (insert_text, delete_range, replace_range, replace_all, get_text_range, get_lines, insert_lines, delete_lines, move_lines) | | clipboard | 6 | Cut/copy/paste operations (cut_text, copy_text, paste_text, cut_block, copy_block, paste_block) | | search | 5 | Find and locate content (find_text, find_heading, format_matches, delete_matches, get_changes) | | navigate | 10 | Navigate document structure (get_next, get_previous, get_parent, get_siblings, get_boundaries, get_block, move_block, select_paragraph, select_word, expand_selection) | | structure | 9 | Analyze document structure (get_toc, get_hierarchy, extract_code, extract_links, extract_images, validate, auto_format_code, update_toc, get_statistics) | | format | 24 | Text styling and transformation (apply_style, apply_heading, convert_levels, indent, dedent, to_list, toggle_list_type, wrap_quote, extract_quote, uppercase, lowercase, titlecase, camelcase, snakecase, kebabcase, slugify, reverse, sort_lines, deduplicate_lines, normalize_whitespace, trim_trailing, ensure_newline, toggle_comment) | | history | 3 | Undo/redo operations (undo, redo, get_history) | | sequence | 1 | Batch operations (execute a sequence of operations atomically) |

Usage Pattern

All grouped tools follow this pattern:

// Example: Get document content
{
  "tool": "document",
  "documentId": "my-doc",
  "operation": "get_content",
  "format": "text"  // operation-specific parameters
}

// Example: Replace all occurrences
{
  "tool": "edit",
  "documentId": "my-doc",
  "operation": "replace_all",
  "searchText": "foo",
  "replaceText": "bar",
  "caseSensitive": false
}

// Example: Move lines
{
  "tool": "edit",
  "documentId": "my-doc",
  "operation": "move_lines",
  "startLine": 10,
  "endLine": 15,
  "targetLine": 5
}

Detailed Tool Operations

• load_from_file: Load document from filesystem
• save_to_file: Save document to filesystem
• get_content: Retrieve content (text/html/json format)
• get_info: Get statistics (lines, words, characters)
• list: List all active document IDs
• delete: Close and remove document
• compute_diff: Calculate line-level diff between two documents
• apply_patch: Apply insert/delete/replace operations

• insert_text: Insert at line:column position
• delete_range: Delete character-level range
• replace_range: Replace specific range
• replace_all: Replace all text occurrences
• get_text_range: Extract text from range
• get_lines: Get specific line range
• insert_lines: Insert array of lines
• delete_lines: Delete line range
• move_lines: Move lines to new position

• cut_text: Cut text range to clipboard
• copy_text: Copy text range to clipboard
• paste_text: Paste at position
• cut_block: Cut markdown block by heading
• copy_block: Copy markdown block
• paste_block: Paste block at line

• find_text: Find all text occurrences with positions
• find_heading: Find heading by text, return line and level
• format_matches: Apply formatting to all matches
• delete_matches: Delete all text matches
• get_changes: Get line numbers that changed

• get_next: Get next heading from position
• get_previous: Get previous heading from position
• get_parent: Get parent heading in hierarchy
• get_siblings: Get sibling headings
• get_boundaries: Get block start/end lines
• get_block: Get markdown section by heading
• move_block: Move markdown section
• select_paragraph: Get paragraph range at line
• select_word: Get word range at position
• expand_selection: Expand to word/sentence/paragraph

• get_toc: Extract table of contents
• get_hierarchy: Get document heading hierarchy
• extract_code: Get all code blocks with language
• extract_links: Get all links with URLs
• extract_images: Get all image references
• validate: Check markdown syntax
• auto_format_code: Auto-detect code block languages
• update_toc: Generate/update table of contents
• get_statistics: Get detailed document statistics

Styling:

• apply_style: Apply bold/italic/strike/code to range
• apply_heading: Convert line to heading (h1-h6)
• convert_levels: Change heading levels (h2→h3, etc.)

Layout:

• indent: Indent line range
• dedent: Dedent line range
• to_list: Convert lines to bullet/numbered list
• toggle_list_type: Toggle bullet ↔ numbered
• wrap_quote: Wrap lines in blockquote
• extract_quote: Remove blockquote formatting
• toggle_comment: Add/remove comment syntax

Text Transformation:

• uppercase: Transform to UPPERCASE
• lowercase: Transform to lowercase
• titlecase: Transform To Title Case
• camelcase: Transform toCamelCase
• snakecase: Transform to_snake_case
• kebabcase: Transform to-kebab-case
• slugify: Transform to-url-slug
• reverse: Reverse text

Utilities:

• sort_lines: Sort lines alphabetically
• deduplicate_lines: Remove duplicate lines
• normalize_whitespace: Collapse blank lines
• trim_trailing: Remove trailing whitespace
• ensure_newline: Ensure final newline

• undo: Undo last operation
• redo: Redo last undone operation
• get_history: Get undo/redo availability status

Execute multiple operations atomically in sequence. Aborts on first error.

{
  "tool": "execute_sequence",
  "documentId": "my-doc",
  "operations": [
    { "tool": "clipboard", "operation": "cut_text", "params": { "range": {...} } },
    { "tool": "clipboard", "operation": "paste_text", "params": { "position": {...} } }
  ]
}

Token Efficiency: 3-5 operations in one call saves ~50-100 tokens vs individual calls.

This MCP server is designed for local-only use via standard input/output (STDIO), ensuring fast, low-latency communication with clients like Claude Desktop without the need for an HTTP server.

Core Components:

• src/index.ts: The main FastMCP server that manages tool definitions and communication.
• src/tiptap/client.ts: A powerful wrapper around a headless TipTap editor instance. It uses JSDOM to run in a Node.js environment and handles all core document manipulations.
• src/tools/: Grouped tool definitions organized by operation type:
  • document.ts - Document lifecycle operations
  • edit.ts - Text editing operations
  • clipboard.ts - Cut/copy/paste operations
  • search.ts - Search and find operations
  • navigate.ts - Navigation operations
  • structure.ts - Structure analysis operations
  • format.ts - Formatting and transformation operations
  • history.ts - Undo/redo operations
  • sequence.ts - Batch operation execution
  • tiptap-grouped.ts - Exports all grouped tools
  • index.ts - Tool registry and MCP server registration

Design Philosophy:

• Grouped Tools: 9 tool groups instead of 65 flat tools for better AI discoverability (8x reduction in top-level tools)
• Operation Parameter: Each tool group uses an operation enum to specify the specific action
• Token Efficiency: Atomic operations save 83-96% tokens vs regenerating content
• Line:Column Addressing: All operations use a human-readable, 1-indexed {line, column} coordinate system for intuitive text manipulation.
• Per-Document Instances: The server can manage multiple independent document sessions, each with its own content, clipboard, and history.
• Built-in History: TipTap automatically maintains an undo/redo history (up to 100 operations deep) for each document.
• Synchronous API: The tool design ensures predictable, atomic operations, making it easier for AI assistants to reason about document state.

Installation

# Clone repository
git clone https://github.com/yourusername/mcp-tiptap-editor.git
cd mcp-tiptap-editor

# Install dependencies
npm install
# or
bun install

# Build
npm run build

Usage

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "tiptap-editor": {
      "command": "node",
      "args": ["/path/to/mcp-tiptap-editor/dist/index.js"]
    }
  }
}

Example Workflows

Move paragraph without rewriting:

// 1. Load document
document.load_from_file({ documentId: "article", filePath: "article.md" })

// 2. Find section locations
search.find_heading({ documentId: "article", operation: "find_heading", text: "Introduction" }) // → line 5
search.find_heading({ documentId: "article", operation: "find_heading", text: "Conclusion" }) // → line 50

// 3. Move the Introduction section
navigate.move_block({ documentId: "article", operation: "move_block", headingText: "Introduction", targetLine: 50 })

Surgical word replacement:

// 1. Load document
document.load_from_file({ documentId: "article", filePath: "article.md" })

// 2. Find all occurrences
search.find_text({ documentId: "article", operation: "find_text", searchText: "algorithm" }) // → returns positions

// 3. Select word at first occurrence
navigate.select_word({ documentId: "article", operation: "select_word", line: 12, column: 15 }) // → returns range

// 4. Replace with new text
edit.replace_range({ documentId: "article", operation: "replace_range", range: {...}, text: "method" })

Batch formatting cleanup:

// Execute multiple operations atomically
execute_sequence({
  documentId: "article",
  operations: [
    { tool: "format", operation: "normalize_whitespace", params: {} },
    { tool: "format", operation: "trim_trailing", params: {} },
    { tool: "format", operation: "ensure_newline", params: {} }
  ]
})

Development

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Technical Details

Dependencies

• @tiptap/core - Core TipTap editor
• @tiptap/pm - ProseMirror libraries
• @tiptap/starter-kit - Essential extensions
• jsdom - Virtual DOM for headless operation
• fastmcp - MCP server framework
• zod - Schema validation

Editor Extensions

The server uses the following TipTap extensions:

• Document, Paragraph, Text (basic structure)
• Bold, Italic, Strike (formatting)
• Heading (h1-h6)
• BulletList, OrderedList, ListItem
• Blockquote, CodeBlock
• HardBreak, HorizontalRule

Additional extensions can be enabled as needed.

Roadmap

• [ ] Support for collaborative editing cursors
• [ ] Rich text format conversion (Markdown ↔ HTML)
• [ ] Multi-document session management
• [ ] Custom extension support
• [ ] Performance optimization for large documents
• [ ] Syntax highlighting for code blocks
• [ ] Table manipulation operations

License

MIT

Contributing

Contributions welcome! This is an early-stage project exploring efficient text editing for AI assistants.

Acknowledgments

• TipTap - Headless editor framework
• ProseMirror - Document editing foundation
• Model Context Protocol - AI integration standard