From 907311298aa07c35822e4fda8b46f0b5c00527f9 Mon Sep 17 00:00:00 2001 From: ispyisail Date: Tue, 29 Sep 2026 11:37:13 +1300 Subject: [PATCH] mcp_server: using it without Claude Code (pending #1128); drop merged #1125/#1126 notices --- mcp_server.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++-- scripting.md | 6 ---- 2 files changed, 91 insertions(+), 9 deletions(-) diff --git a/mcp_server.md b/mcp_server.md index f0ab616..c923ac4 100644 --- a/mcp_server.md +++ b/mcp_server.md @@ -71,6 +71,94 @@ above are the only setup that matters, and both are covered below. --- +## Using it without Claude Code + +> **Status: pending.** Everything in this section describes +> [PR #1128](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1128), +> not yet merged. `--call` does not exist until that lands — check the PR +> before trying it against your own build. This section will drop this +> notice once it does. + +A chat assistant in a web browser — claude.ai, or any other web chat — +cannot start a program on your computer, so it cannot run this server. +There are two ways round that. + +### In the Claude desktop app + +The Claude desktop app for Windows and macOS runs local MCP servers, and +it uses the same account as the website. All the tools work, including +`qet_edit` and `qet_export`, because QElectroTech runs on your own +machine. + +1. Install Python 3.9 or later. Nothing else is needed. +2. In the desktop app, open **Settings → Developer → Edit Config**. This + opens `claude_desktop_config.json`. +3. Add the server, with your own paths: + + ```json + { + "mcpServers": { + "qet": { + "command": "python", + "args": ["C:\\path\\to\\qelectrotech\\misc\\qet-mcp\\qet_mcp.py"], + "env": { + "QET_MCP_WORKSPACE": "C:\\Users\\you\\Documents\\drawings", + "QET_ENABLE_SCRIPTING": "1" + } + } + } + } + ``` + + On macOS use `python3` and ordinary `/` paths. In JSON every `\` in a + Windows path is written `\\`. +4. Quit the app completely and start it again. The tools appear under the + chat box's tools menu. +5. In the chat, say where your `qelectrotech` executable is. `qet_edit` and + `qet_export` take it as an argument on every call; the other tools do + not need it. + +Only files under `QET_MCP_WORKSPACE` can be read or written (see +[Workspace confinement](#workspace-confinement)). Leave out +`QET_ENABLE_SCRIPTING` if you do not want the assistant to edit projects; +see [Scripting gate](#scripting-gate) for what that switches off. + +The server's tests run on Linux. It uses nothing platform-specific, but +these steps have not yet been tested on Windows or macOS. + +### With only a browser + +If your web chat can run Python (on claude.ai, code execution), upload +`qet_mcp.py` together with your project and ask the assistant to run +single tools with `--call`: + +```bash +python3 qet_mcp.py --call qet_elements '{"path": "drawing.qet"}' +echo '{"path": "drawing.qet"}' | python3 qet_mcp.py --call qet_conductors - +``` + +`--call ` runs one tool and exits. The arguments are a +JSON object, or `-` to read it from standard input, which saves quoting +JSON for a shell. The result is the tool's JSON, printed to standard +output. + +| Exit code | Meaning | +|---|---| +| 0 | the tool succeeded | +| 1 | the tool reported an error (a missing file, a path outside the workspace) — the message is on standard output | +| 2 | the call itself was malformed: unknown tool, arguments that are not a JSON object — the message is on standard error | + +The workspace rule applies exactly as it does in the server: with +`QET_MCP_WORKSPACE` unset, only the folder the script was started in. + +The sandbox has no QElectroTech in it, so only the tools that read files +work there: `qet_project_info`, `qet_elements`, `qet_conductors`, +`qet_items`, `qet_diff`, `qet_scan`, `qet_element_info`, +`qet_element_search` and `qet_element_build`. Editing, exporting, +`qet_check` and `qet_query` need the desktop app route above. + +--- + ## Environment variables | Variable | Effect | @@ -284,9 +372,9 @@ Across the shipped examples: 3190 conductors, not one with a cable value. take `"conductor": "{uuid}"` (as `qet_conductors` reports it) in place of `element` + `terminal`, which works where two conductors meet at a terminal, as long as one of the conductor's two terminals carries only it. -- **A terminal can be given by its uuid.** *Pending, - [PR #1126](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1126):* - `terminal`, `from_terminal` and `to_terminal` will also take the +- **A terminal can be given by its uuid** + ([PR #1126](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1126)): + `terminal`, `from_terminal` and `to_terminal` also take the terminal's uuid (as `qet_element_info` lists it) in place of its index, on the op's own element — for `add_conductor`, each end's own. Unlike the index, it tells apart two terminals at the same point. A uuid the element diff --git a/scripting.md b/scripting.md index b927702..88ddc1d 100644 --- a/scripting.md +++ b/scripting.md @@ -171,12 +171,6 @@ section 4). ### Find a terminal by its uuid -> **Status: pending.** This section describes -> [PR #1125](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1125), -> 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. - `qet.addConductor()` and the conductor calls take a terminal as an element uuid and a terminal **index**. The index is the terminal's place in a list sorted top to bottom, then left to right — not the order the symbol file