syzygy-mcp-layer

One command. Works everywhere. Zero manual setup.

MCP quality layer that maximizes output from any model in agentic AI coding tools — without changing your workflow.

npx syzygy-mcp-layer

What is this?

Modern agentic AI tools (Claude Code, Gemini CLI, Cursor, etc.) are powerful but suffer from output degradation when using cheaper models (Flash, Haiku).

syzygy-mcp-layer (a "syzygy" is an alignment of celestial bodies — here, aligning your AI agent with top-tier logic) acts as a high-quality "alignment" layer that sits between you and your AI tool. It forces cheap models to follow a rigorous, quality-assured engineering workflow, producing outputs indistinguishable from expensive, latency-heavy models without changing the underlying AI tool.

It installs as an MCP server that your agent calls automatically to enforce quality, verification, and reflection at every step.

Features

• Auto-detect — scans for Claude Code, Gemini CLI, Cursor, OpenCode, VS Code
• One command install — npx syzygy-mcp-layer handles everything
• SSE daemon — persistent background process, near-zero latency per call
• Enable/disable — toggle per-tool or globally
• 3-layer verifier — syntax → type check → linting → test runner → semantic self-eval
• Prompt compiler — transforms raw tasks into optimized, structured prompts
• Task decomposer — breaks complex tasks into atomic, verifiable sub-tasks
• Reflection loop — targeted error feedback with circuit breaker (max 2 retries)
• Context pruner — trims codebase context to only what's relevant (token budget)
• Few-shot cache — learns from successful tasks, injects examples into future prompts
• No model changes — works with whatever model your tool is using

Supported Tools

| Tool | Auto-detect | MCP Config | |---|---|---| | Claude Code | ✅ claude binary / ~/.claude | claude mcp add --transport sse | | Gemini CLI | ✅ gemini binary / ~/.gemini | ~/.gemini/settings.json | | Cursor | ✅ cursor binary / ~/.cursor | ~/.cursor/mcp.json | | OpenCode | ✅ opencode binary / ~/.opencode | ~/.opencode/config.json | | VS Code + Copilot | ✅ code binary + user dir | settings.json → github.copilot.mcp.servers |

Requirements

| Requirement | Version | Notes | |---|---|---| | Node.js | 18+ | For npx — almost certainly already installed | | Python | 3.10+ | For the MCP server — auto-detected | | Bun | any | Optional — used as runtime if available |

Python packages (mcp, pyyaml, ruff, mypy) are installed automatically.

Install & Usage

First run — auto setup everything

npx syzygy-mcp-layer

What happens:

1. Scans your system for installed AI coding tools
2. Checks Python 3.10+ is available
3. Installs Python dependencies automatically
4. Starts background SSE daemon on port 3141
5. Registers http://localhost:3141/sse in each detected tool's MCP config
6. Copies workflow instruction files (CLAUDE.md, GEMINI.md, etc.)
7. Seeds the few-shot cache with baseline examples
8. Prints a summary with next steps

After install: restart your AI tool, then call health_check() to confirm.

All commands

# Setup
npx syzygy-mcp-layer                        # Auto: detect + install + start + register all
npx syzygy-mcp-layer enable                 # Start daemon + register all detected tools
npx syzygy-mcp-layer enable --claude-code   # Register Claude Code only
npx syzygy-mcp-layer enable --gemini-cli --cursor  # Register multiple specific tools

# Teardown
npx syzygy-mcp-layer disable                # Stop daemon + unregister all
npx syzygy-mcp-layer disable --cursor       # Remove Cursor only (daemon keeps running)

# Daemon control
npx syzygy-mcp-layer start                  # Start daemon only (no registration change)
npx syzygy-mcp-layer stop                   # Stop daemon only (no unregistration)
npx syzygy-mcp-layer restart                # Restart daemon (applies after Python changes)

# Info & maintenance
npx syzygy-mcp-layer status                 # Show daemon status + registered/detected tools
npx syzygy-mcp-layer update                 # Reinstall Python deps + re-seed cache + restart

Tool flags

| Flag | Tool | |---|---| | --claude-code | Claude Code | | --gemini-cli | Gemini CLI | | --cursor | Cursor | | --opencode | OpenCode | | --vscode-copilot | VS Code + GitHub Copilot | | --all | All detected tools |

Other flags

| Flag | Default | Description | |---|---|---| | --port <n> | 3141 | HTTP port for SSE daemon |

Quality & Performance

The quality and reliability of syzygy-mcp-layer are measured through rigorous automated benchmarks and manual inspections.

Benchmark Summary

| Task Scenario | Complexity | Avg Latency | Reflections | Success Rate | | :--- | :---: | :---: | :---: | :---: | | Simple: Hello World | Medium | 3287ms | 1 | 100% | | Medium: Fibonacci | Medium | 481ms | 0 | 100% | | Complex: JWT Auth | Medium | 2470ms | 0 | 100% | | Total Average | - | 2079ms | 0.33 | 100% |

• Full Automated Benchmark Report — Detailed latency, reflection cycles, and task completion metrics.
• Manual Evaluation Report — MCP Inspector tool schema and live verification logs.

Architecture

npx syzygy-mcp-layer
       │
       ├── src/detect.js    Auto-scan: check binaries + config dirs
       ├── src/deps.js      Python 3.10+ check + pip install
       ├── src/daemon.js    Spawn detached SSE server (PID file management)
       ├── src/register.js  Write MCP SSE config to each tool's settings
       └── src/skills.js    Copy instruction files to tool-specific locations
              │
              ▼
    python/server.py        FastMCP server (stdio + SSE dual transport)
    python/core/
      ├── classifier.py     Heuristic complexity: simple / medium / complex
      ├── compiler.py       Prompt optimizer (role anchor, constraints, schema, few-shot)
      ├── decomposer.py     Task → atomic sub-tasks with strategy detection
      ├── context_manager.py Prune context by relevance + token budget
      ├── verifier.py       Layer 1 (ast/mypy/ruff/tsc/govet) + Layer 2 (pytest) + Layer 3 (semantic)
      ├── reflection.py     Targeted reflection + circuit breaker (max 2 loops)
      └── cache.py          ChromaDB few-shot cache (fallback: keyword matching)

How the agent uses the tools

Once registered, your agent reads the skill instruction file (CLAUDE.md, GEMINI.md, etc.) and follows this workflow automatically on every coding task:

User: "build JWT auth endpoint"
          │
          ▼
   analyze_task()        ← classify complexity
          │
          ▼ (if complex)
   decompose_task()      ← break into sub-tasks
          │
          ▼
   compile_prompt()      ← optimize prompt (role, constraints, few-shot)
          │
          ▼ (if large context)
   prune_context()       ← trim to token budget
          │
          ▼
   <agent generates code>
          │
          ▼
   verify_code()         ← Layer 1: syntax/types/lint → Layer 2: tests → Layer 3: semantic
          │
     PASS │ FAIL
          │    │
          │    ▼
          │  inject_reflection()   ← targeted error feedback (max 2x)
          │    │
          │    └──────────────────► escalate if still failing
          │
          ▼
   add_example()         ← cache for future similar tasks

MCP Tools Reference

health_check()

Verify the server is running and all components are functional.

{
  "status": "ok",
  "components": { "classifier": "ok", "compiler": "ok", "verifier": "ok", ... },
  "optional_deps": { "chromadb": false, "tiktoken": false, "ruff": true, "mypy": true },
  "cache_size": 9
}

analyze_task(task)

Classify task complexity and get a routing recommendation.

{
  "complexity": "complex",
  "recommendation": "Use decompose_task FIRST...",
  "matched_complex_signals": ["from scratch", "distributed"],
  "word_count": 12
}

decompose_task(task, language, framework)

Break a complex task into atomic, verifiable sub-tasks.

{
  "strategy": "auth_system",
  "sub_tasks": [
    { "id": "T01", "title": "Define user/session data models", "depends_on": [], "verifier_hint": "..." },
    { "id": "T02", "title": "Implement token generation (JWT)", "depends_on": ["T01"], "verifier_hint": "..." }
  ],
  "execution_order": ["T01", "T02", "T03", ...]
}

compile_prompt(task, language, framework, constraints, context_snippet)

Build an optimized, structured prompt.

Returns a prompt string with: role anchoring, numbered constraints, explicit output schema, 1-2 few-shot examples from cache.

prune_context(context_chunks, task, max_tokens)

Reduce codebase context to only what's relevant.

{
  "pruned_context": "...",
  "original_chunks": 24,
  "retained_chunks": 3,
  "estimated_tokens": 487
}

verify_code(code, language, task_description, test_code)

Full 3-layer verification pipeline.

| Layer | What it checks | Cost | |---|---|---| | 1 | Syntax (ast/tsc/go vet) + types (mypy/tsc) + linting (ruff/eslint) | Zero (deterministic) | | 2 | Test runner (pytest) — only if test_code provided | Zero | | 3 | Semantic — returns structured prompt for agent to self-evaluate | Zero (agent's own model) |

{
  "passed": true,
  "layer_reached": 3,
  "errors": [],
  "warnings": ["Lint: line too long"],
  "semantic_eval_prompt": "[SEMANTIC VERIFICATION REQUEST]...",
  "summary": "✅ All checks passed (through Layer 3)"
}

inject_reflection(task_id, failed_output, errors)

Build targeted reflection prompt after verification failure.

{
  "prompt": "[Attempt 1] Your previous output has 2 issue(s):\n  - SyntaxError...",
  "attempt": 1,
  "escalate": false,
  "escalation_msg": ""
}

Circuit breaker: after max_reflection_loops (default: 2), escalate: true is returned with guidance to decompose or clarify.

add_example(task, solution, language, tags) / search_examples(task, language, top_k)

Manage the few-shot cache. Successful solutions are cached and injected into future similar prompts.

Enable / Disable Lifecycle

npx syzygy-mcp-layer enable
    │
    ├─ daemon starts (port 3141, detached background process)
    ├─ MCP config written to each tool
    └─ skill files copied (CLAUDE.md, GEMINI.md, etc.)

npx syzygy-mcp-layer disable
    │
    ├─ MCP config entries removed from each tool
    └─ daemon stopped (if no tools remain registered)

npx syzygy-mcp-layer disable --cursor    ← remove Cursor only
    │
    ├─ Cursor MCP config entry removed
    └─ daemon keeps running (other tools still registered)

State is persisted in ~/.syzygy-mcp-layer/state.json. The daemon PID is tracked in ~/.syzygy-mcp-layer/daemon.pid.

Configuration

Edit ~/.syzygy-mcp-layer/python/config/config.yaml:

complexity:
  complex_threshold: 2      # how many complex signals trigger "complex"

verifier:
  max_reflection_loops: 2   # circuit breaker — max retries before escalate

context:
  default_max_tokens: 3000  # context budget per prompt
  relevance_threshold: 0.20 # keyword overlap threshold (0–1)

cache:
  top_k: 2                  # few-shot examples injected per task

Troubleshooting

Daemon not starting

npx syzygy-mcp-layer status
cat ~/.syzygy-mcp-layer/logs/daemon.log

Tool not detecting my editor

npx syzygy-mcp-layer enable --claude-code   # explicit registration

Python not found

python3 --version   # needs 3.10+

Install: python.org/downloads

Reset everything from scratch

npx syzygy-mcp-layer disable
rm -rf ~/.syzygy-mcp-layer
npx syzygy-mcp-layer

Verify tools are registered

npx syzygy-mcp-layer status

Then in your AI tool, call:

health_check()

Development

git clone https://github.com/RizkiRdm/syzygy-mcp-layer.git
cd syzygy-mcp-layer

# Install Python deps
pip install -r python/requirements.txt

# Run Python tests
python -m unittest discover -s tests -p "test_*.py" -v

# Lint Python
ruff check python/core/ python/server.py

# Syntax check JS
node --check bin/cli.js src/*.js

# Seed cache manually
python python/seed_cache.py

# Start server manually (stdio)
python python/server.py

# Start server manually (SSE)
python python/server.py --transport sse --port 3141 --debug

Project Structure

syzygy-mcp-layer/
├── bin/
│   └── cli.js                  ← npx entry point
├── src/
│   ├── utils.js                ← shared helpers, colors, file I/O
│   ├── detect.js               ← auto-detect installed AI tools
│   ├── deps.js                 ← Python dependency checker/installer
│   ├── daemon.js               ← SSE daemon process manager
│   ├── register.js             ← MCP config writer per tool
│   └── skills.js               ← skill file installer per tool
├── python/
│   ├── server.py               ← FastMCP server (stdio + SSE)
│   ├── seed_cache.py           ← seed few-shot cache with examples
│   ├── requirements.txt
│   ├── config/
│   │   └── config.yaml         ← tunable parameters
│   └── core/
│       ├── classifier.py       ← heuristic complexity classifier
│       ├── compiler.py         ← prompt optimizer
│       ├── decomposer.py       ← task decomposer
│       ├── context_manager.py  ← context pruner
│       ├── verifier.py         ← 3-layer verifier
│       ├── reflection.py       ← reflection injector + circuit breaker
│       └── cache.py            ← few-shot cache (ChromaDB / keyword fallback)
├── skills/
│   ├── CLAUDE.md               ← workflow instructions for Claude Code
│   ├── GEMINI.md               ← workflow instructions for Gemini CLI
│   ├── skill.md                ← generic (OpenCode, etc.)
│   ├── .cursorrules            ← Cursor rules format
│   └── copilot-instructions.md ← GitHub Copilot instructions
├── tests/
│   ├── test_core.py            ← 39 unit tests (core modules)
│   ├── test_cache.py           ← 20 cache tests (KeywordBackend + FewShotCache)
│   └── test_integration.py     ← 15 end-to-end workflow tests
└── package.json

Uninstall

npx syzygy-mcp-layer disable    # unregister all tools + stop daemon
rm -rf ~/.syzygy-mcp-layer      # remove data, cache, logs

License

MIT — RizkiRdm