Guidance for LLM-based code agents
===================================
This file provides guidance to LLM-based code agents (e.g., Claude Code,
Cursor, Copilot) when working with code in this repository.
Project overview
----------------
An MCP (Model Context Protocol) server that provides clipboard read/write
tools. Cross-platform support for Linux, macOS, Windows, and WSL via
pyperclip.
Development commands
--------------------
~~~~ bash
uv sync # Install dependencies
uv run pyright # Type check
uv run ruff check . # Lint
uv run ruff format . # Format code
uv run clipboard-mcp # Run the server
~~~~
Architecture
------------
Single-module MCP server using FastMCP from the *mcp* package:
- *clipboard_mcp/__init__.py*: Defines `mcp` (FastMCP instance) with
two tools:
- `read_clipboard()`: Returns clipboard text via `pyperclip.paste()`
- `write_clipboard(text)`: Copies text via `pyperclip.copy()`
- Entry point: `main()` calls `mcp.run()` (stdio transport)
Code style
----------
- ruff with `select = ["ALL"]` (strict linting)
- Target Python 3.10+
- Error messages: assign to variable before raising (EM102 rule)
- Use `try`/`except`/`else` pattern for operations that can fail
Markdown style guide
--------------------
When creating or editing Markdown documentation files in this project,
follow these style conventions to maintain consistency with existing
documentation:
### Headings
- *Setext-style headings*: Use underline-style for the document title
(with `=`) and sections (with `-`):
~~~~
Document title
==============
Section name
------------
~~~~
- *ATX-style headings*: Use only for subsections within a section:
~~~~
### Subsection name
~~~~
- *Heading case*: Use sentence case (capitalize only the first word and
proper nouns) rather than Title Case:
~~~~
Development commands ← Correct
Development Commands ← Incorrect
~~~~
### Text formatting
- *Italics* (`*text*`): Use for package names, emphasis, and to distinguish
concepts
- *Bold* (`**text**`): Use sparingly for strong emphasis
- *Inline code* (`` `code` ``): Use for code spans, function names,
filenames, and command-line options
### Lists
- Use ` - ` (space-hyphen-two spaces) for unordered list items
- Indent nested items with 4 spaces
- Align continuation text with the item content:
~~~~
- *First item*: Description text that continues
on the next line with proper alignment
- *Second item*: Another item
~~~~
### Code blocks
- Use four tildes (`~~~~`) for code fences instead of backticks
- Always specify the language identifier:
~~~~~
~~~~ python
def example() -> str:
return "Hello, world!"
~~~~
~~~~~
- For shell commands, use `bash`:
~~~~~
~~~~ bash
uv run pyright
~~~~
~~~~~
### Links
- Use reference-style links placed at the *end of each section*
(not at document end)
- Format reference links with consistent spacing:
~~~~
See the [MCP documentation] for protocol details.
[MCP documentation]: https://modelcontextprotocol.io/
~~~~
### GitHub alerts
Use GitHub-style alert blocks for important information:
- *Note*: `> [!NOTE]`
- *Tip*: `> [!TIP]`
- *Important*: `> [!IMPORTANT]`
- *Warning*: `> [!WARNING]`
- *Caution*: `> [!CAUTION]`
Continue alert content on subsequent lines with `>`:
~~~~
> [!CAUTION]
> This feature is experimental and may change in future versions.
~~~~
### Tables
Use pipe tables with proper alignment markers:
~~~~
| Parameter | Type | Description |
| --------- | ------ | -------------------- |
| `text` | string | Text to copy |
~~~~
### Spacing and line length
- Wrap lines at approximately 80 characters for readability
- Use one blank line between sections and major elements
- Use two blank lines before Setext-style section headings
- Place one blank line before and after code blocks
- End sections with reference links (if any) followed by a blank line
