remarkable-mcp copilot-instructions.md

Copilot Instructions for remarkable-mcp

Project Overview

This is an MCP (Model Context Protocol) server that provides access to reMarkable tablet data. It's a Python project using MCP Python SDK 2.x MCPServer.

Git Workflow

Always work on feature branches and submit PRs. Never push directly to main.

# Create a feature branch
git checkout -b feature/my-feature

# After making changes, push and create PR
git push origin feature/my-feature
# Then create PR via GitHub

Branch protection is enabled on main - all changes must go through pull requests with passing CI checks.

Package Management

Always use uv for all package management operations.

# Install dependencies
uv sync

# Install with dev dependencies
uv sync --extra dev

# Add a new dependency
uv add <package>

# Add a dev dependency
uv add --dev <package>

Never use:

• pip install directly
• pip freeze
• poetry

Running Tests

Always run tests with:

uv run pytest -v

For specific test patterns:

# Run specific test class
uv run pytest -v -k "TestClassName"

# Run with coverage
uv run pytest -v --cov=remarkable_mcp

# Skip slow tests if any
uv run pytest -v -m "not slow"

Important: Tests use pytest-asyncio for async testing. All async tests should use the @pytest.mark.asyncio decorator.

Building & Running

# Run the MCP server directly
uv run python server.py

# Register a new device (one-time setup)
uv run python server.py --register <one-time-code>

# Run as installed package
uv run remarkable-mcp

Code Quality

Before committing, always run:

# 1. Lint code (REQUIRED - CI will fail without this)
uv run ruff check .

# 2. Check formatting (REQUIRED - CI will fail without this)
uv run ruff format --check .

# 3. Run tests (REQUIRED - CI will fail without this)
uv run pytest -v

Fix issues automatically:

# Fix lint issues
uv run ruff check . --fix

# Fix formatting
uv run ruff format .