mcp-json-yaml-toml

Extract specific data, filter content, or transform structure without modification.

Use when you need to extract specific data, filter content, or transform the structure of a JSON, YAML, or TOML file without modifying it.

Output contract: Returns {"success": bool, "result": Any, "format": str, "file": str, ...}. Side effects: None (read-only). Failure modes: FileNotFoundError if file missing. ToolError if format disabled or query fails.

Get, set, or delete data in JSON, YAML, or TOML files.

Use when you need to get, set, or delete specific values or entire sections in a structured data file.

Output contract: Returns {"success": bool, "result": Any, "file": str, ...}. Side effects: Modifies file on disk if operation is 'set' or 'delete'. Failure modes: FileNotFoundError if file missing. ToolError if format disabled or invalid JSON.

Operations:

• get: Retrieve data, schema, or structure

• set: Update/create value at key_path (always writes to file)

• delete: Remove key/element at key_path (always writes to file)

Unified schema operations tool.

Actions:

• validate: Validate file syntax and optionally against schema

• scan: Recursively search for schema directories

• add_dir: Add custom schema directory

• add_catalog: Add custom schema catalog

• associate: Bind file to schema URL or name

• disassociate: Remove file-to-schema association

• list: Show current schema configuration

Examples:

• action="validate", file_path="config.json"

• action="associate", file_path=".gitlab-ci.yml", schema_name="gitlab-ci"

• action="disassociate", file_path=".gitlab-ci.yml"

• action="list"

Convert file format.

Use when you need to transform a file from one format (JSON, YAML, TOML) to another.

Output contract: Returns {"success": bool, "result": str, ...} or writes to file. Side effects: Writes to output_file if provided. Failure modes: FileNotFoundError if input missing. ToolError if formats same or conversion fails.

Merge two files into a single deep-merged configuration.

Performs a deep merge where values from the second (overlay) file override or extend those in the first (base) file. If output_file is provided the merged result is written to that path; otherwise the merged content is returned in the response.

Parameters: file_path1 (str): Path to the base file. file_path2 (str): Path to the overlay file whose values override the base. output_format (str | None): Desired output format: "json", "yaml", or "toml". Defaults to the format of the first file. output_file (str | None): Optional path to write the merged output. When omitted, merged content is returned.

Returns: dict: A payload describing the merge. On success includes "success": True, "file1", "file2", "output_format", and either "result" (merged content) or "output_file" (written path).

Raises: ToolError: If an input file is missing, its format is not enabled, the output format is invalid, or the merge fails.

Validate a value against an LMQL-style constraint.

Use this tool to check if a value satisfies a constraint before using it in other operations. Supports partial validation - can tell if an incomplete input could still become valid.

Output contract: Returns {"valid": bool, "error": str?, "is_partial": bool?, ...}. Side effects: None (read-only validation). Failure modes: ToolError if constraint name unknown.

Available constraints:

• YQ_PATH: Valid yq path (e.g., '.users[0].name')

• YQ_EXPRESSION: Valid yq expression with pipes (e.g., '.items | length')

• CONFIG_FORMAT: Valid format ('json', 'yaml', 'toml', 'xml')

• KEY_PATH: Dot-separated key path (e.g., 'config.database.host')

• INT: Valid integer

• JSON_VALUE: Valid JSON syntax

• FILE_PATH: Valid file path syntax

Return a list of all registered LMQL constraints with their metadata.

Returns: result (dict): A dictionary with keys: - "constraints": a list of constraint objects; each object includes a "name" key and the constraint's definition fields (e.g., "description", any other metadata). - "usage": a string describing how to validate a value against a constraint (e.g., call constraint_validate(constraint_name, value)).