Synesthetic MCP

{
  "version": "v0.2.9",
  "spec_ref": "docs/mcp_spec.md#v0-2-9",
  "task": "Audit synesthetic-mcp repo state (v0.2.9 features, aligned to schemas v0.7.3)",
  "objective": "Verify implementation, tests, and docs match MCP Spec v0.2.9. Confirm TCP default mode, canonical host usage, environment-driven schema resolution, and governance compliance. Report Present/Missing/Divergent with evidence and regenerate AGENTS.md snapshot.",
  "constraints": {
    "style": "deterministic, terse, Markdown headings with bullets/tables",
    "rules": [
      "Present = implementation matches spec and is covered by tests/docs",
      "Missing = feature required by spec but not implemented",
      "Divergent = implemented but differs in behavior or naming",
      "All findings grounded in actual code/tests/docs (no speculation)",
      "Result and evidence must cite file and line/section explicitly",
      "Always overwrite meta/output/mcp_state.md and AGENTS.md with non-empty content",

      "Schema host/version (v0.2.9): Assets validated by MCP MUST include top-level \"$schema\" that starts with canonical host and version → \"https://delk73.github.io/synesthetic-schemas/schema/${LABS_SCHEMA_VERSION}/...\"; default LABS_SCHEMA_VERSION=0.7.3",
      "Schema resolution (v0.2.9): Resolver MUST support remote canonical URLs with optional local cache; reject path traversal; disallow implicit relative loads outside cache dir",
      "No legacy schema keys: Reject payloads using \"schema\" or \"$schemaRef\" with validation_failed at path=\"/$schema\"",
      "Env parity: LABS_SCHEMA_BASE and LABS_SCHEMA_VERSION MUST be read, logged at startup, and used in schema resolution",
      "Governance parity: MCP MUST align with synesthetic-schemas canonical URLs and validate that assets reference canonical $schema",

      "Transport compliance: STDIO MUST exist; Socket MUST support multi-client ordering; TCP MUST exist, be default, and enforce 1 MiB guard; HTTP/gRPC roadmap-only (Divergent if present)",
      "Default mode: MCP_MODE defaults to tcp when unset; up.sh MUST start container in TCP mode",
      "Payload cap: 1 MiB guard enforced across all methods and transports with failing test coverage",
      "Alias: method 'validate' MUST alias 'validate_asset' and log a deprecation warning",
      "Batching: validate_many MUST honor MCP_MAX_BATCH",
      "get_example: MUST return validation_failed when example invalid",
      "Determinism: Sorting for listings, diffs, and error ordering MUST be implemented and tested",
      "Security: Socket/TCP perms default to least-privilege; container runs non-root",
      "Process model: STDIO exits on stdin close; Socket/TCP log readiness; unlink/close on shutdown",
      "Logging: Ready/shutdown logs MUST include mode, path/host:port, schemas_base, schema_version, cache_dir (if any); timestamps ISO-8601; logs to stderr; stdout carries JSON-RPC frames only",
      "Signal handling: SIGINT/SIGTERM MUST yield exit codes -2 / -15",
      "Shutdown logging: MUST mirror ready fields and emit before process exit (no self-kill pre-empting logs)",
      "Ready file format: exactly '<pid> <ISO8601 timestamp>'",
      "Golden examples: MUST include list_schemas, get_schema, validate_asset + alias validate, get_example ok/invalid, diff_assets, malformed JSON-RPC",
      "Docs MUST include TCP client example using 'nc 127.0.0.1 8765' and document canonical host/version env variables",
      "Audit incomplete unless both output files non-empty"
    ],
    "sections": [
      "Summary of repo state",
      "Top gaps & fixes (3-5 bullets)",
      "Alignment with mcp_spec.md (table: Spec item → Status → Evidence)",
      "Transports",
      "STDIO entrypoint & process model",
      "Socket server (multi-client handling, perms, unlink, logs)",
      "TCP server (binding, perms, multi-client, shutdown logs)",
      "Lifecycle signals",
      "Shutdown logging invariant",
      "Ready file format",
      "Golden request/response examples",
      "Payload size guard",
      "Schema validation contract",
      "Schema resolver (remote/cached, traversal guards)",
      "Batching",
      "Determinism & ordering",
      "Logging hygiene (fields, ISO time, stderr separation)",
      "Container & health (non-root, probes)",
      "Environment variables (LABS_SCHEMA_BASE, LABS_SCHEMA_VERSION, MCP_MODE, MCP_HOST/PORT, MCP_MAX_BATCH)",
      "Documentation accuracy (canonical host/version, TCP nc example)",
      "Detected divergences",
      "Recommendations"
    ]
  },
  "scope": {
    "files": [
      "README.md",
      "docs/mcp_spec.md",
      "requirements.txt",
      "docker-compose.yml",
      "Dockerfile",
      "serve.sh",
      "up.sh",
      "down.sh",
      "mcp/**/*.py",
      "tests/**/*.py",
      "libs/synesthetic-schemas",
      "meta/",
      "AGENTS.md",
      ".github/workflows/**",
      ".env",
      ".env.example"
    ]
  },
  "output": {
    "paths": [
      "meta/output/mcp_state.md",
      "AGENTS.md"
    ],
    "format": "Markdown",
    "must_write": true,
    "stdout_optional": true
  },
  "exit_criteria": [
    "meta/output/mcp_state.md written and non-empty",
    "AGENTS.md snapshot updated and non-empty",
    "Spec v0.2.9 features mapped to Present/Missing/Divergent with evidence (file:line or section)",
    "LABS_SCHEMA_BASE and LABS_SCHEMA_VERSION read from env, logged, and used in code paths",
    "TCP mode confirmed default (up.sh starts MCP in TCP mode when MCP_MODE unset)",
    "Schema resolver supports canonical remote and cache modes; traversal blocked; no unintended local-relative loads",
    "All validated assets include top-level canonical $schema URL with version == LABS_SCHEMA_VERSION (default 0.7.3)",
    "STDIO, Socket, TCP behavior verified (multi-client ordering for Socket, logs for all, shutdown, lifecycle signals)",
    "Golden examples verified: list_schemas, get_schema, validate_asset + alias validate, get_example ok/invalid, diff_assets, malformed JSON-RPC",
    "Payload guard enforced (1 MiB) and verified by failing test",
    "validate_many honors MCP_MAX_BATCH",
    "Deterministic ordering verified (listings, diffs, error lists)",
    "Logging verified: mode, host/port, schemas_base, schema_version, cache_dir, ISO-8601 timestamps; stderr logs only; stdout JSON-RPC frames only",
    "Shutdown logs mirror ready fields and emit before exit (no pre-emptive self-kill)",
    "Ready file format '<pid> <ISO8601 timestamp>' verified",
    "Signal exit codes verified (-SIGINT, -SIGTERM)",
    "Container non-root verified (Dockerfile/compose)",
    "README/docs reflect canonical host/version env and include TCP 'nc 127.0.0.1 8765' example",
    "No legacy schema keys accepted; validation_failed on missing $schema (path='/$schema')"
  ]
}