mcp-json-yaml-toml AGENTS.md

MCP JSON/YAML/TOML Server - AI Agent Instructions

AI agents working in this repository follow these instructions for consistency, quality, and architectural integrity.

---

Project Context

Purpose: MCP server for advanced JSON/YAML/TOML manipulation using yq

Stack: Python 3.11-3.12+, FastMCP, uv, hatchling

Core Components:

• yq_wrapper.py - Local binary management
• schemas.py - Schema discovery
• lmql_constraints.py - LMQL constraint validation

Design Principles:

• 100% local processing (no API keys required)
• High-fidelity format preservation (comments, anchors, whitespace)
• Unified tools with parameters (avoid tool proliferation)
• Cursor-based pagination (10KB chunks for large files)

---

Linting Philosophy

<linting_principles>

Linting errors indicate deeper issues in architecture, type flow, or logic. Address root causes rather than suppressing symptoms.

Resolution Hierarchy:

1. Structural/type problems → Fix architecture or type annotations
2. Formatting/style → Use automated tools (ruff format, prettier)
3. True false positives → Document why before suppressing

Suppression Usage:

• Acceptable: Vendored code, intentional examples, platform-specific constraints
• Unacceptable: Structural problems, type errors, logic issues

Reason: Suppressions (# type: ignore, # noqa) hide technical debt. Fixing root causes improves system health.

</linting_principles>

---

Development Workflow

Environment Setup

uv sync  # Install dependencies and dev-tools

Dependency Management

uv add <package>          # Add runtime dependency
uv add --dev <package>    # Add dev dependency
uv remove <package>       # Remove dependency

uv add/remove handles version resolution, lockfile updates, and installation atomically. Manual pyproject.toml edits bypass dependency resolution and cause inconsistent environments.

Verification Protocol

<verification_workflow>

After editing files, verify only changed files (surgical verification prevents diff pollution):