toolnexus 0.26.0 → 0.27.0

package/src/mcp2026/stdio.ts

@@ -4,10 +4,12 @@
  * pending call instead of hanging. No headers, no auth.
  */
 import { spawn, type ChildProcess } from "node:child_process"
-import { createInterface } from "node:readline"
 import type { Readable } from "node:stream"
 import type { Transport } from "./client.js"
 import type { Obj } from "./protocol.js"
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js"
+import { ReadBuffer, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js"
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js"
 
 /** The child exited / closed stdout before answering. */
 export class StdioClosedError extends Error {}
@@ -18,33 +20,89 @@ export class StdioTransport implements Transport {
   private done: Promise<void>
   private child: ChildProcess
 
+  private buf: Buffer = Buffer.alloc(0)
+  private onData: (chunk: Buffer) => void
+  private onEnd: () => void
+  private detached = false
+  private hold = false
+  private held = false
+
   constructor(child: ChildProcess) {
     this.child = child
-    const rl = createInterface({ input: child.stdout as Readable, crlfDelay: Infinity })
-    rl.on("line", (line) => {
-      let m: any
-      try {
-        m = JSON.parse(line)
-      } catch {
-        return // noise
-      }
-      if (!m || typeof m !== "object" || m.method !== undefined || m.id === undefined || m.id === null) return // not a response
-      const key = JSON.stringify(m.id)
-      const f = this.pending.get(key)
-      this.pending.delete(key)
-      f?.(m)
-    })
-    this.done = new Promise((r) =>
-      rl.once("close", () => {
-        this.err ??= new StdioClosedError("stdio server closed its stdout")
-        for (const f of this.pending.values()) f({ __closed: true })
-        this.pending.clear()
-        r()
-      }),
-    )
+    // Line-exact own reader (no readline): detach() can stop it and hand over unread bytes.
+    let closed!: () => void
+    this.done = new Promise<void>((r) => (closed = r))
+    this.onData = (chunk: Buffer) => {
+      this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk
+      this.drain()
+    }
+    this.onEnd = () => {
+      this.err ??= new StdioClosedError("stdio server closed its stdout")
+      for (const f of this.pending.values()) f({ __closed: true })
+      this.pending.clear()
+      closed()
+    }
+    const out = child.stdout as Readable
+    out.on("data", this.onData)
+    out.once("end", this.onEnd)
+    out.once("close", this.onEnd)
     child.stdin?.on("error", () => {}) // EPIPE after the server died surfaces as a closed stdout
   }
 
+  private drain(): void {
+    let nl: number
+    while (!this.detached && !this.held && (nl = this.buf.indexOf(10)) >= 0) {
+      const line = this.buf.subarray(0, nl).toString("utf8").replace(/\r$/, "")
+      this.buf = this.buf.subarray(nl + 1)
+      this.onLine(line)
+    }
+  }
+
+  /** Probe mode: after the next delivered response, stop parsing (bytes stay buffered for detach). */
+  holdAfterNextResponse(): void {
+    this.hold = true
+  }
+
+  /** Leave probe mode and parse whatever was held. */
+  release(): void {
+    this.hold = false
+    this.held = false
+    this.drain()
+  }
+
+  private onLine(line: string): void {
+    let m: any
+    try {
+      m = JSON.parse(line)
+    } catch {
+      return // noise
+    }
+    if (!m || typeof m !== "object" || m.method !== undefined || m.id === undefined || m.id === null) return // not a response
+    const key = JSON.stringify(m.id)
+    const f = this.pending.get(key)
+    this.pending.delete(key)
+    if (f && this.hold) this.held = true
+    f?.(m)
+  }
+
+  /**
+   * §2.2a handoff: stop reading stdout (listeners removed, stream paused — no read left pending)
+   * and give the live child plus any bytes already read past the last delivered line to the
+   * frozen path. The transport is unusable afterwards; the child is NOT killed.
+   */
+  detach(): { child: ChildProcess; leftover: Buffer } {
+    this.detached = true
+    const out = this.child.stdout as Readable
+    out.off("data", this.onData)
+    out.off("end", this.onEnd)
+    out.off("close", this.onEnd)
+    out.pause()
+    this.err ??= new StdioClosedError("stdio transport detached")
+    const leftover = this.buf
+    this.buf = Buffer.alloc(0)
+    return { child: this.child, leftover }
+  }
+
   /** Writes one line and waits for the response with the same id. Never retried. */
   roundTrip(id: number, body: string, timeoutMs: number, signal?: AbortSignal): Promise<Obj> {
     if (this.err) return Promise.reject(this.err)
@@ -100,3 +158,70 @@ export function spawnStdio(argv: string[], env: NodeJS.ProcessEnv, cwd?: string)
     child.once("spawn", () => resolve(new StdioTransport(child)))
   })
 }
+
+/**
+ * §2.2a: the frozen SDK path over a child the probe already started (StdioClientTransport always
+ * spawns). Takes the detached probe's stdin/stdout plus any bytes it had read but not parsed.
+ */
+export class AdoptedStdioTransport implements SdkTransport {
+  onclose?: () => void
+  onerror?: (error: Error) => void
+  onmessage?: (message: JSONRPCMessage) => void
+  private rb = new ReadBuffer()
+  private closed = false
+
+  constructor(private child: ChildProcess, private leftover: Buffer) {}
+
+  async start(): Promise<void> {
+    const out = this.child.stdout as Readable
+    out.on("data", (chunk: Buffer) => this.feed(chunk))
+    out.on("error", (e) => this.onerror?.(e))
+    this.child.stdin?.on("error", (e) => this.onerror?.(e))
+    this.child.once("close", () => this.finish())
+    if (this.leftover.length) this.feed(this.leftover)
+    this.leftover = Buffer.alloc(0)
+    out.resume()
+  }
+
+  private feed(chunk: Buffer): void {
+    this.rb.append(chunk)
+    for (;;) {
+      let m: JSONRPCMessage | null
+      try {
+        m = this.rb.readMessage()
+      } catch (e) {
+        this.onerror?.(e as Error)
+        continue
+      }
+      if (m === null) break
+      this.onmessage?.(m)
+    }
+  }
+
+  send(message: JSONRPCMessage): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.child.stdin?.write(serializeMessage(message))) this.child.stdin?.once("drain", resolve)
+      else resolve()
+    })
+  }
+
+  private finish(): void {
+    if (this.closed) return
+    this.closed = true
+    this.rb.clear()
+    this.onclose?.()
+  }
+
+  /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
+  async close(): Promise<void> {
+    if (this.child.exitCode === null && this.child.signalCode === null) {
+      const exited = new Promise<void>((r) => this.child.once("exit", () => r()))
+      this.child.stdin?.end()
+      const t = setTimeout(() => this.child.kill("SIGKILL"), 2000)
+      await exited
+      clearTimeout(t)
+    }
+    this.child.stdout?.destroy()
+    this.finish()
+  }
+}

package/src/mcphandler.ts

@@ -348,7 +348,7 @@ export function createMcpHandler(toolkitTools: () => Tool[], cfg: McpHandlerConf
   /** Validates protocol header + session (stateful). Writes the HTTP error itself on failure. */
   async function checkSession(ctx: McpContext, req: IncomingMessage, res: ServerResponse): Promise<boolean> {
     const v = header(req, "MCP-Protocol-Version")
-    if (v !== "" && !legacy.includes(v)) {
+    if (v !== "" && !versions.includes(v)) {
       httpError(res, 400, "Bad Request: unsupported MCP-Protocol-Version")
       return false
     }
@@ -775,8 +775,7 @@ export function createMcpHandler(toolkitTools: () => Tool[], cfg: McpHandlerConf
     if (only2026) return true
     if (method === "initialize") return false
     const hv = header(req, "MCP-Protocol-Version")
-    if (hv === MCP_PROTOCOL_2026) return true
-    if (hv !== "" && versions.includes(hv)) return false
+    if (hv !== "" && legacy.includes(hv)) return false
     return method === "server/discover" || header(req, "Mcp-Method") !== "" || (meta !== undefined && META_VERSION in meta)
   }
 

package/src/mcpserve.ts

@@ -16,7 +16,6 @@ import http from "node:http"
 import type { AddressInfo } from "node:net"
 import { randomBytes, timingSafeEqual } from "node:crypto"
 import { Server } from "@modelcontextprotocol/sdk/server/index.js"
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
 import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js"
 import type { Tool, ToolSource, ToolResult } from "./types.js"
 import type { ContentPart } from "./content.js"
@@ -166,6 +165,8 @@ export interface LocalMcpServer {
  */
 export async function serveLocalMcp(tools: Tool[], cfg?: MCPServeConfig): Promise<LocalMcpServer> {
   const exposed = exposedMcpTools(tools, cfg)
+  // Loaded on first serve, not at import: the transport pulls in @hono/node-server.
+  const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js")
   const token = randomBytes(32).toString("hex")
   const want = Buffer.from("Bearer " + token)
   const server = http.createServer((req, res) => {

package/src/serve.ts

@@ -18,7 +18,8 @@ import http from "node:http"
 import fs from "node:fs"
 import path from "node:path"
 import { randomUUID } from "node:crypto"
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+// The SDK server transport (and the @hono/node-server it pulls in) is loaded only when an MCP
+// profile is actually served, so importing toolnexus does not pay for it.
 import { sanitize, type Tool } from "./types.js"
 import type { SkillInfo } from "./skill.js"
 import type { RunResult } from "./client.js"
@@ -213,6 +214,9 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
   const [host, portStr] = splitAddr(opts.addr)
   const store = a2a ? resolveStore(a2a.store) : undefined
   const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : []
+  const StreamableHTTPServerTransport = mcp
+    ? (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport
+    : undefined
 
   const server = http.createServer((req, res) => {
     const rpcRes = (id: unknown, payload: object) => {
@@ -244,7 +248,7 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
         const body = req.method === "POST" ? await readBody(req) : ""
         const parsed = body ? safeJson(body) : undefined
         const mcpServer = buildMcpServer(exposedTools, mcp, onCall)
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+        const transport = new StreamableHTTPServerTransport!({ sessionIdGenerator: undefined })
         res.on("close", () => {
           void transport.close()
           void mcpServer.close()

package/src/skill.ts

@@ -12,10 +12,19 @@
 import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs"
 import path from "node:path"
 import { pathToFileURL } from "node:url"
-import { parse as parseYaml } from "yaml"
+import { createRequire } from "node:module"
 import { compareCodePoints, compareDiscovery, sortEntriesByName } from "./order.js"
 import type { Tool, ToolResult } from "./types.js"
 
+// yaml is required on the first frontmatter parse, not at import, so a host with no skills never
+// loads it. `require` keeps the parse synchronous (listSkills/loadSkills are sync); yaml's Node
+// entry is CommonJS, so this is the same module instance an `import` would get.
+let yamlParse: ((src: string) => unknown) | undefined
+function parseYaml(src: string): unknown {
+  yamlParse ??= (createRequire(import.meta.url)("yaml") as typeof import("yaml")).parse
+  return yamlParse(src)
+}
+
 export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
 
 Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
@@ -68,10 +77,25 @@ export interface SkillSkip {
   detail?: string
 }
 
+/** Why a KEPT skill carries a warning (SPEC.md §3, #84). The skill still loads unchanged. */
+export type SkillWarningReason = "oversized-description"
+
+/** Maximum skill `description` length, in Unicode code points, before a warning (SPEC.md §3). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 1024
+
+export interface SkillWarning {
+  location: string
+  reason: SkillWarningReason
+  /** Description length in Unicode CODE POINTS (not bytes, not UTF-16 units). */
+  chars: number
+}
+
 /** Result of a list-only validate pass (SPEC.md §3, S3). */
 export interface SkillInventory {
   skills: SkillInfo[]
   skipped: SkillSkip[]
+  /** Kept skills that load but carry a warning (oversized description), in discovery order. */
+  warnings: SkillWarning[]
 }
 
 /** Options for loadSkills / listSkills (SPEC.md §3, S1/S2/S5). */
@@ -353,6 +377,26 @@ function collectCandidates(opts: LoadSkillsOptions): RawCandidate[] {
   return cands
 }
 
+/**
+ * Warn — never modify — skills whose description exceeds SKILL_DESCRIPTION_MAX_CHARS code
+ * points (SPEC.md §3, #84). Each warning is also sent to the same channel as the
+ * duplicate-name warning. Order follows the given skills (discovery order).
+ */
+function describeWarnings(skills: SkillInfo[]): SkillWarning[] {
+  const out: SkillWarning[] = []
+  for (const s of skills) {
+    if (s.description === undefined) continue
+    const chars = [...s.description].length
+    if (chars > SKILL_DESCRIPTION_MAX_CHARS) {
+      console.warn(
+        `[toolnexus] skill "${s.name}" (${s.location}) description is ${chars} chars, over ${SKILL_DESCRIPTION_MAX_CHARS} — kept unmodified`,
+      )
+      out.push({ location: s.location, reason: "oversized-description", chars })
+    }
+  }
+  return out
+}
+
 /** Dedupe candidates by name (first-wins); later duplicates become skips. */
 function mergeCandidates(cands: RawCandidate[]): { skills: Record<string, SkillInfo>; skipped: SkillSkip[] } {
   const skills: Record<string, SkillInfo> = {}
@@ -409,6 +453,8 @@ export interface SkillSource {
    * that stops being reported is indistinguishable from something that was finished.
    */
   skipped: SkillSkip[]
+  /** Exposed (post-allowlist) skills whose description is oversized; never modified (#84). */
+  warnings: SkillWarning[]
 }
 
 /**
@@ -420,7 +466,8 @@ export function listSkills(input: string | string[] | LoadSkillsOptions): SkillI
   const opts: LoadSkillsOptions =
     typeof input === "string" || Array.isArray(input) ? { dirs: input } : input
   const merged = mergeCandidates(collectCandidates(opts))
-  return { skills: Object.values(merged.skills), skipped: merged.skipped }
+  const list = Object.values(merged.skills)
+  return { skills: list, skipped: merged.skipped, warnings: describeWarnings(list) }
 }
 
 /** Discover skills (dirs and/or data) and build the `skill` loader tool. */
@@ -432,6 +479,7 @@ export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillS
   const skills = applySkillsFilter(merged.skills, opts.filter)
 
   const skipped = merged.skipped
+  const warnings = describeWarnings(Object.values(skills))
   const tool: Tool = {
     name: "skill",
     description: SKILL_TOOL_DESCRIPTION,
@@ -499,6 +547,7 @@ export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillS
     skills,
     tool,
     skipped,
+    warnings,
     prompt() {
       const described = Object.values(skills)
         .filter((s) => s.description !== undefined)