lablink-mcp 0.1.0__tar.gz

lablink_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+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", "3.13"]
+
+    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 uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Run tests
+        run: pytest tests/ -v

lablink_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyc
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Pytest
+.pytest_cache/
+
+# Coverage
+.coverage
+htmlcov/
+
+# Environment files
+.env
+.env.*
+!examples/.env.example
+uv.lock
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Claude Code local config
+.claude/
+
+# Device configs (user-local, not for version control)
+# ~/.lablink/ lives outside the repo, but guard against accidents
+*.toml.local

lablink_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+First release of LabLink: five protocol drivers on a shared multi-driver
+dispatch core, exposed to AI agents over MCP and to developers over a CLI.
+
+### Added
+
+**Drivers**
+
+| Driver | Transport | Operation tools |
+|--------|-----------|----------------|
+| `visa` | PyVISA (USB-TMC, TCPIP, GPIB, Serial-VISA) | `visa_query`, `visa_write` |
+| `ssh` | Paramiko | `ssh_exec`, `ssh_shell_session`, `ssh_start_stream`, `ssh_read_stream`, `ssh_stop_stream` |
+| `rest` | httpx | `rest_get`, `rest_post`, `rest_put`, `rest_patch`, `rest_delete` |
+| `serial` | pyserial (RS232/RS422/RS485) | `serial_query`, `serial_write`, `serial_read`, `serial_flush` |
+| `python_shell` | subprocess | `python_shell_exec`, `python_shell_eval` |
+
+An `external` routing stub lets a device be handled by a vendor-supplied MCP
+server, surfacing routing hints to the agent on `connect()`.
+
+**SSH streaming.** `ssh_start_stream` / `ssh_read_stream` / `ssh_stop_stream`
+buffer the output of long-running commands (log tails, continuous monitors) in a
+bounded background queue, with clean teardown on stop and disconnect.
+
+**python_shell.** A persistent subprocess REPL bound to a user-supplied
+interpreter (`python_path`), bridging to vendor SDKs such as `nidaqmx` and
+`picosdk` that have no VISA or network interface. State persists across calls
+within a session. Communicates over a newline-delimited JSON wire protocol with
+timeout, crash, and busy-state recovery.
+
+**Architecture**
+
+- Shared lifecycle tools (`connect`, `disconnect`, `list_devices`, `diagnose`)
+  dispatch via the config `type` field across all drivers.
+- Per-driver operation tools register only when that driver's Python
+  dependencies are installed — missing deps are surfaced by `diagnose()`, never
+  a server crash.
+- Driver ABC (`LabLinkDriver[ConfigT]`) with a `Generic[ConfigT]` session model.
+- `AuthConfig` mixin for drivers that need credentials (SSH, REST), referenced by
+  environment variable name only — secrets never live in config files.
+- `DocumentedConfig` mixin carrying `techmanual_document_ids` for
+  [techmanual.ai](https://techmanual.ai) integration on T&M instruments.
+- JSONL event log with canonical `ts` / `op` / `alias` / `success` fields.
+- Three-state session lookup (missing / wrong type / found) for precise error
+  hints.
+- Optional dependency extras per driver (`[visa]`, `[ssh]`, `[rest]`, `[serial]`,
+  `[python_shell]`, `[all]`); the server runs with zero drivers installed.
+- CLI mirroring the MCP tool surface for development and debugging, with the same
+  dependency gating.
+
+### Validated
+
+- **VISA** — end-to-end on a Siglent SDS1104X-E (connect / diagnose / query /
+  write / device memory / event log).
+- **SSH** — unit tests plus a hardware smoke test on a Raspberry Pi 4 (exec,
+  shell session, and live streaming of an `rtl_433` capture).
+- **REST** — live against a public API across all five HTTP verbs.
+- **Serial** — unit tests with a mocked `serial.Serial`.
+- **python_shell** — unit tests plus real-subprocess integration tests exercising
+  the JSON wire protocol (exec, eval, exception/traceback, namespace persistence,
+  stdout capture, shutdown).

lablink_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to LabLink
+
+Thank you for considering a contribution. This document covers the essentials
+for getting oriented, making changes, and submitting them.
+
+---
+
+## Getting started
+
+```bash
+git clone https://github.com/techmanual-ai/lablink-mcp
+cd lablink-mcp
+uv venv
+uv pip install -e ".[dev]"
+```
+
+Run the tests to confirm your environment is clean:
+
+```bash
+pytest tests/
+```
+
+All tests mock hardware drivers — no real instruments required.
+
+---
+
+## Project structure
+
+```text
+lablink/
+├── mcp_server.py       # FastMCP entrypoint; shared lifecycle tools
+├── cli.py              # Click root; shared lifecycle commands
+├── base.py             # Data models, config dataclasses, driver ABC
+├── config.py           # TOML loader
+├── session.py          # Session registry
+├── event_logger.py     # JSONL event log
+├── exceptions.py       # ConfigError, SessionError, DriverError
+└── interfaces/
+    ├── visa/
+    ├── ssh/
+    ├── rest/
+    ├── serial/
+    ├── python_shell/
+    └── external_mcp/
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design.
+
+---
+
+## Adding a driver
+
+1. Create `lablink/interfaces/<type>/` with `driver.py`, `config.py`, `__init__.py`.
+2. Subclass `LabLinkDriver[YourConfig]`; implement `connect`, `disconnect`,
+   `diagnose`, `register_tools`, `register_cli_commands`.
+3. Subclass `DriverConfig` (`@dataclass(kw_only=True)`).
+4. Register it — one line in each of `DRIVER_REGISTRY` and
+   `DRIVER_CONFIG_REGISTRY` in `lablink/interfaces/__init__.py`.
+5. Write `tests/interfaces/test_<type>.py` with full mock coverage.
+6. Add `examples/configs/<type>_device.toml`.
+
+No changes to `lablink/mcp_server.py` or `lablink/cli.py` are required.
+
+---
+
+## Coding standards
+
+- Python 3.10+, PEP 8, strict type hints on all signatures.
+- Google-style docstrings. MCP tool docstrings are load-bearing: they are
+  surfaced to agents as the tool description.
+- Lazy-import all third-party driver deps inside `connect()`. Missing deps must
+  return a structured `{"success": false, "error": ..., "hint": ...}` dict —
+  never raise across the MCP boundary.
+- Every tool call logs via `event_logger.log_event()`. Logging must never raise.
+- Tests use `unittest.mock` to mock driver libraries. No real connections in CI.
+- `@dataclass(kw_only=True)` is mandatory on every config dataclass and result
+  type (see [docs/ARCHITECTURE.md §5.1](docs/ARCHITECTURE.md)).
+
+---
+
+## Commit style
+
+- Imperative mood: `Add REST driver`, `Fix VISA timeout reset`.
+- One feature or fix per commit.
+- Do not skip pre-commit hooks (`--no-verify`).
+
+---
+
+## Submitting a pull request
+
+1. Fork the repo and create a branch from `main`.
+2. Make your changes and add tests.
+3. Run `pytest tests/` and confirm it passes.
+4. Open a pull request with a clear description of what changed and why.
+
+For significant changes or new drivers, open an issue first to discuss the
+approach before investing time in implementation.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[MIT License](LICENSE).

lablink_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 techmanual-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.