forge-lcdl

Handbook

MCP sidecar (LCDL in Cursor)

Connect forge-lcdl to Cursor (or any MCP client) via a local stdio server that exposes LCDL operations as tools. The cheap model can call lcdl.create_contract, lcdl.build_context_pack, lcdl.decompose, lcdl.verify…

Related: to use forge-lcdl as an MCP client (e.g. call Playwright MCP from Python scripts), see MCP-CLIENT.md.

What ships

Tool Purpose
lcdl.create_contract Load bundled ContractSpec (task_id, optional version). “Create” = in memory, not writing files.
lcdl.build_context_pack build_context_pack (task, repo_path, optional budget_chars).
lcdl.decompose create_patch_units (task_description, optional context_pack stub).
lcdl.verify verify_task_result in-process only (task_id, version, input, output).
lcdl.reduce_failure classify_failure + reduce_failure_to_repair from a failed verification_result dict.
lcdl.benchmark mode: dry_run (default) or run_offline (fake chat). live: true is rejected on this surface.
lcdl.graph_status parse_decision_pack + structure summary (decision_pack object).
lcdl.final_report proof_report_from_results / proof_report_to_dict.

Python API: each *_tool in forge_lcdl.integrations.mcp.tools accepts a dict and returns {"ok": bool, "data"?: ..., "error"?: ...}.

Install

From the forge-lcdl repo root:

pip install -e ".[dev,mcp]"

The core package stays dependency-free; mcp is optional and only needed to run the stdio server module.

Enable in Cursor

  1. Open forge-lcdl as the project (or set cwd to this repo).
  2. Copy .cursor/mcp.json.example to your user or project MCP config, or merge the lcdl-local entry into your existing MCP JSON.
  3. Adjust cwd to the forge-lcdl root and ensure PYTHONPATH includes src (the example sets PYTHONPATH to src relative to cwd).
  4. Restart Cursor or reload MCP servers after changes.

Use Cursor’s MCP documentation for where user-level vs project-level config lives in your build.

Entry point:

python3 -m forge_lcdl.integrations.mcp.server

If mcp is missing, the process prints a one-line pip install 'forge-lcdl[mcp]' hint and exits non-zero.

Logs and debugging

  • stderr from the server process (tool errors, import failures).
  • Cursor’s MCP / tools UI usually lists connected servers and recent calls.
  • Run tools directly in Python or pytest (see tests/test_mcp_tools.py) without Cursor.

Security

  1. Secrets in env vars only — never embed API keys or tokens in MCP JSON. Prefer process environment inherited by the stdio server.
  2. No .env files are read by the tool layer; do not ask tools to load dotenv into responses.
  3. No shell / arbitrary execution — verification is in-process schema checks only; benchmarks on this surface are offline unless you change the code.
  4. Review src/forge_lcdl/integrations/mcp/tools.py before exposing the server beyond your machine.
  5. Disable by removing lcdl-local from MCP config or toggling the server off in Cursor.

Disable

Remove or disable the lcdl-local server entry from MCP settings and restart Cursor.