runspec-mcp 0.1.0__tar.gz

runspec_mcp-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `runspec-mcp` are documented here.
+
+## [0.1.0]
+
+Initial release. A local MCP **gateway** that connects Claude Code to local and
+remote runspec runnables from one config file.
+
+- Aggregating MCP stdio server (`runspec-mcp serve`) over local venvs and remote
+  SSH venvs, discovering runnables via `runspec local --format json` and expanding
+  them into leaf MCP tools identical to `runspec serve`.
+- **Live discovery**: declares `tools.listChanged` and pushes
+  `notifications/tools/list_changed` from a background discovery thread — the tool
+  list stays current with no restart or manual refresh.
+- **Credential injection** as name-derived environment variables (reusing the
+  runspec-console convention; secrets in the OS keychain, shared service name),
+  auto-matched to runnables by their declared arg `env` or by scope globs.
+- One config file (`runspec_mcp.toml`), or reuse of an existing runspec-console
+  config directory (`--config-dir`), or a bundled **config seed** package.
+- **Managed SSH keypair**: the gateway generates and uses its own ed25519 key as
+  the default SSH identity (no `~/.ssh` setup needed); `runspec-mcp copy-key`
+  installs the public key on hosts over a one-time password login, and
+  `runspec-mcp key` shows / rotates it. A per-host `identity_file` and the
+  ssh-agent / default keys still work.
+- Ships a Claude Code plugin (MCP server entry + autonomy PreToolUse hook, whose
+  manifest the gateway keeps fresh + slash commands).
+- Transport/credentials/config layer vendored from runspec-console, kept
+  behaviour-identical by parity tests.

runspec_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: runspec-mcp
+Version: 0.1.0
+Summary: Connect Claude Code to local and remote runspec runnables as MCP tools, from one config file
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41
+Requires-Dist: paramiko>=3.0
+Requires-Dist: runspec>=0.48.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: credentials
+Requires-Dist: keyring>=24; extra == 'credentials'
+Provides-Extra: dev
+Requires-Dist: keyring>=24; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
+Requires-Dist: runspec-console; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runspec-mcp
+
+Connect **Claude Code** to the runspec runnables installed across your machines —
+local venvs and remote SSH venvs — from **one config file**, with credentials
+injected as environment variables and each runnable's declared `autonomy` carried
+into Claude Code's permission layer.
+
+`runspec-mcp` is a small local **MCP gateway**: Claude Code spawns it as a
+single MCP server; it reads your hosts + credential metadata, discovers the
+runnables in every configured venv (`runspec local --format json`, locally and
+over SSH), and presents them all as MCP tools. Discovery is **live** — as hosts
+connect/disconnect or their runnables change, the tool list updates automatically
+(no restart, no manual refresh).
+
+```
+pip install "runspec-mcp[credentials]"
+# write runspec_mcp.toml (or point at an existing runspec-console config dir)
+claude --plugin-dir "$(runspec-mcp plugin-path)"
+```
+
+**Any MCP client** (Claude Desktop, Cursor, Cline, or Claude Code without the
+plugin) works too — `runspec-mcp serve` is a standard MCP stdio server. Add a
+`mcpServers` entry:
+
+```json
+{ "mcpServers": { "runspec-mcp": {
+    "command": "runspec-mcp", "args": ["serve"],
+    "env": { "RUNSPEC_MCP_CONFIG": "/absolute/path/to/runspec_mcp.toml" } } } }
+```
+
+The Claude Code plugin adds one thing over a bare client: the PreToolUse hook that
+auto-approves `autonomous` runnables. Either way, `manual` runnables are refused
+by the gateway and `password` args never reach a tool schema. See
+[`docs/mcp.md`](../../../docs/mcp.md) for per-client details and the config-seed
+("fleet adapter") how-to.
+
+## Config (`runspec_mcp.toml`)
+
+```toml
+[local]
+venv_globs = ["~/venvs/*"]                       # local multi-venv discovery
+
+[gateway]
+refresh_interval = 30                             # background rediscovery cadence (s); 0 = off
+
+[[host]]
+name = "prod"
+ssh = "deploy@prod.example.com"                  # omit ssh → this machine
+runspec_paths = ["/opt/venvs/fleet/bin/runspec"]
+jump = "bastion"                                 # optional ProxyJump (system ssh)
+
+[[credential]]
+id = "Windows"                                   # label → WINDOWS_* env vars
+kind = "userpass"                                # userpass | password | token | ssh-key
+username = "svc-bot"
+# secret stored in the OS keychain:  runspec-mcp cred set Windows
+# scope_hosts / scope_runnables optional — else auto-matched by a runnable's arg `env`
+```
+
+A runnable that declares it reads `WINDOWS_USERNAME` / `WINDOWS_PASSWORD` (via an
+arg `env`) auto-pulls the `Windows` credential — no scope config needed.
+
+Secrets live in the OS keychain (`keyring`), keyed by credential `id` under the
+`runspec-console` service, so they are **shared with the desktop console**. Point
+the gateway at an existing console setup with `--config-dir <dir>`.
+
+## SSH keys
+
+**No SSH key ever goes in the MCP config** — only path references. The gateway
+manages its **own ed25519 keypair** and uses it as the default SSH identity, so you
+never touch `~/.ssh`; authorise it on your hosts once:
+
+```bash
+runspec-mcp key                    # print the managed public key
+runspec-mcp copy-key --all         # install it on every configured host (one password prompt)
+```
+
+A per-host `identity_file` path still overrides it, and ssh-agent / `~/.ssh/id_*`
+remain a fallback.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `runspec-mcp serve` | the MCP gateway (what the plugin runs) |
+| `runspec-mcp hosts` | list configured hosts + probe connectivity |
+| `runspec-mcp discover [--host H]` | print discovered tools |
+| `runspec-mcp key [--regenerate]` | show / rotate the managed SSH key |
+| `runspec-mcp copy-key [--all] [HOST…]` | install the managed key on host(s) |
+| `runspec-mcp cred set\|list\|rm ID` | manage credential secrets in the keychain |
+| `runspec-mcp seed-status` | show bundled config-seed contributors |
+| `runspec-mcp plugin-path` | print the bundled Claude Code plugin dir |
+| `runspec-mcp check` | validate config + connectivity + manifest |
+
+## Autonomy
+
+Each runnable's `autonomy` maps onto a Claude Code permission decision via a
+PreToolUse hook the plugin ships (`autonomous → allow`, `confirm`/`supervised →
+ask`, `manual → deny`, unknown → ask). The gateway rewrites the hook's manifest on
+every discovery change, so it is always fresh. The remote side stays authoritative
+(venv denylist, `enforce_run_as`, `password` args omitted from schemas).

runspec_mcp-0.1.0/README.md

@@ -0,0 +1,101 @@
+# runspec-mcp
+
+Connect **Claude Code** to the runspec runnables installed across your machines —
+local venvs and remote SSH venvs — from **one config file**, with credentials
+injected as environment variables and each runnable's declared `autonomy` carried
+into Claude Code's permission layer.
+
+`runspec-mcp` is a small local **MCP gateway**: Claude Code spawns it as a
+single MCP server; it reads your hosts + credential metadata, discovers the
+runnables in every configured venv (`runspec local --format json`, locally and
+over SSH), and presents them all as MCP tools. Discovery is **live** — as hosts
+connect/disconnect or their runnables change, the tool list updates automatically
+(no restart, no manual refresh).
+
+```
+pip install "runspec-mcp[credentials]"
+# write runspec_mcp.toml (or point at an existing runspec-console config dir)
+claude --plugin-dir "$(runspec-mcp plugin-path)"
+```
+
+**Any MCP client** (Claude Desktop, Cursor, Cline, or Claude Code without the
+plugin) works too — `runspec-mcp serve` is a standard MCP stdio server. Add a
+`mcpServers` entry:
+
+```json
+{ "mcpServers": { "runspec-mcp": {
+    "command": "runspec-mcp", "args": ["serve"],
+    "env": { "RUNSPEC_MCP_CONFIG": "/absolute/path/to/runspec_mcp.toml" } } } }
+```
+
+The Claude Code plugin adds one thing over a bare client: the PreToolUse hook that
+auto-approves `autonomous` runnables. Either way, `manual` runnables are refused
+by the gateway and `password` args never reach a tool schema. See
+[`docs/mcp.md`](../../../docs/mcp.md) for per-client details and the config-seed
+("fleet adapter") how-to.
+
+## Config (`runspec_mcp.toml`)
+
+```toml
+[local]
+venv_globs = ["~/venvs/*"]                       # local multi-venv discovery
+
+[gateway]
+refresh_interval = 30                             # background rediscovery cadence (s); 0 = off
+
+[[host]]
+name = "prod"
+ssh = "deploy@prod.example.com"                  # omit ssh → this machine
+runspec_paths = ["/opt/venvs/fleet/bin/runspec"]
+jump = "bastion"                                 # optional ProxyJump (system ssh)
+
+[[credential]]
+id = "Windows"                                   # label → WINDOWS_* env vars
+kind = "userpass"                                # userpass | password | token | ssh-key
+username = "svc-bot"
+# secret stored in the OS keychain:  runspec-mcp cred set Windows
+# scope_hosts / scope_runnables optional — else auto-matched by a runnable's arg `env`
+```
+
+A runnable that declares it reads `WINDOWS_USERNAME` / `WINDOWS_PASSWORD` (via an
+arg `env`) auto-pulls the `Windows` credential — no scope config needed.
+
+Secrets live in the OS keychain (`keyring`), keyed by credential `id` under the
+`runspec-console` service, so they are **shared with the desktop console**. Point
+the gateway at an existing console setup with `--config-dir <dir>`.
+
+## SSH keys
+
+**No SSH key ever goes in the MCP config** — only path references. The gateway
+manages its **own ed25519 keypair** and uses it as the default SSH identity, so you
+never touch `~/.ssh`; authorise it on your hosts once:
+
+```bash
+runspec-mcp key                    # print the managed public key
+runspec-mcp copy-key --all         # install it on every configured host (one password prompt)
+```
+
+A per-host `identity_file` path still overrides it, and ssh-agent / `~/.ssh/id_*`
+remain a fallback.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `runspec-mcp serve` | the MCP gateway (what the plugin runs) |
+| `runspec-mcp hosts` | list configured hosts + probe connectivity |
+| `runspec-mcp discover [--host H]` | print discovered tools |
+| `runspec-mcp key [--regenerate]` | show / rotate the managed SSH key |
+| `runspec-mcp copy-key [--all] [HOST…]` | install the managed key on host(s) |
+| `runspec-mcp cred set\|list\|rm ID` | manage credential secrets in the keychain |
+| `runspec-mcp seed-status` | show bundled config-seed contributors |
+| `runspec-mcp plugin-path` | print the bundled Claude Code plugin dir |
+| `runspec-mcp check` | validate config + connectivity + manifest |
+
+## Autonomy
+
+Each runnable's `autonomy` maps onto a Claude Code permission decision via a
+PreToolUse hook the plugin ships (`autonomous → allow`, `confirm`/`supervised →
+ask`, `manual → deny`, unknown → ask). The gateway rewrites the hook's manifest on
+every discovery change, so it is always fresh. The remote side stays authoritative
+(venv denylist, `enforce_run_as`, `password` args omitted from schemas).

runspec_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-mcp"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Connect Claude Code to local and remote runspec runnables as MCP tools, from one config file"
+readme = "README.md"
+license = "MIT"
+dependencies = [
+    # 0.48.0 for the `discoverable` boolean + serve leaf globals; the gateway
+    # reuses runspec.cli._build_schema and runspec.become.build_become_argv.
+    "runspec>=0.48.0",
+    # Warm SSH connection pool for remote venvs (mirrors runspec-console).
+    "paramiko>=3.0",
+    # Managed ed25519 keypair generation (also a transitive paramiko dep).
+    "cryptography>=41",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+# Secret storage in the OS keychain. Without it the gateway still runs; only
+# credential injection is disabled (same opt-in split as runspec-console).
+credentials = ["keyring>=24"]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+    "keyring>=24",
+    # Dev-only: the parity tests import the console originals to assert the
+    # vendored transport/credential/merge helpers behave identically.
+    "runspec-console",
+]
+
+[project.scripts]
+runspec-mcp = "runspec_mcp.cli:main"
+
+# A corporate seed package can ship a config_seed/ dir under either group; the
+# fleet reads both so one seed configures the console and the plugin alike.
+# [project.entry-points."runspec_mcp.config_seed"]
+# mycorp = "mycorp_fleet"
+
+[tool.hatch.build.targets.wheel]
+# The Claude Code plugin under runspec_mcp/plugin/ ships as package data so
+# `runspec-mcp plugin-path` can point Claude Code at it.
+packages = ["runspec_mcp"]
+artifacts = ["runspec_mcp/plugin/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+# Vendored-verbatim modules follow the console's own typing upstream; kept
+# honest by tests/test_parity.py rather than re-checked here.
+exclude = "runspec_mcp/(executor|ssh_pool|configmerge|hosts)\\.py$"
+
+[[tool.mypy.overrides]]
+module = ["paramiko.*", "keyring.*", "tomli", "runspec.*", "runspec_console.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+# These modules are vendored verbatim from runspec-console and kept
+# behaviour-identical by tests/test_parity.py — they follow the console's own
+# lint config upstream; restyling them here would create drift, so we don't lint
+# them locally.
+extend-exclude = ["runspec_mcp/executor.py", "runspec_mcp/ssh_pool.py", "runspec_mcp/configmerge.py", "runspec_mcp/hosts.py", "runspec_mcp/plugin"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+# try/except/pass with an explanatory comment (best-effort swallow) reads more
+# clearly than contextlib.suppress here, and matches the vendored modules.
+ignore = ["SIM105"]

runspec_mcp-0.1.0/runspec_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""
+runspec-mcp — connect Claude Code to local and remote runspec runnables.
+
+A single local MCP *gateway* server that reads one config file (hosts + credential
+metadata), discovers the runnables installed in every configured venv (local and
+over SSH), and presents them all to Claude Code as MCP tools — with each
+runnable's declared ``autonomy`` carried into Claude Code's permission layer and
+credentials injected as environment variables the way runspec-console does.
+
+The public surface is the ``runspec-mcp`` CLI (see ``cli.py``); the MCP server
+is ``runspec-mcp serve``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"