Typst MCP Server

# Development Guidelines This document contains critical information about working with this codebase. Follow these guidelines precisely. ## Core Development Rules 1. Package Management - ONLY use uv, NEVER pip - Installation: `uv add package` - Running tools: `uv run tool` - Upgrading: `uv add --dev package --upgrade-package package` - FORBIDDEN: `uv pip install`, `@latest` syntax 2. Code Quality - Type hints required for all code - Public APIs must have docstrings - Functions must be focused and small - Follow existing patterns exactly - Line length: 88 chars maximum 3. Testing Requirements - Framework: `uv run --frozen pytest tests` - Async testing: use anyio, not asyncio - Coverage: test edge cases and errors - New features require tests - Bug fixes require regression tests ## Pull Requests - Create a detailed message of what changed. Focus on the high level description of the problem it tries to solve, and how it is solved. Don't go into the specifics of the code unless it adds clarity. ## Python Tools ## Code Formatting 1. Ruff - Format: `uv run --frozen ruff format .` - Lint: `uv run --frozen ruff check . --fix --unsafe-fixes` - Critical issues: - Line length (88 chars) - Import sorting (I001) - Unused imports - Line wrapping: - Strings: use parentheses - Function calls: multi-line with proper indent - Imports: split into multiple lines 2. Type Checking - Tool: `uv run --frozen ty check .` - Requirements: - Explicit None checks for Optional - Type narrowing for strings - Version warnings can be ignored if checks pass 3. Pre-commit - Runs: on git commit - Run Format, Lint, Type Check & Test ## Error Resolution 1. CI Failures - Fix order: 1. Formatting 2. Type errors 3. Linting - Type errors: - Get full line context - Check Optional types - Add type narrowing - Verify function signatures 2. Common Issues - Line length: - Break strings with parentheses - Multi-line function calls - Split imports - Types: - Add None checks - Narrow string types - Match existing patterns - Pytest: - If the tests aren't finding the anyio pytest mark, try adding PYTEST_DISABLE_PLUGIN_AUTOLOAD="" to the start of the pytest run command eg: `PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest tests` 3. Best Practices - Check git status before commits - Run formatters before type checks - Keep changes minimal - Follow existing patterns - Document public APIs - Test thoroughly