Add 52 PhD-level RF engineering tools, fix connected-mode bugs (#42)

Fix critical bugs, security vulnerabilities, and add tests

Author: RFingAdam

.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Type check with mypy
+        run: mypy src/mcp_cst_studio/ --ignore-missing-imports
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify wheel
+        run: pip install dist/*.whl && mcp-cst-studio --help || true

.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CLAUDE.md

@@ -3,28 +3,80 @@
 ## Architecture
 
 - **Dual-mode**: Connected (Windows+CST) and Offline (any OS, generates VBA scripts)
-- **VBA Builder pattern**: All VBA generated via `vba_builder.py` — never use raw f-strings
+- **VBA Builder pattern**: All VBA generated via `vba_builder.py` — never use raw f-strings for VBA
 - **Modular tools**: Each `tools/*.py` exports `TOOLS` list + `handle()` function + `register_*_tools()`
-- **ToolRegistry**: `tools/__init__.py` collects all tools and wires single `list_tools`/`call_tool` handlers
+- **ToolRegistry**: `tools/__init__.py` collects all tools via `_registry.add_module(TOOLS, handle, client)` and wires single `list_tools`/`call_tool` handlers
+- **Offline-first**: Server works fully on Linux/macOS. VBA scripts generated for manual execution in CST
 
 ## Key Files
 
-- `types.py` — Enums and dataclasses (ProjectType, SolverType, etc.)
-- `config.py` — Env vars, CST path auto-detection
-- `validators.py` — Input validation, VBA injection prevention
-- `vba_builder.py` — Safe VBA code generation (builder pattern)
-- `cst_client.py` — Session manager (connected/offline modes)
-- `server.py` — MCP entry point
-- `tools/` — 16 tool modules (~107 tools total)
-- `data/` — JSON material databases, antenna templates, VBA reference
-
-## Adding New Tools
-
-1. Add Tool definition to the module's `TOOLS` list
-2. Add handler in the module's `handle()` function
-3. Use `VBABuilder` for all VBA generation
-4. Validate all inputs via `validators.py`
+| File | Purpose |
+|------|---------|
+| `types.py` | Enums and dataclasses (ProjectType, SolverType, MeshType, etc.) |
+| `config.py` | Env vars, CST path auto-detection |
+| `validators.py` | Input validation, VBA injection prevention |
+| `vba_builder.py` | Safe VBA code generation (VBABuilder + VBAScript classes) |
+| `cst_client.py` | Session manager (connected/offline modes) |
+| `server.py` | MCP entry point, stdio transport |
+| `tools/__init__.py` | ToolRegistry aggregator, register_all_tools() |
+| `data/` | JSON material databases, antenna templates, VBA reference |
+
+## Tool Categories (~107 tools)
+
+| Module | Tools | Description |
+|--------|-------|-------------|
+| project.py | 8 | Create, open, save, close, export, status |
+| geometry.py | 13 | Brick, cylinder, sphere, cone, torus, extrude, loft, wire, polygon |
+| boolean.py | 4 | Add, subtract, intersect, insert |
+| transforms.py | 4 | Translate, rotate, mirror, scale |
+| materials.py | 8 | Create, load, list, assign, lossy metal, anisotropic |
+| ports.py | 7 | Waveguide, discrete, lumped, plane wave, Floquet, list, delete |
+| boundaries.py | 4 | Boundary conditions, background, symmetry, frequency range |
+| mesh.py | 5 | Mesh type, density, refinement, adaptive, info |
+| solvers.py | 5 | Time domain, frequency domain, eigenmode, integral equation, info |
+| simulation.py | 6 | Run, run_async, status, pause, resume, stop |
+| results.py | 10 | S-params, farfield, field monitor, impedance, VSWR, gain, efficiency |
+| import_export.py | 5 | CAD import/export, Touchstone, farfield |
+| parameters.py | 6 | Set, get, list, delete, sweep, optimize |
+| antenna_templates.py | 13 | Parametric designs: patch, dipole, monopole, horn, Yagi, helix, etc. |
+| pcb.py | 6 | Stackup, traces, vias, ground planes, Gerber import |
+| vba.py | 3 | Raw VBA execution, help reference, object listing |
+
+## Adding a New Tool
+
+1. Add `Tool()` definition to the module's `TOOLS` list with proper inputSchema
+2. Add handler in the module's `handle()` function (inside the try/except)
+3. Use `VBABuilder` for all VBA generation — never raw f-strings
+4. Validate all inputs via `validators.py` functions
 5. Return `list[TextContent]` with JSON response
+6. Register in `tools/__init__.py` via `register_*_tools()`
+
+### Adding a New Tool Module
+
+1. Create `tools/new_category.py` with `TOOLS`, `handle()`, and `register_*_tools()`
+2. Follow the pattern: try/except in handle(), error format `{"status": "error", "message": "..."}`
+3. Import and call `register_*_tools()` in `tools/__init__.py:register_all_tools()`
+4. Add tests in `tests/test_tools_new_category.py`
+
+## Error Handling Contract
+
+All `handle()` functions return consistent error format:
+```json
+{"status": "error", "message": "Human-readable error description"}
+```
+
+- Every `handle()` must wrap its body in `try/except Exception as e`
+- Internal validation errors (e.g., bad enum value) return the same format
+- Never raise exceptions from handle() — always return TextContent with error JSON
+
+## Security Rules
+
+- All VBA passes through `validate_vba_input()` — blocks Shell, CreateObject, file I/O, Declare, SendKeys
+- All file paths checked for traversal (`..`) via `validate_file_path()`
+- All names restricted to `[A-Za-z_][A-Za-z0-9_ .-]*` via `validate_name()`
+- Component paths validated via `validate_component_path()`
+- VBA strings escaped via `_escape_vba_string()` — blocks concatenation injection
+- No hardcoded paths — everything via env vars or auto-detection
 
 ## Testing
 
@@ -33,14 +85,26 @@ pip install -e ".[dev]"
 pytest tests/ -v
 ```
 
-Tests run in offline mode — no CST installation needed.
+Tests run in offline mode — no CST installation needed. The offline client returns `{"status": "offline", "vba": code}` for all execute_vba calls.
 
-## Security Rules
+### Test Pattern
+```python
+@pytest.mark.asyncio
+async def test_tool(client: CSTClient):
+    from mcp_cst_studio.tools.module import handle
+    result = await handle("cst_tool_name", {args}, client)
+    data = json.loads(result[0].text)
+    assert "vba" in data or "status" in data
+```
 
-- All VBA passes through `validate_vba_input()` — blocks Shell, CreateObject, file I/O
-- All file paths checked for traversal (`..`)
-- All names restricted to alphanumeric + underscore + space + dot + hyphen
-- No hardcoded paths — everything via env vars or auto-detection
+## RF Engineering References
+
+- Patch antenna dimensions: Balanis Ch. 14, Hammerstad-Jensen effective permittivity (Eq. 14-1)
+- Microstrip impedance: Wheeler synthesis (narrow/wide strip regimes)
+- Stripline impedance: Cohn formula (Z0 = 94.25/sqrt(eps_r) * ...)
+- Yagi design: reflector 0.20λ spacing, directors 0.25λ spacing
+- Helix gain: Kraus formula (C²NS/λ³)
+- Horn gain: aperture efficiency formula
 
 ## Build & Run
 
@@ -50,6 +114,6 @@ mcp-cst-studio  # runs stdio server
 ```
 
 Environment variables:
-- `CST_PATH` — CST installation directory
-- `CST_WORK_DIR` — Working directory for projects
-- `CST_VERSION` — CST version (default: 2026)
+- `CST_PATH` — CST installation directory (auto-detected on Windows)
+- `CST_WORK_DIR` — Working directory for projects (default: ~/cst_projects)
+- `CST_VERSION` — CST version year (default: 2026)

README.md

@@ -108,11 +108,72 @@ Each template calculates dimensions from target frequency and generates a comple
 | Vivaldi | Planar | 5-12 dBi | 100%+ |
 | IFA/PIFA | Planar | 1-3 dBi | 5-10% |
 
+## Connected Mode Setup (Windows)
+
+To use with a live CST Studio installation:
+
+### Prerequisites
+
+- Windows 10/11 with CST Studio Suite 2024+ installed
+- CST Python libraries on your Python path (typically `C:\Program Files\CST Studio Suite 20XX\LinuxAMD64\python_cst_libraries`)
+- Python 3.10+
+
+### Setup
+
+```bash
+# 1. Clone and install
+git clone https://github.com/RFingAdam/mcp-cst-studio.git
+cd mcp-cst-studio
+pip install -e .
+
+# 2. Set environment (or let auto-detect find CST)
+set CST_PATH=C:\Program Files\CST Studio Suite 2026
+set CST_WORK_DIR=C:\cst_projects
+
+# 3. Add CST Python libs to PYTHONPATH
+set PYTHONPATH=%CST_PATH%\LinuxAMD64\python_cst_libraries;%PYTHONPATH%
+
+# 4. Verify
+python -c "import cst.interface; print('CST available')"
+mcp-cst-studio  # starts stdio server
+```
+
+### Claude Code / Claude Desktop
+
+Add to your `.mcp.json` or Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "cst-studio": {
+      "command": "mcp-cst-studio",
+      "env": {
+        "CST_PATH": "C:\\Program Files\\CST Studio Suite 2026",
+        "CST_WORK_DIR": "C:\\cst_projects",
+        "PYTHONPATH": "C:\\Program Files\\CST Studio Suite 2026\\LinuxAMD64\\python_cst_libraries"
+      }
+    }
+  }
+}
+```
+
+### Validation Checklist
+
+Once connected, verify with these prompts:
+
+1. **Connection**: "What is the CST connection status?" — should show `connected` mode
+2. **Geometry**: "Create a brick from (0,0,0) to (10,10,5) in component1" — should appear in CST
+3. **Antenna**: "Design a 2.4 GHz patch antenna on FR-4" — should build full model
+4. **Simulation**: "Run a time-domain simulation" — should start solver
+5. **Results**: "Show me the S-parameters" — should extract S11 data
+
 ## Development
 
 ```bash
 pip install -e ".[dev]"
-pytest tests/ -v
+pytest tests/ -v          # 215 tests, all offline
+ruff check src/ tests/    # linting
+mypy src/mcp_cst_studio/  # type checking
 ```
 
 ## License