From daaeadaddd934429b8a8e4659b2cffe3ffd1111a Mon Sep 17 00:00:00 2001 From: ispyisail Date: Tue, 29 Sep 2026 12:40:19 +1300 Subject: [PATCH] ai_assistants: setup for each AI assistant; mcp_server: Over HTTP (pending #1132) --- _Sidebar.md | 2 + ai_assistants.md | 270 +++++++++++++++++++++++++++++++++++++++++++++++ mcp_server.md | 51 +++++++++ 3 files changed, 323 insertions(+) create mode 100644 ai_assistants.md diff --git a/_Sidebar.md b/_Sidebar.md index 06fe331..42c89b2 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -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_ diff --git a/ai_assistants.md b/ai_assistants.md new file mode 100644 index 0000000..49736cc --- /dev/null +++ b/ai_assistants.md @@ -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 `. 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 diff --git a/mcp_server.md b/mcp_server.md index d4cfeca..0a9dcef 100644 --- a/mcp_server.md +++ b/mcp_server.md @@ -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 ` 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