---

version: 0.1.0 owner: delk73 lastReviewed: 2025-09-12

Synesthetic MCP

Lightweight Model Context Protocol (MCP) server for Synesthetic assets.
This repo adapts the canonical synesthetic-schemas into MCP resources and tools.

• Resources: schemas, examples (read-only, from SSOT).
• Tools: validation, diff (RFC6902 patch ops), backend population.
• Guards: enforce schema compliance before persistence.

System Context

flowchart LR
  FE["sdfk_fe_ts\n(TypeScript Frontend)"]
  BE["sdfk-backend\n(Python API & CRUD)"]
  MCP["synesthetic-mcp\n(Python MCP Adapter)"]
  RLHF["sdfk_rlhf\n(RLHF Asset Generation)"]
  SSOT["synesthetic-schemas\n(SSOT: Schemas + Codegen)"]

  FE --> |Consumes API| BE
  RLHF --> |Generates Assets via MCP| MCP
  MCP --> |Validates + Persists| BE
  SSOT --> |Submodule + Python pkg| MCP
  SSOT --> |TypeScript types| FE
  SSOT --> |Python models| BE

  style MCP fill:#444444,stroke:#ffffff,stroke-width:2px

Quick Setup

Option A: Nix + Poetry (full dev shell)

# Enter reproducible Nix shell (Python + Poetry pre-installed)
nix develop

# Install deps into local .venv/
poetry install

# Run tests
pytest

Option B: Fast path (pinned requirements, no resolver rodeos)

# Clean and bootstrap fresh venv
./install.sh

# Activate venv
source .venv/bin/activate

# Run tests
pytest -q

# Lint / type-check
ruff check .
mypy mcp/

The install.sh script installs from requirements.txt with exact pinned versions for deterministic, fast environment setup.

Structure

synesthetic-mcp/
  README.md
  requirements.txt     # Pinned dependencies (single source of truth for pip)
  install.sh           # Simple bootstrap script for reproducible env
  docs/
    mcp_spec.md        # Full spec for MCP v1 (resources, tools, error model)
  mcp/
    __init__.py
    core.py            # schema/example discovery
    validate.py        # validation helpers
    diff.py            # JSON Patch generation
    backend.py         # proxy client to backend
    stdio_main.py      # MCP stdio adapter
    http_main.py       # optional FastAPI adapter
  tests/
    test_validate.py
    test_diff.py
    test_tools.py
    fixtures/
      valid_asset.json
      invalid_asset.json
  meta/
    prompts/           # Canonical Codex/ChatGPT prompts used to spin up repo

Development

• MCP server is written in Python (>=3.11, tested on 3.11–3.13).
• Depends on generated Python models from synesthetic-schemas.
• Use FastAPI for HTTP adapter, or run via stdio for direct agent integration.
• Tests use pytest and golden fixtures.
• Reproducible dev environment provided via Nix flake; pip + requirements.txt for fast installs.

Spec

See docs/mcp_spec.md for the pinned v1 specification.

Status

✅ Spec pinned in docs/mcp_spec.md 🚧 Implementation scaffolding in progress