mcp-clipboard: 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

mcp-clipboard is an MCP (Model Context Protocol) server that reads and writes the system clipboard — tables, plain text, code, JSON, URLs, images, and more. Preserves structure when possible (e.g. spreadsheet row/column layout from HTML) and returns non-tabular content with smart formatting. Images on the clipboard are returned as viewable content; audio and video are detected and reported but not returned.

Commands

# Install dependencies
uv sync

# Run all tests (mocked, no clipboard needed)
uv run pytest

# Run a single test file
uv run pytest tests/test_parser.py

# Run a single test function
uv run pytest tests/test_parser.py::test_parse_google_sheets_html

# Run integration tests (requires real clipboard daemon)
uv run pytest -m integration

# Run the MCP server (stdio mode)
uv run mcp-clipboard

# Run with debug logging
uv run mcp-clipboard --debug
# or: MCP_CLIPBOARD_DEBUG=1 uv run mcp-clipboard

# Test interactively with MCP Inspector
uv run mcp dev src/mcp_clipboard/server.py

# Build wheel (to verify packaging)
uv build --wheel

# Publish to PyPI (do NOT publish directly — push a tag to trigger GitHub Actions)
git tag v0.1.x && git push origin v0.1.x   # triggers .github/workflows/publish.yml
git tag test-v0.1.x && git push origin test-v0.1.x  # triggers test-publish.yml (TestPyPI)

Architecture

Three-layer design with clean separation:

• server.py — MCP server (FastMCP, name mcp_clipboard) exposing 7 tools:
  • clipboard_paste(output_format, include_schema, selection) — Primary tool. Handles any clipboard content: tables → markdown/json/csv; non-tabular → smart formatting (JSON, code, URL, text). Images are returned as base64-encoded image content. Audio/video are detected and reported. selection defaults to "clipboard"; pass "primary" on X11/Wayland to read the middle-click/select-text-to-paste buffer.
  • clipboard_copy(content) — Writes text to the system clipboard.
  • clipboard_copy_markdown(text) — Renders markdown to HTML and places both formats on the clipboard so paste targets pick the right one. macOS/Windows write both atomically via multi-format clipboard APIs; Wayland/X11 are single-MIME and write only text/html.
  • clipboard_copy_image(image_data, mime_type) — Writes a PNG or JPEG image to the system clipboard from base64-encoded bytes. Pass-through, no re-encoding. Magic bytes are validated against the declared MIME.
  • clipboard_read_raw(mime_type, selection) — Returns raw clipboard content for a given MIME type (truncated at 50KB). Rejects binary MIME types. Accepts selection="primary" on X11/Wayland.
  • clipboard_list_formats(selection) — Lists available MIME types on clipboard. Accepts selection="primary" on X11/Wayland.
  • clipboard_version() — Returns the running mcp-clipboard package version as {"name": "mcp-clipboard", "version": "<x.y.z>"}. Diagnostic surface for hosts that don't expose the standard MCP serverInfo block to the model, and for test harnesses that need to record which build served a given run.