@cyanheads/mcp-ts-core 0.12.6 → 0.12.7

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.9"
+  version: "2.10"
   audience: external
   type: debug
 ---
@@ -17,7 +17,7 @@ Unit tests (`add-test` skill) verify handler logic with mocked context. Field te
 
 ### Transport coverage
 
-This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface.
+This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface. Both HTTP session modes are covered: a durable `Mcp-Session-Id` session, and the sessionless initialization a `MCP_SESSION_MODE=stateless` server performs.
 
 **Stdio coverage is a boot check only — run this before Step 1.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
 
@@ -93,9 +93,26 @@ mcp_start() {
   echo "ready pid=$pid url=$url port=$port log=$server_log"
 }
 
+# Internal: report a failed initialize with the raw exchange, then clean up.
+_mcp_init_fail() {
+  local msg="$1"; local body_file="$2"; local hdr="$3"
+  echo "init failed — $msg" >&2
+  echo "--- response body ---" >&2
+  if [ -s "$body_file" ]; then cat "$body_file" >&2; else echo "(empty)" >&2; fi
+  echo "--- response headers ---" >&2
+  if [ -s "$hdr" ]; then cat "$hdr" >&2; else echo "(none)" >&2; fi
+  rm -f "$hdr" "$body_file"
+  return 1
+}
+
 # Usage: mcp_init <url>
 # Runs `initialize`, sends `notifications/initialized`, prints:
-#   ready sid=<id> protocol=<negotiated-version>
+#   ready sid=<id-or-empty> protocol=<negotiated-version> requested=<want> (HTTP <code>)
+# The initialize *result* is what decides success — a session ID is optional.
+# A server started with MCP_SESSION_MODE=stateless mints none, and the session
+# header is then omitted from every later request. Capture BOTH `sid` and
+# `protocol`: mcp_call takes the protocol as its 5th arg, which is what carries
+# the negotiated revision when there is no session to carry it.
 # A negotiated version older than the requested one means the server capped it
 # — note that in the report; you are then testing an older protocol than a
 # current client would use.
@@ -105,41 +122,57 @@ mcp_init() {
   local want="${MCP_FIELD_TEST_PROTOCOL:-2025-11-25}"
   local hdr; hdr=$(mktemp)
   local body_file; body_file=$(mktemp)
-  local code
+  local code curl_rc
   code=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$url" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"$want\",\"capabilities\":{},\"clientInfo\":{\"name\":\"field-test\",\"version\":\"1.0.0\"}}}")
-  local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
-  if [ -z "$sid" ]; then
-    echo "init failed — HTTP $code, no Mcp-Session-Id header returned" >&2
-    echo "--- response body ---" >&2
-    cat "$body_file" >&2
-    echo "--- response headers ---" >&2
-    cat "$hdr" >&2
-    rm -f "$hdr" "$body_file"
+  curl_rc=$?
+  if [ "$curl_rc" -ne 0 ] || [ -z "$code" ] || [ "$code" = "000" ]; then
+    _mcp_init_fail "transport failure — curl exit $curl_rc, http_code '${code:-none}'; nothing listening at $url" "$body_file" "$hdr"
     return 1
   fi
-  local got; got=$(sed -n 's/^data: //p' "$body_file" | grep -o '"protocolVersion":"[^"]*"' | head -1 | cut -d'"' -f4)
-  [ -z "$got" ] && got=$(grep -o '"protocolVersion":"[^"]*"' "$body_file" | head -1 | cut -d'"' -f4)
-  curl -sS -X POST "$url" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json, text/event-stream" \
-    -H "Mcp-Session-Id: $sid" \
+  [ "$code" -ge 400 ] && { _mcp_init_fail "HTTP $code" "$body_file" "$hdr"; return 1; }
+  # Unwrap SSE framing when present; a plain JSON body is used as-is.
+  local payload; payload=$(sed -n 's/^data: //p' "$body_file")
+  [ -z "$payload" ] && payload=$(cat "$body_file")
+  local reply; reply=$(printf '%s\n' "$payload" | grep -E '"(result|error)"' | head -1)
+  [ -z "$reply" ] && reply="$payload"
+  if printf '%s' "$reply" | grep -q '"error"'; then
+    _mcp_init_fail "server returned a JSON-RPC error" "$body_file" "$hdr"
+    return 1
+  fi
+  if ! printf '%s' "$reply" | grep -q '"result"'; then
+    _mcp_init_fail "HTTP $code but no JSON-RPC result in the body" "$body_file" "$hdr"
+    return 1
+  fi
+  local got; got=$(printf '%s' "$reply" | grep -o '"protocolVersion":"[^"]*"' | head -1 | cut -d'"' -f4)
+  if [ -z "$got" ]; then
+    _mcp_init_fail "initialize result declares no protocolVersion" "$body_file" "$hdr"
+    return 1
+  fi
+  local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
+  local init_headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: $got")
+  [ -n "$sid" ] && init_headers+=(-H "Mcp-Session-Id: $sid")
+  curl -sS -X POST "$url" "${init_headers[@]}" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
   rm -f "$hdr" "$body_file"
-  echo "ready sid=$sid protocol=${got:-unknown} requested=$want (HTTP $code)"
+  echo "ready sid=$sid protocol=$got requested=$want (HTTP $code)"
 }
 
-# Usage: mcp_call <url> <sid> <method> [JSON_PARAMS]
+# Usage: mcp_call <url> <sid> <method> [JSON_PARAMS] [protocol]
 # Prints the JSON-RPC response. SSE framing is stripped when present, and only
 # the reply is emitted (a single POST can also carry progress notifications, so
 # emitting every event would break `| jq .result`). A transport failure or an
 # HTTP >= 400 prints the details and returns non-zero — it never returns 0 with
 # empty output. Pipe to `jq`.
+# `sid` may be empty ('') for a stateless server; the session header is then
+# omitted. Pass the `protocol` mcp_init printed as the 5th arg — with no
+# session carrying the negotiation, MCP-Protocol-Version is what tells the
+# server which revision the request speaks.
 mcp_call() {
-  local url="$1"; local sid="$2"; local method="$3"; local params="${4:-}"
-  [ -z "$url" ] || [ -z "$sid" ] || [ -z "$method" ] && { echo "usage: mcp_call <url> <sid> <method> [params]" >&2; return 1; }
+  local url="$1"; local sid="$2"; local method="$3"; local params="${4:-}"; local protocol="${5:-}"
+  [ -z "$url" ] || [ -z "$method" ] && { echo "usage: mcp_call <url> <sid> <method> [params] [protocol]" >&2; return 1; }
   local body
   if [ -z "$params" ]; then
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s"}' "$RANDOM" "$method")
@@ -148,11 +181,10 @@ mcp_call() {
   fi
   local resp_file; resp_file=$(mktemp)
   local code curl_rc
-  code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$url" \
-    -H "Content-Type: application/json" \
-    -H "Accept: application/json, text/event-stream" \
-    -H "Mcp-Session-Id: $sid" \
-    -d "$body")
+  local headers=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream")
+  [ -n "$sid" ] && headers+=(-H "Mcp-Session-Id: $sid")
+  [ -n "$protocol" ] && headers+=(-H "MCP-Protocol-Version: $protocol")
+  code=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$url" "${headers[@]}" -d "$body")
   curl_rc=$?
   if [ "$curl_rc" -ne 0 ] || [ -z "$code" ] || [ "$code" = "000" ]; then
     echo "TRANSPORT FAILURE calling $method — curl exit $curl_rc, http_code '${code:-none}'." >&2
@@ -241,11 +273,19 @@ Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later
 mcp_init <url-from-mcp_start>
 ```
 
-Runs `initialize`, sends `notifications/initialized`, prints `sid=<id>` to capture for `mcp_call`, plus the protocol version the server negotiated.
+Runs `initialize`, sends `notifications/initialized`, prints the `sid` and `protocol` to capture for `mcp_call`. Success is decided by the initialize *result*, so a transport failure, a non-2xx status, a JSON-RPC error, a malformed body, or a result with no `protocolVersion` all fail loudly with the raw exchange.
 
 The helper requests the newest `initialize`-negotiated revision the SDK supports (`2025-11-25`). **If `protocol=` comes back older than `requested=`, the server capped it** — every call after that exercises an older protocol than a current client would negotiate. Note it as a `bug` finding and check the pinned `@modelcontextprotocol/server` version; don't quietly test the downgraded surface. To deliberately test an older version, set `MCP_FIELD_TEST_PROTOCOL`.
 
-This exercises the **2025-era arm**: `initialize` negotiates the revision, the server mints an `Mcp-Session-Id`, and every later call rides that session. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is not in the `initialize` ladder at all — it is selected per request by the `io.modelcontextprotocol/protocolVersion` key in the request's own `_meta` envelope, and carries no session. Curl-based field testing therefore covers the sessionful leg; exercise the per-request leg from a real 2026-era client or an integration test.
+**`sid=` may come back empty — that is a pass, not a failure.** Under `MCP_SESSION_MODE=stateless` the server mints no `Mcp-Session-Id`, and the helper then omits the session header from every later request. Thread the empty value through positionally and pass the negotiated protocol, which is what identifies the revision when no session carries it:
+
+```bash
+mcp_call <url> '' tools/list '' <protocol-from-mcp_init>
+```
+
+To exercise both session modes, start the server twice — once with the project's default, once with `MCP_SESSION_MODE=stateless` — and run the same calls against each.
+
+Both modes exercise the **2025-era arm**: `initialize` negotiates the revision, and the session (when there is one) carries it. The [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) is a different thing from a sessionless 2025 handshake — it does not initialize at all, and is selected per request by the `io.modelcontextprotocol/protocolVersion` key in the request's own `_meta` envelope. This helper does not reach it; exercise the per-request leg from a real 2026-era client or an integration test.
 
 ### 3. Surface the catalog
 
@@ -379,7 +419,7 @@ End with:
 
 - [ ] Stdio boot check completed — `bun run rebuild && bun run start:stdio` shows clean startup (banner, expected counts, no errors)
 - [ ] HTTP server built and started; real port parsed from log
-- [ ] Session initialized; `notifications/initialized` sent; negotiated protocol version matches the requested one (a downgrade is a finding)
+- [ ] Session initialized (a stateless server returns an empty `sid` — still a pass); `notifications/initialized` sent; negotiated protocol version matches the requested one (a downgrade is a finding)
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
 - [ ] Universal battery run on every definition (happy path, parity against the full `content[]` array, input error)
 - [ ] Situational categories applied only when triggered

package/skills/git-wrapup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts) and an annotated tag. Verify, commit, tag. Stops at "committed and tagged locally" — no push, no publish. The release-and-publish skill picks up from here. Distilled from the git_wrapup_instructions protocol.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "1.12"
   audience: external
   type: workflow
 ---
@@ -69,6 +69,7 @@ Every file that declares a version must be updated. Skip any file that doesn't e
 - `package.json` — `version`
 - `server.json` — top-level `version` AND every `packages[].version` entry
 - `manifest.json` (if present) — `version`. Verify `name` is the bare package name (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`)
+- `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` (if present) — `version`. Packaging validation fails on a mismatch; `.codex-plugin/mcp.json` is connection config and carries none
 - `README.md` — version badge
 - `CLAUDE.md` / `AGENTS.md` — if they pin a version string
 - `Dockerfile` — OCI labels if they pin the version
@@ -129,7 +130,7 @@ bun run test:package       # only if the script exists — NOT part of test:all
 Do NOT `git add -A` into one commit. Group the working tree into a handful of logical commits — never one blob:
 
 1. **The work — one commit per concern.** A feature spanning multiple layers splits by layer: runtime/logic, linter/tooling, docs/skills. Unrelated changes (two separate fixes, an incidental doc tweak) are their own commits. Work commits do not carry the version.
-2. **The release commit — last, on top.** Version bumps (`package.json`, `server.json`, README badge, `CLAUDE.md`/`AGENTS.md`), the changelog entry, `CHANGELOG.md`, and `docs/tree.md` go in a single final commit that sits on top of the work stack — never mixed into a feature commit.
+2. **The release commit — last, on top.** Version bumps (`package.json`, `server.json`, `manifest.json`, the plugin manifests, README badge, `CLAUDE.md`/`AGENTS.md`), the changelog entry, `CHANGELOG.md`, and `docs/tree.md` go in a single final commit that sits on top of the work stack — never mixed into a feature commit.
 
 Stage each group explicitly, commit it, then move to the next — the release commit goes last:
 
@@ -230,7 +231,7 @@ If the working tree isn't clean or the tag doesn't point at HEAD, something went
 ## Checklist
 
 - [ ] Diff reviewed end-to-end before version bump
-- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
+- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
 - [ ] GH issues addressed by this work commented with what landed (if working from GH issues)
 - [ ] Docs updated for any new or changed features
 - [ ] Changelog authored at `changelog/<major.minor>.x/<version>.md`

package/templates/package.json

@@ -65,15 +65,15 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.5",
+    "@biomejs/biome": "2.5.12",
     "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@types/node": "26.1.1",
-    "@vitest/coverage-istanbul": "4.1.10",
+    "@types/node": "26.4.0",
+    "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
     "fast-check": "^4.9.0",
-    "ignore": "^7.0.6",
-    "tsc-alias": "^1.9.1",
+    "ignore": "^7.0.7",
+    "tsc-alias": "^1.9.2",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }