qcoder 0.5.0a6__tar.gz → 0.5.0a7__tar.gz

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
 
+## 0.5.0a7
+
+- Add local read-only qCoder MCP for Cursor-oriented Explorer Launch workflows.
+- Add MCP tools for local circuit analysis, context-pack generation, counts review, bounded findings, claim boundaries, next checks, and share-safe artifact sanitization.
+- Document the Evidence-Grounded Coding Loop and preserve the manual artifact handoff as launch-required even when local MCP is available.
+- Harden Windows-created inputs by accepting UTF-8 BOM in QASM and JSON paths used by local analysis/review.
+- Improve `qcoder review` error guidance for malformed JSON and Qiskit counts input.
+- Add MCP, share-safe, claim-boundary, and Windows/QASM/Qiskit tests plus release-check MCP stdio rehearsal.
+- Preserve launch boundaries: no public hosted MCP claim, no live service calls from MCP, no token requirement, no autonomous code modification, no QPU/simulator submission, and no runtime/fidelity/backend/QPU/correctness/advantage claims.
+- This is release-candidate preparation only until separately published.
+
+
 ## 0.5.0a6
 
 - Add share-safe / redacted artifact mode for artifacts intended for ChatGPT, Cursor, email, GitHub issues, or support threads.

{qcoder-0.5.0a6/src/qcoder.egg-info → qcoder-0.5.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a6
+Version: 0.5.0a7
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -15,6 +15,8 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -40,6 +42,7 @@ The current public local path is **qCoder OSS**. OSS commands run locally and do
 - `qcoder batch`
 - `qcoder context`
 - `qcoder review`
+- `qcoder mcp` (local read-only Cursor MCP tools)
 - `qcoder explorer` (Explorer Beta account-backed status/demo/evidence checks)
 - `qcoder student` (temporary compatibility alias for Explorer Beta)
 - `qcoder pro` (archived pilot/bootstrap client contract; non-confidential local plumbing only, not a current public product path)
@@ -87,6 +90,14 @@ qcoder review --counts-json counts.json --format qiskit_counts --preflight-json
 
 Share-safe mode is designed for safer sharing: it redacts local paths and token/header-like strings, adds `share_safe=true`, and marks raw QASM/local paths/tokens as not included. Review artifacts before sharing; this is not a guarantee that all sensitive project content has been removed.
 
+Local Cursor MCP:
+
+```bash
+qcoder mcp serve
+```
+
+The MCP server uses explicit user-selected local inputs only. It reads, inspects, explains, bounds, and recommends; it does not execute circuits, modify user code, read arbitrary files, call live services, or require tokens. See [Explorer Evidence-Grounded Coding Loop](examples/08_explorer_evidence_grounded_coding_loop.md) for the manual artifact loop, Cursor MCP setup, and claim boundaries.
+
 Explorer Beta compatibility checks and archived Pro bootstrap:
 
 ```bash

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/README.md

@@ -10,6 +10,7 @@ The current public local path is **qCoder OSS**. OSS commands run locally and do
 - `qcoder batch`
 - `qcoder context`
 - `qcoder review`
+- `qcoder mcp` (local read-only Cursor MCP tools)
 - `qcoder explorer` (Explorer Beta account-backed status/demo/evidence checks)
 - `qcoder student` (temporary compatibility alias for Explorer Beta)
 - `qcoder pro` (archived pilot/bootstrap client contract; non-confidential local plumbing only, not a current public product path)
@@ -57,6 +58,14 @@ qcoder review --counts-json counts.json --format qiskit_counts --preflight-json
 
 Share-safe mode is designed for safer sharing: it redacts local paths and token/header-like strings, adds `share_safe=true`, and marks raw QASM/local paths/tokens as not included. Review artifacts before sharing; this is not a guarantee that all sensitive project content has been removed.
 
+Local Cursor MCP:
+
+```bash
+qcoder mcp serve
+```
+
+The MCP server uses explicit user-selected local inputs only. It reads, inspects, explains, bounds, and recommends; it does not execute circuits, modify user code, read arbitrary files, call live services, or require tokens. See [Explorer Evidence-Grounded Coding Loop](examples/08_explorer_evidence_grounded_coding_loop.md) for the manual artifact loop, Cursor MCP setup, and claim boundaries.
+
 Explorer Beta compatibility checks and archived Pro bootstrap:
 
 ```bash

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.5.0a6"
+version = "0.5.0a7"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,6 +23,8 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
 ]
 dependencies = ["numpy"]
 

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.5.0a6"
+__version__ = "0.5.0a7"
 file = __file__

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/cli.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+from json import JSONDecodeError
 from pathlib import Path
 
 from qcoder.pipelines.analyze import analyze_qasm
@@ -284,14 +285,29 @@ def _cmd_review(argv: list[str]) -> int:
     )
     args = p.parse_args(argv)
 
-    write_execution_review(
-        counts_json=args.counts_json,
-        counts_format=args.counts_format,
-        preflight_json=args.preflight_json,
-        out_json=args.out_json,
-        out_md=args.out_md,
-        share_safe=args.share_safe,
-    )
+    try:
+        write_execution_review(
+            counts_json=args.counts_json,
+            counts_format=args.counts_format,
+            preflight_json=args.preflight_json,
+            out_json=args.out_json,
+            out_md=args.out_md,
+            share_safe=args.share_safe,
+        )
+    except JSONDecodeError as exc:
+        print(
+            f"qcoder review: input JSON could not be parsed at line {exc.lineno}, column {exc.colno}. "
+            "Check that the counts/preflight file is UTF-8 JSON.",
+            file=sys.stderr,
+        )
+        return 2
+    except ValueError as exc:
+        print(
+            f"qcoder review: {exc}. For Qiskit counts, use --format qiskit_counts with a JSON object "
+            'like {"00": 10, "11": 6} or {"counts": {"00": 10, "11": 6}}.',
+            file=sys.stderr,
+        )
+        return 2
     json_label = "<redacted-local-path>" if args.share_safe else args.out_json
     md_label = "<redacted-local-path>" if args.share_safe else args.out_md
     print(f"Wrote execution review JSON to {json_label}", file=sys.stderr)
@@ -299,6 +315,30 @@ def _cmd_review(argv: list[str]) -> int:
     return 0
 
 
+def _cmd_mcp(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        prog="qcoder mcp",
+        add_help=True,
+        description=(
+            "Local read-only qCoder MCP for Cursor. Uses explicit user-selected inputs only; "
+            "does not execute circuits, modify code, use tokens, or call live services."
+        ),
+    )
+    sub = p.add_subparsers(dest="mcp_command")
+    p_serve = sub.add_parser("serve", help="Serve qCoder tools over MCP stdio.")
+    p_serve.set_defaults(mcp_command="serve")
+    args = p.parse_args(argv)
+    if args.mcp_command is None:
+        p.print_help()
+        return 0
+    if args.mcp_command == "serve":
+        from qcoder.mcp.server import serve_stdio
+
+        return serve_stdio()
+    p.print_help()
+    return 0
+
+
 def _run_pro_preview_demo_check(
     *,
     base_url_override: str | None,
@@ -1200,14 +1240,15 @@ def _cmd_pro(argv: list[str]) -> int:
 
 def _print_root_help() -> None:
     print(
-        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,explorer,pro,student} ...\n\n"
+        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,mcp,explorer,pro,student} ...\n\n"
         "Quantum circuit analysis CLI.\n\n"
         "positional arguments:\n"
-        "  {analyze,batch,context,review,explorer,pro,student}  subcommand\n\n"
+        "  {analyze,batch,context,review,mcp,explorer,pro,student}  subcommand\n\n"
         "  analyze          Analyze a QASM file (feature extraction + metadata + run config).\n"
         "  batch            Batch extract a directory to JSONL (requires --out).\n"
         "  context          Build deterministic preflight context artifacts.\n"
         "  review           Build deterministic execution review artifacts from counts.\n"
+        "  mcp              Serve local read-only qCoder tools for Cursor over MCP stdio.\n"
         "  explorer         Explorer Beta status/demo/evidence checks.\n"
         "  pro              Archived Pro client-contract shell (not current public product).\n"
         "  student          Compatibility alias for Explorer Beta checks.\n\n"
@@ -1239,6 +1280,8 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_context(rest)
     if cmd == "review":
         return _cmd_review(rest)
+    if cmd == "mcp":
+        return _cmd_mcp(rest)
     if cmd == "explorer":
         return _cmd_explorer(rest)
     if cmd == "pro":
@@ -1247,7 +1290,7 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_student(rest)
 
     print(
-        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, explorer, pro, or student)",
+        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, mcp, explorer, pro, or student)",
         file=sys.stderr,
     )
     print("Run `qcoder --help` for usage.", file=sys.stderr)

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/engines/feature_extraction/qasm2_regex_parser.py

@@ -193,5 +193,5 @@ def parse_qasm2_text(qasm_text: str, *, source_label: str | None = None) -> Circ
 
 def parse_qasm2_file(path: str) -> CircuitIR:
     p = Path(path)
-    text = p.read_text(encoding="utf-8", errors="replace")
+    text = p.read_text(encoding="utf-8-sig", errors="replace")
     return parse_qasm2_text(text)

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/explorer/derived_evidence.py

@@ -71,7 +71,7 @@ def _qcoder_version() -> str:
 
 def _load_context_json(path: str) -> dict[str, Any]:
     try:
-        loaded = json.loads(Path(path).read_text(encoding="utf-8"))
+        loaded = json.loads(Path(path).read_text(encoding="utf-8-sig"))
     except json.JSONDecodeError as exc:
         raise ExplorerDerivedEvidenceRequestError("context JSON is not valid JSON") from exc
     if not isinstance(loaded, dict):

qcoder-0.5.0a7/src/qcoder/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Local read-only MCP helpers for qCoder Explorer Launch."""
+
+from qcoder.mcp.tools import call_tool, list_tools
+
+__all__ = ["call_tool", "list_tools"]

qcoder-0.5.0a7/src/qcoder/mcp/server.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, TextIO
+
+from qcoder.mcp.tools import call_tool, list_tools
+
+
+SERVER_INFO = {"name": "qcoder-local-read-only", "version": "0.1.0"}
+
+
+def serve_stdio(*, stdin: TextIO | None = None, stdout: TextIO | None = None) -> int:
+    in_stream = stdin or sys.stdin
+    out_stream = stdout or sys.stdout
+    for raw_line in in_stream:
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+            response = handle_request(request)
+        except Exception as exc:  # MCP server must answer JSON-RPC errors, not crash on bad input.
+            response = _error_response(None, -32603, str(exc))
+        if response is not None:
+            out_stream.write(json.dumps(response, separators=(",", ":"), sort_keys=True) + "\n")
+            out_stream.flush()
+    return 0
+
+
+def handle_request(request: dict[str, Any]) -> dict[str, Any] | None:
+    if not isinstance(request, dict):
+        return _error_response(None, -32600, "request must be a JSON object")
+    request_id = request.get("id")
+    method = request.get("method")
+    params = request.get("params") if isinstance(request.get("params"), dict) else {}
+
+    if method == "initialize":
+        return _result_response(
+            request_id,
+            {
+                "protocolVersion": params.get("protocolVersion", "2024-11-05"),
+                "capabilities": {"tools": {}},
+                "serverInfo": SERVER_INFO,
+                "instructions": (
+                    "Local read-only qCoder MCP. Uses explicit user-selected inputs only; "
+                    "does not execute circuits, modify code, use tokens, or call live services."
+                ),
+            },
+        )
+    if method == "notifications/initialized":
+        return None
+    if method == "tools/list":
+        return _result_response(request_id, {"tools": list_tools()})
+    if method == "tools/call":
+        name = params.get("name")
+        arguments = params.get("arguments")
+        if not isinstance(name, str):
+            return _error_response(request_id, -32602, "tools/call requires a string tool name")
+        if arguments is not None and not isinstance(arguments, dict):
+            return _error_response(request_id, -32602, "tools/call arguments must be an object")
+        try:
+            return _result_response(request_id, call_tool(name, arguments or {}))
+        except Exception as exc:
+            return _error_response(request_id, -32000, str(exc))
+    return _error_response(request_id, -32601, f"unknown method: {method}")
+
+
+def _result_response(request_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error_response(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="qcoder mcp serve")
+    parser.add_argument("serve", nargs="?", help=argparse.SUPPRESS)
+    args = parser.parse_args(argv)
+    _ = args
+    return serve_stdio()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qcoder-0.5.0a7/src/qcoder/mcp/tools.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from qcoder.core.share_safe import make_share_safe_payload
+from qcoder.engines.context.markdown import render_context_markdown
+from qcoder.engines.review.markdown import render_review_markdown
+from qcoder.pipelines.analyze import analyze_qasm_json
+from qcoder.pipelines.context import build_preflight_context
+from qcoder.pipelines.review import build_execution_review
+
+
+MAX_MCP_INPUT_BYTES = 1024 * 1024
+
+SAFE_MARKETING_FRAME = (
+    "Explorer helps you make your AI assistant better at quantum circuit work by "
+    "giving it clean qCoder evidence to reason from."
+)
+
+SUPPORTED_CLAIMS = [
+    "local deterministic QASM2/OpenQASM 2 structural evidence",
+    "local Qiskit counts review",
+    "share-safe evidence handoff",
+    "plain-English bounded next checks from observed qCoder evidence",
+]
+
+UNSUPPORTED_CLAIMS = [
+    "autonomous circuit repair",
+    "runtime prediction",
+    "fidelity prediction",
+    "backend or QPU ranking",
+    "QPU/backend guidance",
+    "quantum advantage",
+    "correctness proof",
+    "raw hosted QASM review",
+    "persistent Explorer history",
+    "public hosted MCP",
+    "productized Claude Code or Codex integration",
+]
+
+
+def list_tools() -> list[dict[str, Any]]:
+    return [
+        _tool_schema(
+            "qcoder_analyze_circuit",
+            "Analyze one explicit local OpenQASM 2 file and return share-safe qCoder evidence.",
+            {"qasm_path": {"type": "string"}, "include_guidance": {"type": "boolean"}, "include_profiles": {"type": "boolean"}},
+            ["qasm_path"],
+        ),
+        _tool_schema(
+            "qcoder_generate_context_pack",
+            "Build a share-safe preflight context pack for one explicit local OpenQASM 2 file.",
+            {"qasm_path": {"type": "string"}, "include_guidance": {"type": "boolean"}, "include_profiles": {"type": "boolean"}},
+            ["qasm_path"],
+        ),
+        _tool_schema(
+            "qcoder_review_counts",
+            "Review one explicit local counts JSON file, optionally linked to one preflight context JSON.",
+            {
+                "counts_json": {"type": "string"},
+                "counts_format": {"type": "string", "enum": ["qcoder", "qiskit_counts"]},
+                "preflight_json": {"type": "string"},
+            },
+            ["counts_json"],
+        ),
+        _tool_schema(
+            "qcoder_explain_findings",
+            "Explain bounded findings from a qCoder artifact object supplied directly to the tool.",
+            {"artifact": {"type": "object"}},
+            ["artifact"],
+        ),
+        _tool_schema(
+            "qcoder_claim_boundaries",
+            "Return qCoder Explorer Launch claim boundaries and unsupported claims.",
+            {"artifact": {"type": "object"}},
+            [],
+        ),
+        _tool_schema(
+            "qcoder_next_checks",
+            "Recommend bounded next checks from a qCoder artifact object supplied directly to the tool.",
+            {"artifact": {"type": "object"}},
+            ["artifact"],
+        ),
+        _tool_schema(
+            "qcoder_generate_share_safe_artifact",
+            "Sanitize a supplied artifact object into a share-safe qCoder artifact.",
+            {"artifact": {"type": "object"}},
+            ["artifact"],
+        ),
+    ]
+
+
+def _tool_schema(name: str, description: str, properties: dict[str, Any], required: list[str]) -> dict[str, Any]:
+    return {
+        "name": name,
+        "description": description,
+        "inputSchema": {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+            "additionalProperties": False,
+        },
+    }
+
+
+def call_tool(name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+    args = arguments or {}
+    if name == "qcoder_analyze_circuit":
+        return _analyze_circuit(args)
+    if name == "qcoder_generate_context_pack":
+        return _generate_context_pack(args)
+    if name == "qcoder_review_counts":
+        return _review_counts(args)
+    if name == "qcoder_explain_findings":
+        return _explain_findings(args)
+    if name == "qcoder_claim_boundaries":
+        return _claim_boundaries(args)
+    if name == "qcoder_next_checks":
+        return _next_checks(args)
+    if name == "qcoder_generate_share_safe_artifact":
+        return _generate_share_safe_artifact(args)
+    raise ValueError(f"unknown qCoder MCP tool: {name}")
+
+
+def _explicit_file_arg(args: dict[str, Any], key: str) -> str:
+    value = args.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{key} is required")
+    path = Path(value).expanduser()
+    if not path.is_file():
+        raise ValueError(f"{key} must be an explicit readable file")
+    if path.stat().st_size > MAX_MCP_INPUT_BYTES:
+        raise ValueError(f"{key} exceeds the local MCP input size cap of {MAX_MCP_INPUT_BYTES} bytes")
+    return str(path)
+
+
+def _artifact_arg(args: dict[str, Any]) -> dict[str, Any]:
+    artifact = args.get("artifact")
+    if not isinstance(artifact, dict):
+        raise ValueError("artifact must be a JSON object supplied directly to the tool")
+    return artifact
+
+
+def _result(payload: dict[str, Any], *, markdown: str | None = None) -> dict[str, Any]:
+    text = json.dumps(payload, indent=2, sort_keys=True)
+    content = [{"type": "text", "text": text}]
+    if markdown is not None:
+        content.append({"type": "text", "text": markdown})
+    return {"content": content, "structuredContent": payload}
+
+
+def _analyze_circuit(args: dict[str, Any]) -> dict[str, Any]:
+    qasm_path = _explicit_file_arg(args, "qasm_path")
+    try:
+        payload = analyze_qasm_json(
+            qasm_path,
+            include_guidance=bool(args.get("include_guidance", True)),
+            include_profiles=bool(args.get("include_profiles", True)),
+        )
+    except NotImplementedError as exc:
+        if "OpenQASM 3" in str(exc):
+            raise ValueError("local qCoder MCP currently supports OpenQASM 2; QASM3 is deferred") from exc
+        raise
+    payload = make_share_safe_payload(payload)
+    payload["mcp_boundary"] = _mcp_boundary()
+    return _result(payload)
+
+
+def _generate_context_pack(args: dict[str, Any]) -> dict[str, Any]:
+    qasm_path = _explicit_file_arg(args, "qasm_path")
+    try:
+        payload = build_preflight_context(
+            qasm_path,
+            include_guidance=bool(args.get("include_guidance", True)),
+            include_profiles=bool(args.get("include_profiles", True)),
+        )
+    except NotImplementedError as exc:
+        if "OpenQASM 3" in str(exc):
+            raise ValueError("local qCoder MCP currently supports OpenQASM 2; QASM3 is deferred") from exc
+        raise
+    payload = make_share_safe_payload(payload)
+    payload["evidence_grounded_coding_loop"] = _evidence_loop()
+    payload["mcp_boundary"] = _mcp_boundary()
+    return _result(payload, markdown=render_context_markdown(payload))
+
+
+def _review_counts(args: dict[str, Any]) -> dict[str, Any]:
+    counts_json = _explicit_file_arg(args, "counts_json")
+    counts_format = args.get("counts_format", "qiskit_counts")
+    if counts_format not in {"qcoder", "qiskit_counts"}:
+        raise ValueError("counts_format must be qcoder or qiskit_counts")
+    preflight_json = args.get("preflight_json")
+    preflight = _explicit_file_arg(args, "preflight_json") if preflight_json else None
+    payload = build_execution_review(
+        counts_json=counts_json,
+        counts_format=str(counts_format),
+        preflight_json=preflight,
+    )
+    payload = make_share_safe_payload(payload)
+    payload["mcp_boundary"] = _mcp_boundary()
+    return _result(payload, markdown=render_review_markdown(payload))
+
+
+def _explain_findings(args: dict[str, Any]) -> dict[str, Any]:
+    artifact = _artifact_arg(args)
+    feature_map = _feature_map_from_artifact(artifact)
+    summary = {
+        "schema_id": "qcoder.mcp.explain_findings.v0",
+        "status": "ok",
+        "finding_summary": _finding_lines(feature_map),
+        "evidence_basis": "qCoder structural evidence supplied by the user or generated from an explicit local input.",
+        "limits": [
+            "This is not simulator or hardware execution evidence.",
+            "This is not a correctness proof.",
+            "This is not runtime, fidelity, backend, QPU, or quantum-advantage prediction.",
+        ],
+        "safe_framing": SAFE_MARKETING_FRAME,
+        "mcp_boundary": _mcp_boundary(),
+    }
+    return _result(make_share_safe_payload(summary))
+
+
+def _claim_boundaries(args: dict[str, Any]) -> dict[str, Any]:
+    artifact = args.get("artifact") if isinstance(args.get("artifact"), dict) else {}
+    feature_map = _feature_map_from_artifact(artifact) if artifact else {}
+    payload = {
+        "schema_id": "qcoder.mcp.claim_boundaries.v0",
+        "status": "ok",
+        "mcp_supported_claims": SUPPORTED_CLAIMS,
+        "mcp_unsupported_claims": UNSUPPORTED_CLAIMS,
+        "artifact_present": bool(artifact),
+        "artifact_summary": {
+            "feature_map_present": bool(feature_map),
+            "feature_keys_present": sorted(str(key) for key in feature_map)[:12],
+            "artifact_type": artifact.get("artifact_type") if isinstance(artifact.get("artifact_type"), str) else None,
+            "schema_id": artifact.get("schema_id") if isinstance(artifact.get("schema_id"), str) else None,
+        },
+        "manual_artifact_loop_launch_required": True,
+        "local_cursor_mcp_complements_artifacts": True,
+        "oss_boundary": "OSS remains local, no-account, no-token.",
+        "explorer_boundary": "Explorer is account-backed guidance over local/share-safe evidence.",
+        "pro_boundary": "Pro owns fidelity prediction, QPU/backend guidance, backend ranking, and validated runtime/shot modeling.",
+        "mcp_boundary": _mcp_boundary(),
+    }
+    return _result(make_share_safe_payload(payload))
+
+
+def _next_checks(args: dict[str, Any]) -> dict[str, Any]:
+    artifact = _artifact_arg(args)
+    feature_map = _feature_map_from_artifact(artifact)
+    checks = [
+        "Generate or refresh a share-safe qCoder preflight context artifact.",
+        "If you have measurement counts, run qcoder review with --format qiskit_counts or qcoder.",
+        "Share only the share-safe summary with Cursor, ChatGPT, teammates, issues, or forums.",
+    ]
+    if _number(feature_map.get("n_measure_ops")) == 0:
+        checks.append("Add or verify measurement operations before interpreting counts.")
+    if _number(feature_map.get("n_2q_gate_ops")) > 0:
+        checks.append("Review two-qubit structure and entangling depth before choosing simulator settings.")
+    if _number(feature_map.get("n_param_ops")) > 0:
+        checks.append("Confirm parameter binding and sweep assumptions outside qCoder before execution.")
+    payload = {
+        "schema_id": "qcoder.mcp.next_checks.v0",
+        "status": "ok",
+        "next_checks": checks,
+        "limits": [
+            "Recommendations are bounded next checks, not autonomous repair.",
+            "No backend, QPU, runtime, fidelity, correctness, or advantage claim is made.",
+        ],
+        "mcp_boundary": _mcp_boundary(),
+    }
+    return _result(make_share_safe_payload(payload))
+
+
+def _generate_share_safe_artifact(args: dict[str, Any]) -> dict[str, Any]:
+    payload = make_share_safe_payload(_artifact_arg(args))
+    payload["mcp_boundary"] = _mcp_boundary()
+    return _result(payload)
+
+
+def _feature_map_from_artifact(artifact: dict[str, Any]) -> dict[str, Any]:
+    if isinstance(artifact.get("feature_map"), dict):
+        return artifact["feature_map"]
+    analysis = artifact.get("analysis")
+    if isinstance(analysis, dict) and isinstance(analysis.get("feature_map"), dict):
+        return analysis["feature_map"]
+    derived = artifact.get("derived_analysis")
+    if isinstance(derived, dict) and isinstance(derived.get("selected_feature_map"), dict):
+        return derived["selected_feature_map"]
+    return {}
+
+
+def _finding_lines(feature_map: dict[str, Any]) -> list[str]:
+    if not feature_map:
+        return ["No qCoder feature_map was supplied; generate qCoder evidence first."]
+    lines: list[str] = []
+    for key in ("n_qubits", "n_ops", "real_depth", "entangling_depth", "n_2q_gate_ops", "n_measure_ops"):
+        if key in feature_map:
+            lines.append(f"{key}: {feature_map[key]}")
+    return lines or ["qCoder evidence was supplied, but no launch summary fields were present."]
+
+
+def _number(value: Any) -> float:
+    if isinstance(value, bool):
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    return 0.0
+
+
+def _mcp_boundary() -> dict[str, Any]:
+    return {
+        "local": True,
+        "read_only": True,
+        "explicit_user_selected_inputs_only": True,
+        "modifies_user_code": False,
+        "executes_circuits": False,
+        "submits_to_qpu_or_simulator": False,
+        "requires_token": False,
+        "uses_live_service": False,
+    }
+
+
+def _evidence_loop() -> list[str]:
+    return [
+        "write/edit circuit",
+        "generate qCoder evidence locally",
+        "use Explorer to produce plain-English review and next-step guidance",
+        "share clean Explorer summary with Cursor/ChatGPT",
+        "revise circuit",
+        "review again",
+    ]

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/pipelines/analyze.py

@@ -88,7 +88,7 @@ def analyze_qasm(
     if mirror_artifacts_dir:
         from qcoder.core.qasm2.adjoint_eligibility import check_adjoint_eligibility
 
-        qasm_text = Path(qasm_path).read_text(encoding="utf-8", errors="replace")
+        qasm_text = Path(qasm_path).read_text(encoding="utf-8-sig", errors="replace")
         content_hash = hashlib.sha256(qasm_text.encode("utf-8")).hexdigest()
         eligibility = check_adjoint_eligibility(qasm_text, include_mirror_qasm=True)
         mirror_qasm_ref = None

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder/pipelines/review.py

@@ -20,7 +20,7 @@ def _qcoder_version() -> str:
 
 
 def _load_json(path: str) -> dict[str, Any]:
-    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    data = json.loads(Path(path).read_text(encoding="utf-8-sig"))
     if not isinstance(data, dict):
         raise ValueError(f"JSON root must be an object: {path}")
     return data

{qcoder-0.5.0a6 → qcoder-0.5.0a7/src/qcoder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a6
+Version: 0.5.0a7
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -15,6 +15,8 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -40,6 +42,7 @@ The current public local path is **qCoder OSS**. OSS commands run locally and do
 - `qcoder batch`
 - `qcoder context`
 - `qcoder review`
+- `qcoder mcp` (local read-only Cursor MCP tools)
 - `qcoder explorer` (Explorer Beta account-backed status/demo/evidence checks)
 - `qcoder student` (temporary compatibility alias for Explorer Beta)
 - `qcoder pro` (archived pilot/bootstrap client contract; non-confidential local plumbing only, not a current public product path)
@@ -87,6 +90,14 @@ qcoder review --counts-json counts.json --format qiskit_counts --preflight-json
 
 Share-safe mode is designed for safer sharing: it redacts local paths and token/header-like strings, adds `share_safe=true`, and marks raw QASM/local paths/tokens as not included. Review artifacts before sharing; this is not a guarantee that all sensitive project content has been removed.
 
+Local Cursor MCP:
+
+```bash
+qcoder mcp serve
+```
+
+The MCP server uses explicit user-selected local inputs only. It reads, inspects, explains, bounds, and recommends; it does not execute circuits, modify user code, read arbitrary files, call live services, or require tokens. See [Explorer Evidence-Grounded Coding Loop](examples/08_explorer_evidence_grounded_coding_loop.md) for the manual artifact loop, Cursor MCP setup, and claim boundaries.
+
 Explorer Beta compatibility checks and archived Pro bootstrap:
 
 ```bash

{qcoder-0.5.0a6 → qcoder-0.5.0a7}/src/qcoder.egg-info/SOURCES.txt

@@ -56,6 +56,9 @@ src/qcoder/engines/review/markdown.py
 src/qcoder/engines/review/qiskit_counts.py
 src/qcoder/explorer/__init__.py
 src/qcoder/explorer/derived_evidence.py
+src/qcoder/mcp/__init__.py
+src/qcoder/mcp/server.py
+src/qcoder/mcp/tools.py
 src/qcoder/model_packs/__init__.py
 src/qcoder/model_packs/resource_guidance_local_v0.json
 src/qcoder/pipelines/analyze.py