@tmcp/transport-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paolo Ricciuti
+
+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,136 @@
+# @tmcp/transport-cli
+
+A CLI transport for TMCP that turns your MCP server's tools into command-line commands. Each registered tool becomes a subcommand with flags derived from its JSON Schema input, powered by [yargs](https://yargs.js.org/).
+
+## Installation
+
+```bash
+pnpm add @tmcp/transport-cli tmcp
+```
+
+## Usage
+
+```javascript
+import { McpServer } from 'tmcp';
+import { CliTransport } from '@tmcp/transport-cli';
+import { ZodJsonSchemaAdapter } from '@tmcp/adapter-zod';
+import { z } from 'zod';
+
+const server = new McpServer(
+	{
+		name: 'my-cli',
+		version: '1.0.0',
+		description: 'My CLI tool',
+	},
+	{
+		adapter: new ZodJsonSchemaAdapter(),
+		capabilities: { tools: {} },
+	},
+);
+
+server.tool(
+	{
+		name: 'greet',
+		description: 'Greet someone by name',
+		schema: z.object({
+			name: z.string().describe('Name of the person to greet'),
+			loud: z.boolean().optional().describe('Shout the greeting'),
+		}),
+	},
+	async (input) => {
+		const text = `Hello, ${input.name}!`;
+		return {
+			content: [
+				{ type: 'text', text: input.loud ? text.toUpperCase() : text },
+			],
+		};
+	},
+);
+
+const cli = new CliTransport(server);
+await cli.run(undefined, process.argv.slice(2));
+```
+
+Running the above:
+
+```bash
+node my-cli.js greet --name Alice
+# {"content":[{"type":"text","text":"Hello, Alice!"}]}
+
+node my-cli.js greet --name Alice --loud
+# {"content":[{"type":"text","text":"HELLO, ALICE!"}]}
+```
+
+Output is pretty-printed JSON written to stdout. Errors go to stderr and set `process.exitCode` to 1.
+
+The help output uses the server's `name` (from the `McpServer` config) as the CLI program name. In the example above, `--help` would show `my-cli` as the command name.
+
+## Argument types
+
+The transport maps JSON Schema types from your tool's input schema to yargs option types:
+
+| JSON Schema type | yargs type | Example                      |
+| ---------------- | ---------- | ---------------------------- |
+| `string`         | `string`   | `--name Alice`               |
+| `number`         | `number`   | `--count 5`                  |
+| `integer`        | `number`   | `--port 8080`                |
+| `boolean`        | `boolean`  | `--verbose` / `--no-verbose` |
+| `array`          | `array`    | `--items foo --items bar`    |
+
+Properties marked as required in the schema are enforced by yargs (`demandOption`). Optional properties can be omitted. Enum values (e.g. from `z.enum()` or `v.picklist()`) are passed through as `choices`.
+
+## Custom context
+
+If your server uses custom context, you can pass it as the first argument to `run()`:
+
+```javascript
+const cli = new CliTransport(server);
+await cli.run({ userId: 'cli-user' }, process.argv.slice(2));
+```
+
+The context is forwarded to the server on every request, so your tool handlers can read it from `server.ctx.custom`.
+
+## API
+
+### `CliTransport`
+
+#### Constructor
+
+```typescript
+new CliTransport(server: McpServer)
+```
+
+Creates a new CLI transport. The `server` parameter is the TMCP server instance whose tools will be exposed as commands.
+
+#### Methods
+
+##### `run(ctx?: TCustom, argv?: string[]): Promise<void>`
+
+Initializes an MCP session, fetches the tool list from the server, builds yargs commands from the tool definitions, and parses the given argv (or `process.argv.slice(2)` if omitted).
+
+- `ctx` - Optional custom context passed to the server for this invocation.
+- `argv` - Optional array of CLI arguments. Defaults to `process.argv.slice(2)`.
+
+## How it works
+
+1. The transport sends an `initialize` JSON-RPC request to the server to start a session.
+2. It calls `tools/list` to get all registered tools and their input schemas.
+3. For each tool, it registers a yargs command using the tool name and converts the tool's `inputSchema` properties into yargs options.
+4. When the user invokes a command, the parsed arguments are coerced back to their schema types and sent as a `tools/call` request.
+5. The result is written to stdout as pretty-printed JSON.
+
+## Related Packages
+
+- [`tmcp`](../tmcp) - Core TMCP server implementation
+- [`@tmcp/transport-stdio`](../transport-stdio) - Standard I/O transport
+- [`@tmcp/transport-http`](../transport-http) - HTTP transport
+- [`@tmcp/adapter-zod`](../adapter-zod) - Zod schema adapter
+- [`@tmcp/adapter-valibot`](../adapter-valibot) - Valibot schema adapter
+
+## Acknowledgments
+
+Huge thanks to Sean O'Bannon that provided us with the `@tmcp` scope on npm.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tmcp/transport-cli",
+  "version": "0.0.1",
+  "description": "CLI transport for TMCP - exposes MCP tools as CLI commands via yargs",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/types/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "tmcp": "^1.16.3"
+  },
+  "dependencies": {
+    "yargs": "^17.7.2"
+  },
+  "keywords": [
+    "tmcp",
+    "cli",
+    "transport",
+    "yargs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paoloricciuti/tmcp.git",
+    "directory": "packages/transport-cli"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "@types/yargs": "^17.0.33",
+    "dts-buddy": "^0.6.2",
+    "publint": "^0.3.12",
+    "valibot": "^1.1.0",
+    "vitest": "^4.0.6",
+    "@tmcp/adapter-valibot": "^0.1.5",
+    "tmcp": "^1.19.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate:types": "dts-buddy && publint",
+    "prepublish": "pnpm generate:types",
+    "test": "vitest"
+  }
+}

package/src/index.js

@@ -0,0 +1,277 @@
+/**
+ * @import { McpServer } from "tmcp";
+ * @import { Options } from "yargs";
+ * @import { InputSchema, Tool } from "./internal.js";
+ */
+import process from 'node:process';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import Yargs from 'yargs/yargs';
+
+/**
+ * Maps a JSON Schema type string to a yargs option type.
+ * @param {string | undefined} json_schema_type
+ * @returns {Options["type"]}
+ */
+function json_schema_type_to_yargs(json_schema_type) {
+	switch (json_schema_type) {
+		case 'string':
+			return 'string';
+		case 'number':
+		case 'integer':
+			return 'number';
+		case 'boolean':
+			return 'boolean';
+		case 'array':
+			return 'array';
+		default:
+			return 'string';
+	}
+}
+
+/**
+ * Converts a JSON Schema inputSchema into a yargs options object.
+ * @param {InputSchema} input_schema
+ * @returns {Record<string, Options>}
+ */
+function json_schema_to_yargs_options(input_schema) {
+	/** @type {Record<string, Options>} */
+	const options = {};
+
+	const properties = input_schema.properties ?? {};
+	const required = new Set(input_schema.required ?? []);
+
+	for (const [name, schema] of Object.entries(properties)) {
+		/** @type {Options} */
+		const option = {};
+
+		option.type = json_schema_type_to_yargs(schema.type);
+		option.demandOption = required.has(name);
+
+		if (schema.description) {
+			option.describe = schema.description;
+		}
+
+		if (schema.enum) {
+			option.choices =
+				/** @type {Array<string | number | true | undefined>} */ (
+					schema.enum
+				);
+		}
+
+		if (schema.default !== undefined) {
+			option.default = schema.default;
+		}
+
+		options[name] = option;
+	}
+
+	return options;
+}
+
+/**
+ * Coerces parsed yargs arguments back to their JSON Schema types.
+ * Yargs parses everything from argv as strings by default for some types,
+ * so we need to coerce values based on the schema.
+ * @param {Record<string, unknown>} args
+ * @param {InputSchema} input_schema
+ * @returns {Record<string, unknown>}
+ */
+function coerce_args(args, input_schema) {
+	/** @type {Record<string, unknown>} */
+	const result = {};
+	const properties = input_schema.properties ?? {};
+
+	for (const [key, schema] of Object.entries(properties)) {
+		const value = args[key];
+
+		if (value === undefined) continue;
+
+		if (schema?.type === 'integer' && typeof value === 'string') {
+			result[key] = parseInt(value, 10);
+		} else if (schema?.type === 'number' && typeof value === 'string') {
+			result[key] = parseFloat(value);
+		} else if (schema?.type === 'object' && typeof value === 'string') {
+			try {
+				result[key] = JSON.parse(value);
+			} catch {
+				result[key] = value;
+			}
+		} else {
+			result[key] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * @template {Record<string, unknown> | undefined} [TCustom=undefined]
+ */
+export class CliTransport {
+	/**
+	 * @type {McpServer<any, TCustom>}
+	 */
+	#server;
+
+	/**
+	 * @type {AsyncLocalStorage<string | undefined>}
+	 */
+	#session_id_storage = new AsyncLocalStorage();
+
+	/**
+	 * @type {number}
+	 */
+	#request_id = 0;
+
+	/**
+	 * @type {string}
+	 */
+	#session_id = crypto.randomUUID();
+
+	/**
+	 * @param {McpServer<any, TCustom>} server
+	 */
+	constructor(server) {
+		this.#server = server;
+	}
+
+	/**
+	 * Sends a JSON-RPC request to the server and returns the result.
+	 * @param {string} method
+	 * @param {Record<string, unknown>} [params]
+	 * @param {TCustom} [ctx]
+	 * @returns {Promise<any>}
+	 */
+	async #request(method, params, ctx) {
+		const request_id = this.#request_id++;
+
+		const response = await this.#session_id_storage.run(
+			this.#session_id,
+			() =>
+				this.#server.receive(
+					{
+						jsonrpc: '2.0',
+						id: request_id,
+						method,
+						...(params ? { params } : {}),
+					},
+					{
+						sessionId: this.#session_id,
+						custom: ctx,
+					},
+				),
+		);
+
+		if (response?.error) {
+			throw new Error(response.error.message ?? 'Unknown JSON-RPC error');
+		}
+
+		return response?.result;
+	}
+
+	/**
+	 * Initialize the MCP session with the server.
+	 * @param {TCustom} [ctx]
+	 * @returns {Promise<{ serverInfo?: { name?: string } }>}
+	 */
+	async #initialize(ctx) {
+		return this.#request(
+			'initialize',
+			{
+				protocolVersion: '2025-03-26',
+				capabilities: {},
+				clientInfo: {
+					name: 'tmcp-cli',
+					version: '0.0.1',
+				},
+			},
+			ctx,
+		);
+	}
+
+	/**
+	 * Fetches the list of tools from the server.
+	 * @param {TCustom} [ctx]
+	 * @returns {Promise<Array<Tool>>}
+	 */
+	async #list_tools(ctx) {
+		const result = await this.#request('tools/list', undefined, ctx);
+		return result?.tools ?? [];
+	}
+
+	/**
+	 * Calls a tool by name with arguments.
+	 * @param {string} name
+	 * @param {Record<string, unknown>} [args]
+	 * @param {TCustom} [ctx]
+	 * @returns {Promise<any>}
+	 */
+	async #call_tool(name, args, ctx) {
+		return this.#request(
+			'tools/call',
+			{
+				name,
+				arguments: args ?? {},
+			},
+			ctx,
+		);
+	}
+
+	/**
+	 * Starts the CLI. Initializes the MCP session, lists tools,
+	 * builds yargs commands from the tool definitions, and parses argv.
+	 * @param {TCustom} [ctx]
+	 * @param {Array<string>} [argv]
+	 */
+	async run(ctx, argv) {
+		const init_result = await this.#initialize(ctx);
+
+		const tools = await this.#list_tools(ctx);
+
+		const script_name = init_result?.serverInfo?.name ?? 'tmcp';
+
+		const cli = Yargs(argv ?? process.argv.slice(2))
+			.scriptName(script_name)
+			.strict()
+			.demandCommand(
+				1,
+				'You need to specify a tool command to run. Use --help to see available tools.',
+			)
+			.help();
+
+		for (const tool of tools) {
+			const options = json_schema_to_yargs_options(tool.inputSchema);
+
+			cli.command(
+				tool.name,
+				tool.description ?? '',
+				(yargs) => yargs.options(options),
+				async (args) => {
+					try {
+						const coerced = coerce_args(
+							/** @type {Record<string, unknown>} */ (args),
+							tool.inputSchema,
+						);
+
+						const result = await this.#call_tool(
+							tool.name,
+							coerced,
+							ctx,
+						);
+
+						process.stdout.write(
+							JSON.stringify(result, null, 2) + '\n',
+						);
+					} catch (err) {
+						process.stderr.write(
+							`Error: ${err instanceof Error ? err.message : String(err)}\n`,
+						);
+						process.exitCode = 1;
+					}
+				},
+			);
+		}
+
+		await cli.parseAsync();
+	}
+}

package/src/internal.d.ts

@@ -0,0 +1,20 @@
+export type InputSchema = {
+	type: 'object';
+	properties?: Record<
+		string,
+		{
+			type?: string;
+			description?: string;
+			enum?: Array<unknown>;
+			default?: unknown;
+			items?: { type?: string };
+		}
+	>;
+	required?: Array<string>;
+};
+
+export type Tool = {
+	name: string;
+	description?: string;
+	inputSchema: InputSchema;
+};

package/src/test.js

@@ -0,0 +1,5 @@
+import Yargs from 'yargs/yargs';
+
+await Yargs(process.argv.slice(2))
+	.command('test', 'Run tests', {}, console.log)
+	.parseAsync();

package/src/types/index.d.ts

@@ -0,0 +1,18 @@
+declare module '@tmcp/transport-cli' {
+	import type { McpServer } from 'tmcp';
+	export class CliTransport<TCustom extends Record<string, unknown> | undefined = undefined> {
+		
+		constructor(server: McpServer<any, TCustom>);
+		/**
+		 * Starts the CLI. Initializes the MCP session, lists tools,
+		 * builds yargs commands from the tool definitions, and parses argv.
+		 * 
+		 */
+		run(ctx?: TCustom, argv?: Array<string>): Promise<void>;
+		#private;
+	}
+
+	export {};
+}
+
+//# sourceMappingURL=index.d.ts.map

package/src/types/index.d.ts.map

@@ -0,0 +1,15 @@
+{
+	"version": 3,
+	"file": "index.d.ts",
+	"names": [
+		"CliTransport"
+	],
+	"sources": [
+		"../index.js"
+	],
+	"sourcesContent": [
+		null
+	],
+	"mappings": ";;cA6GaA,YAAYA",
+	"ignoreList": []
+}