version: v0.2.7 owner: delk73 lastReviewed: 2025-09-12

Synesthetic MCP

Minimal, deterministic MCP-style adapter exposing schemas, examples, validation, diff, and an optional backend-populate tool.

System Context

Features

• Schema and example discovery

• JSON Schema validation (Draft 2020-12)

• Batch validation via validate_many with MCP_MAX_BATCH (default 100)

• RFC6902 diff (add/remove/replace only)

• Backend population (optional via SYN_BACKEND_URL)

• Canonical STDIO JSON-RPC loop with optional Unix-domain socket transport (MCP_ENDPOINT=socket) and TCP transport (MCP_ENDPOINT=tcp, MCP_HOST, MCP_PORT)

• Per-request 1 MiB payload guard enforced before parsing across STDIO, socket, and TCP transports

• Deprecated validate alias remains available but logs a warning; prefer validate_asset

• Strict asset contract: top-level $schema is required and legacy schema/$schemaRef keys are rejected (v0.2.8)

Quickstart

1. Install deps: pip install -r requirements.txt && pip install -e .

2. Initialize schemas/examples: git submodule update --init --recursive.

3. Serve via Compose: docker compose up serve (runs the transport, logs mcp:ready mode=<endpoint> with ISO-8601 timestamps, and exposes /tmp/mcp.ready for health checks).

4. Or run the helper: ./up.sh builds the image and starts the serve service in the background; follow with docker compose logs -f serve if you want to tail logs.

5. Validate an asset locally: python -m mcp --validate libs/synesthetic-schemas/examples/SynestheticAsset_Example1.json.

Structure

Development

• Python >= 3.11

• Install deps (minimal): pip install -r requirements.txt

  • Minimal deps: jsonschema, httpx, pytest

  • Optional extras: referencing (enhanced JSON Schema refs; import is optional)

  • Dev (optional): ruff, mypy

• Import check: python -c "import mcp; print(mcp.__version__)"

• Run tests: pytest -q

• Runtimes:

  • python -m mcp (STDIO by default; set MCP_ENDPOINT=socket for the Unix-domain socket server or MCP_ENDPOINT=tcp for TCP. Logs mcp:ready mode=<endpoint> with ISO-8601 timestamps on readiness).

  • python -m mcp.stdio_main (invoke the STDIO loop directly when embedding).

Dependencies

• Runtime: jsonschema, httpx

• Tests: pytest

• Dev (optional): ruff, mypy

• Extras (optional): referencing (ref handling performance/behavior)

Environment

.env.example captures these defaults for quick copying into local shells or Compose.

Environment Discovery

• SYN_SCHEMAS_DIR and SYN_EXAMPLES_DIR override paths when set.

• Otherwise, schemas/examples are loaded from the libs/synesthetic-schemas submodule.

• If neither is available, listings are empty and get operations return not found (no fixture fallback).

Submodule (SSOT)

Authoritative schemas/examples live at libs/synesthetic-schemas (git submodule).

Order of discovery used by the adapter:

1. SYN_SCHEMAS_DIR and SYN_EXAMPLES_DIR if set

2. libs/synesthetic-schemas/jsonschema and libs/synesthetic-schemas/examples if present

3. If neither exists, listings are empty and get operations return not found

Initialize the submodule:

Update the submodule to the latest published commit (0fdc842 as of this audit):

After checking out the new commit you can create a commit in the main repository, for example git commit -m "chore: bump synesthetic-schemas to 0fdc842".

Schema Aliases (Nested Assets)

• synesthetic-asset → canonical schema (flat).

• nested-synesthetic-asset → alias for assets with components inlined.

• All component types may be embedded (shader, tone, haptic, control, modulation, rule bundle).

• Alias validation loads the canonical synesthetic-asset schema.

• Examples SynestheticAsset_Example*.json are treated as nested-synesthetic-asset.

• Assets MUST declare their validating schema via top-level $schema; legacy schema or $schemaRef keys are rejected.

• Tests use the nested alias; submodule is the single source of truth.

Error Model

• Validation failed: { ok:false, reason:'validation_failed', errors:[{ path, msg }] }

• Backend error: { ok:false, reason:'backend_error', status, detail }

• Unsupported tool/resource: { ok:false, reason:'unsupported', detail }

• Network errors map to backend_error with status:503 and a brief detail.

• Payload too large (>1 MiB on STDIO/socket/TCP): { ok:false, reason:'validation_failed', errors:[{ path:'', msg:'payload_too_large' }] }

CLI Usage

• Exit code 0: validation succeeded.

• Exit code 1: validation failed (payload includes reason: validation_failed).

• Exit code 2: input errors (file missing, unreadable, or invalid JSON).

Docker

Build and run tests in a container:

Notes:

• docker-compose.yml passes through env if set; there are no defaults to fixtures. The adapter’s own discovery logic picks the right source.

• No backend service is started by compose; backend calls are disabled unless SYN_BACKEND_URL is set.

Serving Locally

• docker compose up serve builds the image, starts python -m mcp, waits for /tmp/mcp.ready, and keeps logs attached.

• ./up.sh builds the image and starts the serve service in detached mode; run docker compose logs -f serve to follow output after startup.

• STDIO remains the default; set MCP_ENDPOINT=socket to listen on the Unix-domain socket path, or MCP_ENDPOINT=tcp (optionally with MCP_HOST/MCP_PORT) to expose a TCP listener.

• Requests above 1 MiB (UTF-8 bytes) are rejected before parsing with payload_too_large on STDIO, socket, and TCP (see tests/test_stdio.py, tests/test_socket.py, and tests/test_tcp.py).

Spec

See docs/mcp_spec.md for deterministic IO contracts and limits.

Status

✅ Spec pinned in docs/mcp_spec.md ✅ Minimal implementation with tests

Validating it

Quick host check with

Paste this request:

You should get a JSON response with available schemas.

Labs connection env (pointing to the MCP container via TCP):

Run Labs against it: