LintQ MCP Server — endpoint for agents

01How it works

The endpoint is a thin, agent-facing wrapper around the same LintQ analysis described on the main site: the Python fact extractor followed by the Soufflé-style Datalog checks.

AgentPOST program

→

Validate≤100 lines · ≤130 ch/line

→

LintQ analysisextractor + Datalog checks

→

Format & shuffleplain-text report

→

JSON responsewarnings + report

The agent POSTs a program. A single JSON object whose program field holds the Qiskit source as a string.
The server validates it. The program must be agreed scope: at most 100 lines and at most 130 characters per line. Out-of-scope programs are rejected with a clear error and never analysed.
The server runs LintQ. The same extractor + Datalog checks used on the main site lower the program to facts and enumerate the four warning classes.
Warnings are formatted and shuffled. They are returned both as machine-readable rows (warnings) and as a single report string written for an agent to read.
The request is logged. Program text, returned warnings, a timestamp, and an anonymous request id are stored in a SQL database so we can understand what agents lint.

The endpoint is intentionally minimal: one route, one JSON body, one JSON response. It is designed to be called directly by an LLM agent (or any HTTP client) without any special library.

02Endpoint & request schema

Send a single JSON object over POST. The only required field is program — the Qiskit source as a string.

POST /mcp
Host: lintq.matteopaltenghi.com
Content-Type: application/json

{
  "program": "from qiskit import QuantumCircuit\nqc = QuantumCircuit(1, 1)\nqc.measure(0, 0)\nqc.measure(0, 0)"
}

Request fields

Field	Type	Required	Notes
`program`	string	yes	Qiskit source. Must be ≤ 100 lines and every line ≤ 130 chars.

Response fields

Field	Type	Meaning
`ok`	boolean	`true` when the program was analysed; `false` on validation error.
`code`	string	Error code when `ok` is false (e.g. `TOO_LONG`, `LINE_TOO_LONG`).
`error`	string	Human-readable rejection reason (only when `ok` is false).
`warnings`	array	One object per warning: `check`, `line`, `circuit`, `qubit`, `message`.
`report`	string	A ready-to-read plain-text summary of the warnings, for the agent to consume directly.

Limits (validation)

Maximum 100 lines in the submitted program.
Maximum 130 characters per line.

If a program breaks a limit the server answers with ok:false and an error string — it never lints an out-of-scope program.

03Example agent requests & responses

With curl

curl -sS -X POST https://lintq.matteopaltenghi.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"program":"from qiskit import QuantumCircuit\nqc = QuantumCircuit(1, 1)\nqc.measure(0, 0)\nqc.measure(0, 0)"}'

With Python

import requests

resp = requests.post(
    "https://lintq.matteopaltenghi.com/mcp",
    json={"program": "from qiskit import QuantumCircuit\n"
                     "qc = QuantumCircuit(1, 1)\n"
                     "qc.measure(0, 0)\n"
                     "qc.measure(0, 0)"},
)
data = resp.json()
print(data["report"])        # human-readable text for the agent
for w in data["warnings"]:   # or machine-readable rows
    print(w["check"], w["line"])

Response — one warning (DoubleMeas)

{
  "ok": true,
  "warnings": [
    {
      "check": "DoubleMeas",
      "line": 4,
      "circuit": "qc",
      "qubit": 0,
      "message": "Qubit 0 is measured twice (lines 3 and 4) with no operation in between -- redundant consecutive measurement."
    }
  ],
  "report": "LintQ found 1 warning:\n[1] DoubleMeas (line 4, qc, qubit 0): Qubit 0 is measured twice (lines 3 and 4) with no operation in between -- redundant consecutive measurement."
}

Warnings are shuffled before they are returned, so the order inside warnings may differ between calls. The report string mirrors the same (shuffled) warnings in the same order.

Response — clean program (no warnings)

{
  "ok": true,
  "warnings": [],
  "report": "LintQ found 0 warnings. ✓"
}

Response — validation error

{
  "ok": false,
  "code": "TOO_LONG",
  "error": "Program exceeds the 100-line limit (received 142 lines)."
}

✓ Send a Qiskit program, get back warnings as text — that is the whole contract.

04What the checks look for

The endpoint runs the same four analyses documented on the main site.

Check	Detects
OpAfterMeas	A gate acts on a qubit after that qubit was measured, with no reset along the control-flow path between them.
DoubleMeas	Two measurements of the same qubit with no operation on it in between — a redundant consecutive measure.
GhostCompose	`qc.compose(sub)` (or `tensor`) whose return value is discarded — a silent no-op in Qiskit.
MissingReset	The first operation on a qubit is not a reset — the qubit is used or measured while uninitialised.

Each returned warning carries the line of the offending statement, the circuit it belongs to, and a plain-language message an agent can act on.

05Terms of use

By sending a program to the LintQ MCP endpoint you agree to the following:

1 · No guarantee whatsoever

The service is provided “as is”, without warranty of any kind. We make no guarantee whatsoever as to the correctness, completeness, availability, or fitness for any purpose of the analysis or its output. The warnings may be wrong, missing, or misleading.

2 · Use of submitted data

We reserve the right to use submitted data for any academic or commercial purpose, including but not limited to research, model training, evaluation, benchmarking, and publication, without compensation to you.

3 · Ownership of submitted code

You acknowledge that the code you send is yours. You represent that you have the right to submit it, and submission does not transfer ownership of the code to us.

4 · Logging

Requests and response metadata (program text, returned warnings, timestamp, and an anonymous request id) are logged to a SQL database to understand agent needs and improve the service.