# tqs-mcp

MCP server for **TQS**, the Brazilian structural engineering CAD/analysis system,
built on the [TQS Python Interface](https://docs.tqs.com.br/Docs/Details?id=173818189&language=pt-BR).

It lets Claude Code (or any MCP client) read building models, extract data from
TQS drawings, run structural processing, and script against the TQS API.

> Unofficial and independent. TQS® is a trademark of TQS Informática Ltda.

## Requirements

- **Windows** with TQS installed (the modules bind to native TQS DLLs)
- The **TQS Python Interface** wheel installed in some Python 3.10+ interpreter:
  ```
  pip install TQSPythonInterface-1.2.1-py310-none-any.whl
  ```
  Get it from [tqs.com.br/developers](https://www.tqs.com.br/developers).
- Python 3.10+ to run this server

The server itself does **not** need TQS in its own interpreter. It runs all TQS
work in a subprocess under whichever interpreter has the TQS package — point
`TQS_PYTHON` at it. That keeps the server alive if a TQS DLL crashes, and lets
this server run on a modern Python while TQS code runs on the version its wheel
was built for.

## Install

```bash
git clone https://github.com/carlostavares-manager-MNGT/tqs-mcp
cd tqs-mcp
uv sync
```

## Configure

Add to Claude Code:

```bash
claude mcp add tqs -e TQS_PYTHON=C:\\TQSW\\Python\\python.exe -e TQS_ROOT=C:\\TQS -- uv --directory C:\\path\\to\\tqs-mcp run tqs-mcp
```

Or edit the MCP config directly:

```json
{
  "mcpServers": {
    "tqs": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\tqs-mcp", "run", "tqs-mcp"],
      "env": {
        "TQS_PYTHON": "C:\\TQSW\\Python\\python.exe",
        "TQS_ROOT": "C:\\TQS"
      }
    }
  }
}
```

| Variable | Meaning | Default |
|----------|---------|---------|
| `TQS_PYTHON` | Interpreter with the TQS package installed | the server's own interpreter |
| `TQS_ROOT` | Root of the building tree | none — pass paths explicitly |
| `TQS_MCP_TIMEOUT` | Default subprocess timeout, seconds | `120` |

**Run `tqs_status` first.** It reports the interpreter in use, which TQS modules
import, and the TQS folders — and tells you what to fix if TQS is unreachable.

## Tools

| Tool | What it does |
|------|--------------|
| `tqs_status` | Is TQS reachable? Which interpreter, modules, folders |
| `tqs_list_buildings` | Find buildings (folders with `EDIFICIO.DAT`) under a root |
| `tqs_building_read` | Project metadata, model, floors, concrete strengths, covers, loads |
| `tqs_building_edit` | Change building properties and save — dry-run by default |
| `tqs_dwg_read` | Drawing metadata, extents, levels, blocks, entity counts, entities |
| `tqs_process` | Run TQSExec tasks — global processing, drawings, rebar schedules |
| `tqs_introspect` | List the **installed** TQS API's real methods and properties |
| `tqs_run_script` | Run arbitrary Python with TQS importable — the escape hatch |
| `tqs_reference` | Bundled offline API reference, browsable and searchable |

`tqs_building_edit`, `tqs_process` and `tqs_run_script` modify project files and
are annotated as such, so MCP clients prompt before running them.

The reference topics are also exposed as MCP resources under `tqs://reference/`.

### Why `tqs_introspect` exists

TQS's published docs cover part of the API. Rather than guess at property names,
ask the installed version:

```
tqs_introspect(target="TQSBuild.Building.floorsplan")
tqs_introspect(target="TQSDwg", filter="DWGTYPE")
```

## Examples

**Audit concrete strengths across a project**

> Read the building at C:\TQS\EDIF-A and tell me the concrete strength per floor.

**Pull rebar callouts out of a drawing**

> From C:\TQS\EDIF-A\PAV1\VIGAS.DWG, extract all TEXT entities containing "Ø"
> and group them by level.

**Reprocess after a change**

> Set beam cover to 3.0 cm in EDIF-A, then run global processing on the frames
> folder and regenerate the rebar schedule.

**Anything else**

```python
# via tqs_run_script
from TQS import TQSDwg
dwg = TQSDwg.Dwg()
dwg.file.Open("PLANTA.DWG")
result = {"limits": dwg.limits.DwgLimits(), "scale": dwg.settings.scale}
```

## Development

```bash
uv sync
uv run pytest
```

The test suite runs **without TQS installed** — it covers the tool surface,
driver framing, and the absent-TQS error paths.

### Status

The MCP layer, the subprocess bridge, and every driver's framing and error path
are tested and working. The TQS API calls inside the drivers are written from the
official documentation but **have not been exercised against a live TQS
install** — that hardware wasn't available here. Expect to need
`tqs_introspect` to correct property names on first real use, particularly:

- the floor-count property on `floorsplan` (the driver probes several candidates)
- the return shape of `loads.GetLoad()`
- `TaskGlobalProc` parameter names beyond those in the docs

Corrections via issue or PR are welcome.

### Layout

```
src/tqs_mcp/
  server.py      MCP tools
  bridge.py      subprocess protocol (sentinel-framed JSON)
  config.py      environment variables
  drivers/       scripts executed inside the TQS interpreter
  reference/     bundled API docs, served as tools and resources
```

Drivers are plain scripts, so they can be run and debugged directly:

```bash
echo {} > args.json
C:\TQSW\Python\python.exe src/tqs_mcp/drivers/status.py args.json
```

## License

MIT — see [LICENSE](LICENSE).