@alvin0/ai-agent-sdk-mcp-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @alvin0/ai-agent-sdk-mcp-node
+
+Runtime: **Node 22.12+**.
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-mcp @alvin0/ai-agent-sdk-mcp-node
+```
+
+Node-only MCP stdio client transport. Universal remote HTTP clients remain in
+`@alvin0/ai-agent-sdk-mcp`; server hosting is selected separately through
+`@alvin0/ai-agent-sdk-mcp-server` or `@alvin0/ai-agent-sdk-mcp-node-server`.
+
+```ts
+import { createAgentRuntime } from '@alvin0/ai-agent-sdk-core'
+import { connectMcpStdio } from '@alvin0/ai-agent-sdk-mcp-node'
+
+const runtime = await createAgentRuntime({ providers: [modelProvider] })
+let connection: Awaited<ReturnType<typeof connectMcpStdio>> | undefined
+try {
+  connection = await connectMcpStdio({
+    serverName: 'local-tools',
+    command: process.execPath,
+    args: ['path/to/server.js'],
+    logger: runtime.logger({ fields: { integration: 'mcp-stdio' } }),
+  })
+  const agent = runtime.agent({ model, toolSources: [connection] })
+  await agent.generate('Use the local tools when needed.')
+} finally {
+  try {
+    await runtime.close()
+  } finally {
+    await connection?.closeWithReport()
+  }
+}
+```
+
+Composition: `runtime-agent.toolSources`. Lifecycle: `connected-caller-owned`;
+create the runtime first, pass `runtime.logger(...)`, close the runtime before
+the borrowed connection, and inspect `closeWithReport()`.

package/dist/index.d.mts

@@ -0,0 +1,13 @@
+import { StdioServerParameters } from "@modelcontextprotocol/client/stdio";
+import { McpClientConnection, McpClientLifecycleOptions, McpCloseReport, McpConnectionError } from "@alvin0/ai-agent-sdk-mcp/client";
+//#region src/index.d.ts
+/** Stdio-specialized alias retained so normal Node recipes name their transport. */
+interface McpStdioConnection extends McpClientConnection {}
+interface McpStdioClientOptions extends McpClientLifecycleOptions, StdioServerParameters {}
+/** Construct a supervised stdio client without spawning the child yet. */
+declare function createMcpStdioClient(options: McpStdioClientOptions): McpStdioConnection;
+/** Spawn, negotiate, discover tools, and return a ready stdio client. */
+declare function connectMcpStdio(options: McpStdioClientOptions): Promise<McpStdioConnection>;
+//#endregion
+export { type McpCloseReport, McpConnectionError, McpStdioClientOptions, McpStdioConnection, connectMcpStdio, createMcpStdioClient };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;UAaiB,2BAA2B;UAE3B,8BAA8B,2BAA2B;;iBAG1D,qBAAqB,SAAS,wBAAwB;;iBAiBhD,gBAAgB,SAAS,wBAAwB,QAAQ"}

package/dist/index.mjs

@@ -0,0 +1,48 @@
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { McpClientConnection, McpConnectionError, McpConnectionError as McpConnectionError$1 } from "@alvin0/ai-agent-sdk-mcp/client";
+
+//#region src/index.ts
+/** Node-only MCP stdio client transport. */
+/** Construct a supervised stdio client without spawning the child yet. */
+function createMcpStdioClient(options) {
+	const { command, args, env, stderr, cwd, maxBufferSize, ...lifecycle } = options;
+	if (command.trim().length === 0) throw new TypeError("MCP stdio command must not be empty");
+	return new McpClientConnection(lifecycle, () => new StdioClientTransport({
+		command,
+		...args === void 0 ? {} : { args: [...args] },
+		...env === void 0 ? {} : { env: { ...env } },
+		...stderr === void 0 ? {} : { stderr },
+		...cwd === void 0 ? {} : { cwd },
+		...maxBufferSize === void 0 ? {} : { maxBufferSize }
+	}), { integrationFamily: "mcp-stdio-client" });
+}
+/** Spawn, negotiate, discover tools, and return a ready stdio client. */
+async function connectMcpStdio(options) {
+	const connection = createMcpStdioClient(options);
+	try {
+		await connection.connect();
+		return connection;
+	} catch (error) {
+		const cleanup = await connection.closeWithReport();
+		throw new McpConnectionError$1(connection.state.status === "connecting" ? "handshake" : "unknown", {
+			code: "MCP_CONNECT_FAILED",
+			stage: "stdio-connect",
+			message: "MCP stdio connection startup failed",
+			usageCoverage: {
+				logicalCalls: 0,
+				attempts: 0,
+				complete: 0,
+				partial: 0,
+				estimated: 0,
+				missing: 0,
+				notApplicable: 0,
+				possiblyBilledAttemptsWithoutUsage: 0
+			},
+			possiblyBilledAttemptsWithoutUsage: 0
+		}, cleanup, error);
+	}
+}
+
+//#endregion
+export { McpConnectionError, connectMcpStdio, createMcpStdioClient };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["McpConnectionError"],"sources":["../src/index.ts"],"sourcesContent":["/** Node-only MCP stdio client transport. */\n\nimport { StdioClientTransport, type StdioServerParameters } from '@modelcontextprotocol/client/stdio'\nimport {\n  McpConnectionError,\n  McpClientConnection,\n  type McpClientLifecycleOptions,\n} from '@alvin0/ai-agent-sdk-mcp/client'\n\nexport { McpConnectionError } from '@alvin0/ai-agent-sdk-mcp/client'\nexport type { McpCloseReport } from '@alvin0/ai-agent-sdk-mcp/client'\n\n/** Stdio-specialized alias retained so normal Node recipes name their transport. */\nexport interface McpStdioConnection extends McpClientConnection {}\n\nexport interface McpStdioClientOptions extends McpClientLifecycleOptions, StdioServerParameters {}\n\n/** Construct a supervised stdio client without spawning the child yet. */\nexport function createMcpStdioClient(options: McpStdioClientOptions): McpStdioConnection {\n  const {\n    command, args, env, stderr, cwd, maxBufferSize,\n    ...lifecycle\n  } = options\n  if (command.trim().length === 0) throw new TypeError('MCP stdio command must not be empty')\n  return new McpClientConnection(lifecycle, () => new StdioClientTransport({\n    command,\n    ...(args === undefined ? {} : { args: [...args] }),\n    ...(env === undefined ? {} : { env: { ...env } }),\n    ...(stderr === undefined ? {} : { stderr }),\n    ...(cwd === undefined ? {} : { cwd }),\n    ...(maxBufferSize === undefined ? {} : { maxBufferSize }),\n  }), { integrationFamily: 'mcp-stdio-client' })\n}\n\n/** Spawn, negotiate, discover tools, and return a ready stdio client. */\nexport async function connectMcpStdio(options: McpStdioClientOptions): Promise<McpStdioConnection> {\n  const connection = createMcpStdioClient(options)\n  try {\n    await connection.connect()\n    return connection\n  } catch (error: unknown) {\n    const cleanup = await connection.closeWithReport()\n    throw new McpConnectionError(\n      connection.state.status === 'connecting' ? 'handshake' : 'unknown',\n      {\n        code: 'MCP_CONNECT_FAILED', stage: 'stdio-connect', message: 'MCP stdio connection startup failed',\n        usageCoverage: { logicalCalls: 0, attempts: 0, complete: 0, partial: 0, estimated: 0,\n          missing: 0, notApplicable: 0, possiblyBilledAttemptsWithoutUsage: 0 },\n        possiblyBilledAttemptsWithoutUsage: 0,\n      },\n      cleanup,\n      error,\n    )\n  }\n}\n"],"mappings":";;;;;;AAkBA,SAAgB,qBAAqB,SAAoD;CACvF,MAAM,EACJ,SAAS,MAAM,KAAK,QAAQ,KAAK,eACjC,GAAG,cACD;CACJ,IAAI,QAAQ,KAAK,CAAC,CAAC,WAAW,GAAG,MAAM,IAAI,UAAU,qCAAqC;CAC1F,OAAO,IAAI,oBAAoB,iBAAiB,IAAI,qBAAqB;EACvE;EACA,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE;EAChD,GAAI,QAAQ,SAAY,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE;EAC/C,GAAI,WAAW,SAAY,CAAC,IAAI,EAAE,OAAO;EACzC,GAAI,QAAQ,SAAY,CAAC,IAAI,EAAE,IAAI;EACnC,GAAI,kBAAkB,SAAY,CAAC,IAAI,EAAE,cAAc;CACzD,CAAC,GAAG,EAAE,mBAAmB,mBAAmB,CAAC;AAC/C;;AAGA,eAAsB,gBAAgB,SAA6D;CACjG,MAAM,aAAa,qBAAqB,OAAO;CAC/C,IAAI;EACF,MAAM,WAAW,QAAQ;EACzB,OAAO;CACT,SAAS,OAAgB;EACvB,MAAM,UAAU,MAAM,WAAW,gBAAgB;EACjD,MAAM,IAAIA,qBACR,WAAW,MAAM,WAAW,eAAe,cAAc,WACzD;GACE,MAAM;GAAsB,OAAO;GAAiB,SAAS;GAC7D,eAAe;IAAE,cAAc;IAAG,UAAU;IAAG,UAAU;IAAG,SAAS;IAAG,WAAW;IACjF,SAAS;IAAG,eAAe;IAAG,oCAAoC;GAAE;GACtE,oCAAoC;EACtC,GACA,SACA,KACF;CACF;AACF"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@alvin0/ai-agent-sdk-mcp-node",
+  "author": {
+    "name": "alvin0 - chaulamdinhai",
+    "email": "chaulamdinhai@gmail.com"
+  },
+  "version": "0.1.0",
+  "description": "Node stdio MCP client transport for ai-agent-sdk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alvin0/ai-agent-sdk.git",
+    "directory": "packages/mcp-node"
+  },
+  "homepage": "https://github.com/alvin0/ai-agent-sdk/tree/main/packages/mcp-node#readme",
+  "bugs": {
+    "url": "https://github.com/alvin0/ai-agent-sdk/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@alvin0/ai-agent-sdk-mcp": "^0.1.0",
+    "@modelcontextprotocol/client": "2.0.0"
+  },
+  "peerDependencies": {
+    "@alvin0/ai-agent-sdk-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@alvin0/ai-agent-sdk-core": "^0.1.0",
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "26.4.0",
+    "publint": "0.3.24",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "aiAgentSdk": {
+    "runtime": "node",
+    "coreApi": 1,
+    "roles": [
+      "mcp-client-transport"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "node -e \"for(const p of ['dist','artifacts'])require('node:fs').rmSync(p,{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "pack": "pnpm pack --pack-destination artifacts",
+    "test:pack": "node ../../scripts/test-packed-node-capability.mts mcp-node",
+    "check:publint": "publint",
+    "check:types": "attw --profile esm-only --pack ."
+  }
+}