skillscript-runtime 0.15.5 → 0.15.6

package/docs/adopter-playbook.md

@@ -83,22 +83,33 @@ This same skill body runs unchanged against your substrate, against SQLite-FTS (
 
 ### Case 2 — MCP-tools wiring (substrate-locked)
 
-Your substrate exposes itself as MCP tools (via a local MCP server or remote one). You wire it as an `McpConnector` (typically `RemoteMcpConnector` for spawned MCP processes) and skills reference its tools by name with substrate-specific kwargs.
+Your substrate exposes itself as MCP tools (via a local MCP server or remote one). You wire it as an `McpConnector` and skills reference its tools by name with substrate-specific kwargs.
 
-```typescript
-// connectors.json:
-{
-  "my_store": {
-    "class": "RemoteMcpConnector",
-    "config": {
-      "command": "my-store-mcp-server",
-      "args": ["--db", "/var/store"]
+**MCP transport — two paths.** The protocol's wire layer is the same; the transport differs:
+
+- **Stdio MCP** (most common for community servers — YouTrack, GitHub, Linear, etc.): the MCP server is a binary you spawn as a child process and communicate with via stdin/stdout. Wired via `RemoteMcpConnector`:
+
+  ```json
+  {
+    "my_store": {
+      "class": "RemoteMcpConnector",
+      "config": {
+        "command": "my-store-mcp-server",
+        "args": ["--db", "/var/store"]
+      }
     }
   }
-}
-```
+  ```
+
+- **HTTP MCP / Streamable HTTP** (Anthropic's hosted MCP, AMP, increasingly common for hosted services): the MCP server speaks JSON-RPC over HTTP with Server-Sent Events for the stream channel. Two ways to wire it:
+
+  - **(a) Stdio bridge** — `RemoteMcpConnector` + `npx mcp-remote https://... --sse` runs a node child process that bridges HTTPS-SSE into stdio for the runtime to consume. Works today; adds the bridge subprocess.
+  - **(b) Direct HTTP connector** — wire your own `McpConnector` class against the HTTP transport (no subprocess). See `examples/connectors/McpConnectorTemplate/` for the fork template.
+
+Pick (a) for quick wiring against a remote HTTP MCP server with no implementation effort; pick (b) when subprocess overhead matters or you want direct control over connection lifecycle.
+
+**In skills**, regardless of transport:
 
-**In skills:**
 ```
 $ my_store.search query="customer feedback" region="eu-west" cluster="prod" -> CONTEXT
 ```

package/examples/connectors/McpConnectorTemplate/README.md

@@ -14,13 +14,15 @@ A skeleton `McpConnector` implementation for adopters writing their own. Not run
 
 **Fork this template only when none of those fit** — e.g.:
 
-- Direct HTTP MCP (JSON-RPC over HTTP, no child process)
+- Direct HTTP MCP (JSON-RPC over HTTP, no child process) — for now; check the bundled `McpConnector` classes before forking, as a bundled `HttpMcpConnector` is on the near-term roadmap
 - WebSocket MCP
 - In-process MCP (call methods directly without IPC)
 - Custom transport that doesn't match stdio framing
 - Cross-thread / worker-pool dispatch
 
-If you're trying to wire a remote MCP server like YouTrack or GitHub, **you want `RemoteMcpConnector` in `connectors.json`**, not this template. See `connectors.json.example` for the wiring pattern.
+If you're trying to wire a remote stdio MCP server like YouTrack or GitHub, **you want `RemoteMcpConnector` in `connectors.json`**, not this template. See `connectors.json.example` for the wiring pattern.
+
+If you're trying to wire a Streamable HTTP MCP server (AMP, Anthropic's hosted MCP, etc.), the simplest path today is `RemoteMcpConnector` + `npx mcp-remote https://... --sse` (bridges HTTPS-SSE into stdio via a node subprocess). For lower overhead (no subprocess layer) check whether a bundled `HttpMcpConnector` is available in your installed runtime version — if so, declare an instance in `connectors.json` rather than forking this template.
 
 ## Forking workflow
 

package/examples/onboarding-scaffold/connectors.json

@@ -1,6 +1,8 @@
 {
   "_comment": "Onboarding scaffold connectors.json — wires example MCP servers an adopter might add alongside the bundled bridges. Most onboarding deployments don't need anything here; the file-backed data store + OpenAI LLM + tmux-shell wiring lives in bootstrap.ts. This file is the place for adopter-specific MCP servers (your in-house tools, a YouTrack instance, a custom agent API, etc.).",
 
+  "_comment_transport": "RemoteMcpConnector bridges stdio MCP servers. The `mcp-remote` shape below also bridges Streamable HTTP MCP servers (the wire transport increasingly common for hosted MCPs — Anthropic's hosted MCP, AMP, etc.): `mcp-remote https://endpoint/sse` runs a node subprocess that adapts HTTPS-SSE to stdio for the runtime. For lower overhead (no subprocess layer), wire a direct HTTP MCP connector class — see docs/adopter-playbook.md §Case 2 and examples/connectors/McpConnectorTemplate/.",
+
   "_example_remote_mcp": {
     "class": "RemoteMcpConnector",
     "config": {

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-01T20:23:35.853Z",
+  "compiled_at": "2026-06-01T20:44:19.882Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.15.5",
+  "version": "0.15.6",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",