mcp-json-yaml-toml copilot-instructions.md

Copilot Instructions - mcp-json-yaml-toml

Repository Overview

mcp-json-yaml-toml is a token-efficient, schema-aware MCP (Model Context Protocol) server for safely reading and modifying JSON, YAML, and TOML files. It provides AI assistants with structured data manipulation tools that preserve comments and formatting while enforcing schema validation.

• Size: ~2.4MB, 28 Python files
• Stack: Python 3.11-3.14, FastMCP, uv package manager, hatchling build backend
• Architecture: 100% local processing, no API keys required
• Cross-Platform: Works seamlessly on Windows, Linux, and macOS (any system where yq binary is supported)
• Key Features: yq-based transformations, SchemaStore.org integration, LMQL constraint validation

Prerequisites & Setup

Required Tools

• Python: 3.11-3.14 (CI tests against 3.11, 3.12, 3.13, 3.14)
• uv: Package manager (replaces pip/poetry/pipenv)
• Node.js: Required for markdown/prettier linting (npx commands)

Initial Setup

ALWAYS run this first after cloning:

uv sync  # Installs all dependencies and dev-tools (~30-60 seconds)

This command:

• Creates .venv/ virtual environment
• Installs all Python dependencies from pyproject.toml
• Installs dev dependencies (pytest, ruff, ty, prek)
• Is idempotent - safe to run multiple times

NEVER use pip install or bare python commands. Always use uv run <command>.

Validation Commands (CI Enforcement)

Recommended Approach: Use prek to run all validation checks in one command:

uv run prek run --files <file1> <file2>  # For specific files
uv run prek run --all-files               # For all files (use sparingly)

The prek tool automatically runs all the checks below in parallel. For debugging or CI reference, individual commands are listed:

Individual Validation Commands

These are automatically run by prek but can be executed separately if needed:

1. Code Formatting

uv run ruff format --check