Field Test

# Pick your ID — example below uses 9DJ73-K103L. Substitute your own.
# (Helper path also encodes the project name so /tmp/ stays grep-friendly.)
cat > /tmp/<project-name>-field-test-9DJ73-K103L.sh <<'HELPER_EOF'
#!/bin/bash
# Field-test helper: stateless wrappers around an MCP HTTP server + JSON-RPC
# session. Every function takes the IDs it needs as positional args — the agent
# threads pid/url/port/sid/log through each call rather than relying on a state
# file or env vars (the Bash tool wipes shell state between calls, and a
# pointer file would race the same way two agents race on shared state).
# See https://github.com/cyanheads/mcp-ts-core/issues/90, #144.
#
# Surfaces failures aggressively — field test is for finding things that fail,
# so the helper auto-tails logs and prints HTTP status/body on errors instead
# of swallowing them. It also measures: every mcp_call prints a one-line
# size/latency reading on stderr, and mcp_catalog_size weighs tools/list.

# Usage: mcp_start /path/to/server [startup-timeout-seconds]   (default: 30)
# Builds, starts the HTTP server in the background, waits for the listen line,
# and prints: ready pid=<n> url=<u> port=<n> log=<path>
# Capture these — every later helper takes them as args. Raise the timeout for
# servers that build a local index at boot.
mcp_start() {
  local dir="${1:-$PWD}"
  local timeout="${2:-30}"
  local build_log; build_log=$(mktemp /tmp/mcp-field-test-build.XXXXXX)
  echo "building $dir ..." >&2
  if ! (cd "$dir" && bun run rebuild) >"$build_log" 2>&1; then
    echo "BUILD FAILED — last 30 lines of $build_log:" >&2
    tail -30 "$build_log" >&2
    return 1
  fi
  rm -f "$build_log"
  local server_log; server_log=$(mktemp /tmp/mcp-field-test-server.XXXXXX)
  echo "starting server ..." >&2
  (cd "$dir" && bun run start:http) >"$server_log" 2>&1 &
  local pid=$!
  local line=""
  local waited=0
  while [ "$waited" -lt "$((timeout * 4))" ]; do
    line=$(grep -Eo 'listening at http://[^" ]+/mcp' "$server_log" | head -1)
    [ -n "$line" ] && break
    if ! kill -0 "$pid" 2>/dev/null; then
      echo "server exited during startup — last 30 lines of $server_log:" >&2
      tail -30 "$server_log" >&2
      rm -f "$server_log"
      return 1
    fi
    sleep 0.25
    waited=$((waited + 1))
  done
  if [ -z "$line" ]; then
    echo "server failed to start within ${timeout}s — last 30 lines of $server_log:" >&2
    tail -30 "$server_log" >&2
    kill "$pid" 2>/dev/null
    rm -f "$server_log"
    return 1
  fi
  local url="${line#listening at }"
  local port; port=$(echo "$url" | sed -E 's|.*:([0-9]+)/.*|\1|')
  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-or-empty> protocol=<negotiated-version> requested=<want> instructions=<bytes>B (HTTP <code>)
# `instructions=` is the byte size of the server's `instructions` string — it
# loads into every client session alongside tools/list, so it is the other half
# of the per-session context tax mcp_catalog_size weighs.
# 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.
mcp_init() {
  local url="$1"
  [ -z "$url" ] && { echo "usage: mcp_init <url>" >&2; return 1; }
  local want="${MCP_FIELD_TEST_PROTOCOL:-2025-11-25}"
  local hdr; hdr=$(mktemp)
  local body_file; body_file=$(mktemp)
  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\"}}}")
  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
  [ "$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")
  # Pick the reply frame by structure, not by substring: a server that logs to the
  # client emits `notifications/message` frames first, and a `"level":"error"` or a
  # log string containing `result` matches a text grep and gets read as the reply.
  local reply; reply=$(printf '%s\n' "$payload" | jq -c 'select(type=="object" and (has("result") or has("error")))' 2>/dev/null | tail -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 instr; instr=$(printf '%s' "$reply" | jq -r '.result.instructions // "" | utf8bytelength' 2>/dev/null || echo 0)
  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 requested=$want instructions=${instr}B (HTTP $code)"
}

# Internal: one stderr line per call — reply bytes, the content/structured
# split, a token estimate, wall-clock. Bytes are the reply as delivered (SSE
# framing stripped). `content` is every text block's bytes, `structured` is
# structuredContent serialized. The token figure is bytes/4 — an estimate, not
# a tokenizer. Wall-clock is curl's time_total for the whole exchange.
_mcp_measure() {
  local method="$1"; local params="$2"; local reply="$3"; local code="$4"; local secs="$5"
  local total; total=$(printf '%s' "$reply" | wc -c | tr -d ' ')
  local ms; ms=$(awk -v s="$secs" 'BEGIN { printf "%d", s * 1000 }')
  local label="$method"
  local split=""
  case "$method" in
    tools/call)
      local name; name=$(printf '%s' "$params" | jq -r '.name // empty' 2>/dev/null)
      [ -n "$name" ] && label="$method $name"
      split=$(printf '%s' "$reply" | jq -r '
        (.result // {}) as $r
        | ([$r.content[]? | select(.type == "text") | .text] | join("") | utf8bytelength) as $c
        | (if $r.structuredContent == null then "none" else ($r.structuredContent | tojson | utf8bytelength | tostring) end) as $s
        | "content \($c) · structured \($s)"' 2>/dev/null)
      ;;
    resources/read)
      split=$(printf '%s' "$reply" | jq -r '
        "text \([.result.contents[]? | .text // ""] | join("") | utf8bytelength)"' 2>/dev/null)
      ;;
  esac
  local tok; tok=$(awk -v b="$total" 'BEGIN { if (b >= 1000) printf "~%.1fk", b / 4000; else printf "~%d", b / 4 }')
  echo "⏱ $label · HTTP $code · ${total} B${split:+ ($split)} · $tok tok · ${ms} ms" >&2
}

# 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`.
# Every call also prints one measurement line on stderr, e.g.
#   ⏱ tools/call gbif_search_species · HTTP 200 · 18412 B (content 9100 · structured 8900) · ~4.6k tok · 812 ms
# Read it on every call — it is the size/latency evidence the report cites.
# `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:-}"; 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")
  else
    body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
  fi
  local resp_file; resp_file=$(mktemp)
  local stats code secs curl_rc
  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")
  stats=$(curl -sS -o "$resp_file" -w '%{http_code} %{time_total}' -X POST "$url" "${headers[@]}" -d "$body")
  curl_rc=$?
  read -r code secs <<< "$stats"
  if [ "$curl_rc" -ne 0 ] || [ -z "$code" ] || [ "$code" = "000" ]; then
    echo "TRANSPORT FAILURE calling $method — curl exit $curl_rc, http_code '${code:-none}'." >&2
    echo "Server not reachable at $url (check it is still running: mcp_log <log>)." >&2
    rm -f "$resp_file"
    return 1
  fi
  if [ "$code" -ge 400 ]; then
    echo "HTTP $code from $method — response:" >&2
    cat "$resp_file" >&2
    rm -f "$resp_file"
    return 1
  fi
  local reply
  local sse; sse=$(sed -n 's/^data: //p' "$resp_file")
  if [ -n "$sse" ]; then
    # Structural pick, same reason as in mcp_init: log-notification frames precede
    # the reply and can carry the literal tokens a text grep keys on.
    reply=$(printf '%s\n' "$sse" | jq -c 'select(type=="object" and (has("result") or has("error")))' 2>/dev/null | tail -1)
    reply="${reply:-$sse}"
  else
    reply=$(cat "$resp_file")
  fi
  rm -f "$resp_file"
  _mcp_measure "$method" "$params" "$reply" "$code" "$secs"
  printf '%s\n' "$reply"
}

# Usage: mcp_catalog_size <url> <sid> [protocol]
# Weighs the catalog: the bytes of the tools/list reply — what every client
# loads into context per session before a single call — then each tool's
# serialized entry, largest first, split into description / inputSchema /
# outputSchema so the row says WHERE the weight is. A fat outputSchema costs as
# much as a fat description and is the usual surprise. Prints:
#   catalog: 12 tools · 48210 B · ~12.1k tok
#   <bytes>  <~tok>  <name>  desc <b> · input <b> · output <b|none>   (one row per tool)
mcp_catalog_size() {
  local url="$1"; local sid="$2"; local protocol="${3:-}"
  [ -z "$url" ] && { echo "usage: mcp_catalog_size <url> <sid> [protocol]" >&2; return 1; }
  local reply; reply=$(mcp_call "$url" "$sid" tools/list '' "$protocol") || return 1
  printf '%s' "$reply" | jq -r '
    def tok: if . >= 1000 then "~\(. / 4000 * 10 | round / 10)k" else "~\(. / 4 | floor)" end;
    def bytes_or_none: if . == null then "none" else (tojson | utf8bytelength | tostring) end;
    (.result.tools // []) as $t
    | (. | tojson | utf8bytelength) as $total
    | "catalog: \($t | length) tools · \($total) B · \($total | tok) tok",
      ($t
       | map({name, b: (tojson | utf8bytelength),
              d: ((.description // "") | utf8bytelength),
              i: (.inputSchema | bytes_or_none),
              o: (.outputSchema | bytes_or_none)})
       | sort_by(-.b) | .[]
       | "\(.b)\t\(.b | tok)\t\(.name)\tdesc \(.d) · input \(.i) · output \(.o)")'
}

# Usage: mcp_log <server-log-path> [N]   (default: 50 lines)
# Tail the per-server log printed by mcp_start. Useful when a call surprises
# you — pino startup banner, definition lint diagnostics, request handler
# errors, upstream calls, and rate-limit warnings all land here.
mcp_log() {
  local log="$1"; local n="${2:-50}"
  [ -z "$log" ] && { echo "usage: mcp_log <log-path> [n]" >&2; return 1; }
  tail -n "$n" "$log"
}

# Usage: mcp_stop <pid> [server-log-path] [port]
# Kills the background server and the `bun run` child that actually holds the
# port (SIGKILL is not forwarded, so the child must be signalled directly or it
# survives as an orphaned listener). Pass the port from mcp_start to have the
# stop confirmed against the socket rather than against the wrapper PID.
# Removes the server log if a path is given.
mcp_stop() {
  local pid="$1"; local log="${2:-}"; local port="${3:-}"
  [ -z "$pid" ] && { echo "usage: mcp_stop <pid> [log-path] [port]" >&2; return 1; }
  local kids; kids=$(pgrep -P "$pid" 2>/dev/null)
  kill "$pid" $kids 2>/dev/null
  for _ in $(seq 1 12); do
    kill -0 "$pid" 2>/dev/null || break
    sleep 0.25
  done
  if kill -0 "$pid" 2>/dev/null; then
    echo "PID $pid didn't exit on SIGTERM — sending SIGKILL"
    kill -9 "$pid" $kids 2>/dev/null
    sleep 0.5
  fi
  local held=""
  [ -n "$port" ] && held=$(lsof -ti tcp:"$port" 2>/dev/null | tr '\n' ' ')
  if [ -n "$held" ]; then
    echo "WARNING: port $port still held by PID(s) $held after stopping $pid — kill those before re-running"
  elif kill -0 "$pid" 2>/dev/null; then
    echo "WARNING: PID $pid still alive after SIGKILL"
  else
    echo "stopped pid=$pid${port:+ (port $port free)}"
  fi
  [ -n "$log" ] && rm -f "$log"
  return 0
}
HELPER_EOF

. /tmp/<project-name>-field-test-9DJ73-K103L.sh
mcp_start /absolute/path/to/server   # replace with the target server

. /tmp/<project-name>-field-test-<ID>.sh
mcp_init <url-from-mcp_start>

mcp_call <url> '' tools/list '' <protocol-from-mcp_init>

. /tmp/<project-name>-field-test-<ID>.sh
mcp_call <url> <sid> tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
mcp_call <url> <sid> resources/list | jq '.result.resources[] | {uri, name, mimeType}'
mcp_call <url> <sid> prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
mcp_catalog_size <url> <sid> <protocol>