ai_assistants: setup for each AI assistant; mcp_server: Over HTTP (pending #1132)

2026-10-06 19:54:13 +02:00 · 2026-09-29 12:40:19 +13:00
parent 6c3ecb9c40
commit daaeadaddd
3 changed files with 323 additions and 0 deletions
@@ -151,6 +151,8 @@

 **[MCP server](mcp_server)** — let an AI assistant read, verify and edit projects

+**[Connecting an AI assistant](ai_assistants)** — setup for Claude, Copilot, Gemini, Codex, Cursor, LM Studio
+
 **[Development Roadmap](development_roadmap)**

 **[Vision](vision)** — _proposal, under discussion_
@@ -0,0 +1,270 @@
+# Connecting an AI assistant
+
+Let the AI assistant you already use (Claude, GitHub Copilot, Gemini,
+Codex, or a model running on your own computer) open, check and edit your
+QElectroTech drawings. It does this through QElectroTech's
+**[MCP server](mcp_server)**, a small program that runs on your computer next
+to your drawings. Nothing is uploaded to us. What the assistant reads goes to
+whichever AI company runs it, as with anything else you show it.
+
+This page is the setup for each assistant. What the tools do, and every
+option, is on the [MCP server](mcp_server) page.
+
+---
+
+## Before you start
+
+1. **Python 3.9 or later.** Nothing else to install: the server uses only
+   Python's standard library. On Windows, get it from
+   [python.org](https://www.python.org/downloads/) and tick "Add python.exe
+   to PATH" in the installer.
+2. **The server itself**, one file:
+   [`qet_mcp.py`](https://raw.githubusercontent.com/qelectrotech/qelectrotech-source-mirror/master/misc/qet-mcp/qet_mcp.py).
+   Save it anywhere, for example next to your drawings. It is not in the
+   QElectroTech installers yet.
+3. **A folder for the drawings the assistant may use.** The server only
+   reads and writes inside it (`QET_MCP_WORKSPACE`). Pick a folder of
+   drawings, not your whole home folder.
+
+In every setup below, replace:
+
+| Placeholder | With |
+|---|---|
+| `/path/to/qet_mcp.py` | where you saved the server |
+| `/path/to/drawings` | your drawings folder |
+| `/path/to/qelectrotech` | the QElectroTech program: `/usr/bin/qelectrotech` on Linux, `C:\Program Files\QElectroTech\bin\qelectrotech.exe` or wherever you installed it on Windows |
+
+On Windows, write each `\` in a JSON file as `\\`, and use `python` where
+the examples say `python3`.
+
+### What the assistant can do
+
+| Setting | Tools the assistant gets |
+|---|---|
+| nothing extra | read projects and symbols, compare two versions of a project (`qet_diff`), search the symbol collection, export to PDF/PNG/SVG/DXF and lists |
+| `QET_ENABLE_SCRIPTING=1` | also **edit**: place symbols, draw wires, set labels, add folios, check design rules, query the project database |
+
+Leave `QET_ENABLE_SCRIPTING` out if you only want the assistant to read.
+Edits are never saved over an existing file unless the assistant asks for it
+explicitly. They go to a new file you name.
+
+> **Be careful with projects from other people.** An assistant reads the
+> text in a project: labels, notes, symbol names. Text written to look like
+> an instruction can steer it. Keep editing off when you work on drawings you
+> did not make, and check what an assistant changed (it can show you with
+> `qet_diff`).
+
+### Telling it where QElectroTech is
+
+> **Status: pending.** The `QET_BINARY` setting below comes with
+> [PR #1129](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1129),
+> not yet merged. Until it is, leave it in the setup anyway (it does no
+> harm), and tell the assistant in the chat where the QElectroTech program
+> is when it asks. This section will drop this notice once the PR lands.
+
+Exports and edits start QElectroTech in the background. The server finds it
+from `QET_BINARY`, or from `qelectrotech` on your `PATH`. The assistant
+cannot pick another program.
+
+---
+
+## Setups
+
+Each was checked as far as the "Tested" column says, on 2026-09-29.
+
+| Assistant | Where the setup goes | Tested |
+|---|---|---|
+| [Claude Desktop](#claude-desktop) | Settings → Developer → Edit Config | not on Windows or macOS; same format as Claude Code |
+| [Claude Code](#claude-code) | `.mcp.json` in your drawings folder, or `claude mcp add` | **a real tool call**, Claude Code 2.1.283 |
+| [GitHub Copilot in VS Code](#github-copilot-in-vs-code) | `.vscode/mcp.json` | format from VS Code's documentation; not run |
+| [Cursor](#cursor) | `~/.cursor/mcp.json` | format from Cursor's documentation; not run |
+| [Gemini CLI](#gemini-cli) | `~/.gemini/settings.json` | **connects** (`gemini mcp list`: Connected) |
+| [Codex CLI](#codex-cli) | `~/.codex/config.toml` | **setup accepted** (`codex mcp list`: enabled); no tool call |
+| [LM Studio](#lm-studio) | Program → Install → Edit mcp.json | format from LM Studio's documentation; not run |
+
+### Claude Desktop
+
+Settings → Developer → **Edit Config**, add this, then quit the app fully
+and start it again:
+
+```json
+{
+  "mcpServers": {
+    "qet": {
+      "command": "python3",
+      "args": ["/path/to/qet_mcp.py"],
+      "env": {
+        "QET_MCP_WORKSPACE": "/path/to/drawings",
+        "QET_BINARY": "/path/to/qelectrotech",
+        "QET_ENABLE_SCRIPTING": "1"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+The same block, saved as `.mcp.json` in your drawings folder, or in one
+command:
+
+```bash
+claude mcp add qet \
+  -e QET_MCP_WORKSPACE=/path/to/drawings \
+  -e QET_BINARY=/path/to/qelectrotech \
+  -e QET_ENABLE_SCRIPTING=1 \
+  -- python3 /path/to/qet_mcp.py
+```
+
+### GitHub Copilot in VS Code
+
+Copilot uses tools in **agent mode** only. Save as `.vscode/mcp.json` in the
+folder you open in VS Code. VS Code asks you to trust the server the first
+time it starts:
+
+```json
+{
+  "servers": {
+    "qet": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["/path/to/qet_mcp.py"],
+      "env": {
+        "QET_MCP_WORKSPACE": "/path/to/drawings",
+        "QET_BINARY": "/path/to/qelectrotech",
+        "QET_ENABLE_SCRIPTING": "1"
+      }
+    }
+  }
+}
+```
+
+Note the key is `servers` here, not `mcpServers`.
+
+### Cursor
+
+`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one:
+
+```json
+{
+  "mcpServers": {
+    "qet": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["/path/to/qet_mcp.py"],
+      "env": {
+        "QET_MCP_WORKSPACE": "/path/to/drawings",
+        "QET_BINARY": "/path/to/qelectrotech",
+        "QET_ENABLE_SCRIPTING": "1"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+`~/.gemini/settings.json`, or `.gemini/settings.json` in your drawings
+folder:
+
+```json
+{
+  "mcpServers": {
+    "qet": {
+      "command": "python3",
+      "args": ["/path/to/qet_mcp.py"],
+      "env": {
+        "QET_MCP_WORKSPACE": "/path/to/drawings",
+        "QET_BINARY": "/path/to/qelectrotech",
+        "QET_ENABLE_SCRIPTING": "1"
+      }
+    }
+  }
+}
+```
+
+Gemini CLI starts no server in a folder you have not trusted: it asks the
+first time you run `gemini` there. `gemini mcp list` should then show
+`qet … Connected`.
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.qet]
+command = "python3"
+args = ["/path/to/qet_mcp.py"]
+
+[mcp_servers.qet.env]
+QET_MCP_WORKSPACE = "/path/to/drawings"
+QET_BINARY = "/path/to/qelectrotech"
+QET_ENABLE_SCRIPTING = "1"
+```
+
+`codex mcp list` should show `qet` as `enabled`.
+
+### LM Studio
+
+LM Studio 0.3.17 or later. In the **Program** tab of the right-hand sidebar,
+**Install → Edit mcp.json**, and add the same block as
+[Gemini CLI](#gemini-cli). A model running on your own computer
+sends nothing anywhere, but small models use tools less reliably than the
+big hosted ones. Expect more mistakes with edits.
+
+### Any other assistant
+
+Most take the same `command` / `args` / `env` block under `mcpServers`.
+The server speaks MCP over standard input and output.
+
+---
+
+## By web address
+
+> **Status: pending.** This section describes
+> [PR #1132](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1132),
+> not yet merged. Nothing here works until that lands — check the PR
+> before trying any of this against your own build. This section will drop
+> this notice once it does.
+
+Some assistants connect to a server by address instead of starting it. Start
+it yourself, on this computer only:
+
+```bash
+QET_MCP_WORKSPACE=/path/to/drawings python3 qet_mcp.py --http
+python3 qet_mcp.py --show-token
+```
+
+and give the assistant `http://127.0.0.1:8731/mcp` with the header
+`Authorization: Bearer <token>`. For example in VS Code:
+
+```json
+{
+  "servers": {
+    "qet": {
+      "type": "http",
+      "url": "http://127.0.0.1:8731/mcp",
+      "headers": { "Authorization": "Bearer ${input:qet-token}" }
+    }
+  },
+  "inputs": [
+    { "id": "qet-token", "type": "promptString", "description": "qet-mcp token", "password": true }
+  ]
+}
+```
+
+It offers only the reading tools unless started with `--allow-edit`. Every
+option and what it refuses is on the [MCP server](mcp_server#over-http) page.
+
+## ChatGPT, and Claude or Copilot in a web browser
+
+These reach a server only through the internet, from their own computers,
+and need a login QElectroTech's server does not have yet. That is planned.
+Until then, a web chat that can run Python can use the server's reading
+tools on a project you upload. See
+[Using it without Claude Code](mcp_server#using-it-without-claude-code).
+
+## See also
+
+- **[MCP server](mcp_server)**: every tool and setting
+- **[JavaScript Scripting](scripting)**: what edits run underneath
@@ -72,6 +72,56 @@ above are the only setup that matters, and both are covered below.

 ---

+## Over HTTP
+
+> **Status: pending.** This section describes
+> [PR #1132](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1132),
+> not yet merged. Nothing here works until that lands — check the PR
+> before trying any of this against your own build. This section will drop
+> this notice once it does.
+
+Some assistants connect to a server by web address rather than starting it
+themselves. `--http` serves the same tools on this computer only:
+
+```bash
+export QET_MCP_WORKSPACE=/home/you/drawings
+python3 misc/qet-mcp/qet_mcp.py --http            # http://127.0.0.1:8731/mcp
+python3 misc/qet-mcp/qet_mcp.py --show-token      # the token a client must send
+```
+
+The client sends `Authorization: Bearer <token>` with every request; its
+setup usually has a "headers" field for it (examples on
+[Connecting an AI assistant](ai_assistants#by-web-address)).
+
+| Option | Effect |
+|---|---|
+| `--http [PORT]` | serve on `127.0.0.1:PORT` (default 8731). It never listens on any other address |
+| `--allow-edit` | offer every tool. Without it only the eight that read a file are offered: `qet_project_info`, `qet_elements`, `qet_conductors`, `qet_items`, `qet_diff`, `qet_scan`, `qet_element_info`, `qet_element_search` |
+| `--allow-origin ORIGIN` | a web page origin allowed to call, for a client that runs in a browser (repeatable) |
+| `--show-token` / `--new-token` | print the token / replace it, which cuts off every client using the old one |
+| `QET_MCP_TOKEN_FILE` | where the token is kept. Default: `~/.config/qet-mcp/token`; `%APPDATA%\qet-mcp\token` on Windows; `~/Library/Application Support/qet-mcp/token` on macOS |
+
+What it refuses, before reading a request:
+
+| Refused | Answer | Why |
+|---|---|---|
+| a `Host` other than `127.0.0.1:PORT` or `localhost:PORT` | 403 | a web page reaching a local server through a name of its own (DNS rebinding) |
+| an `Origin` not allowed with `--allow-origin` | 403 | a web page you visit calling it |
+| a missing or wrong token | 401 | anyone else on the machine |
+| a body over 1 MB, not JSON, or a batch | 413 / 415 / 400 | |
+| GET, DELETE and other methods | 405 | no event stream, no sessions |
+
+The token file is created readable by you only; if others can read it, the
+server refuses to use it. `QET_MCP_WORKSPACE` must be set, because a server
+started by hand from your home folder would otherwise serve all of it.
+Every call is logged to standard error with the tool and the paths it was
+given, never file contents or the token.
+
+It speaks the protocol versions that begin with `initialize` (2025-03-26 to
+2025-11-25). Clients on the newer revision fall back to it.
+
+---
+
 ## Using it without Claude Code

 Added in
@@ -444,6 +494,7 @@ regression in the thing under test, not a missing switch.

 ## See also

+- **[Connecting an AI assistant](ai_assistants)** — setup for each assistant
 - **[JavaScript Scripting](scripting)** — the `qet.*` engine `qet_edit` and
  `qet_query` drive underneath
 - **[The project database](project_database)** — what `qet_query` reads