@tmcp/transport-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @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/).
+A CLI transport for TMCP that exposes your MCP tools as static, JSON-first commands. It is designed for agent-driven usage: tools are invoked with JSON input, schemas can be inspected directly, and output can be narrowed before it leaves stdout.
 
 ## Installation
 
@@ -33,16 +33,24 @@ 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'),
+			name: z.string(),
+			loud: z.boolean().optional(),
+		}),
+		outputSchema: z.object({
+			message: z.string(),
 		}),
 	},
 	async (input) => {
-		const text = `Hello, ${input.name}!`;
+		const message = `Hello, ${input.name}!`;
+
 		return {
 			content: [
-				{ type: 'text', text: input.loud ? text.toUpperCase() : text },
+				{
+					type: 'text',
+					text: input.loud ? message.toUpperCase() : message,
+				},
 			],
+			structuredContent: { message },
 		};
 	},
 );
@@ -51,44 +59,84 @@ const cli = new CliTransport(server);
 await cli.run(undefined, process.argv.slice(2));
 ```
 
-Running the above:
+## Commands
+
+### `tools`
+
+Prints the available tools as pretty JSON.
 
 ```bash
-node my-cli.js greet --name Alice
-# {"content":[{"type":"text","text":"Hello, Alice!"}]}
+node my-cli.js tools
+```
 
-node my-cli.js greet --name Alice --loud
-# {"content":[{"type":"text","text":"HELLO, ALICE!"}]}
+### `schema <tool>`
+
+Prints the tool metadata plus its input and output schemas.
+
+```bash
+node my-cli.js schema greet
 ```
 
-Output is pretty-printed JSON written to stdout. Errors go to stderr and set `process.exitCode` to 1.
+### `call <tool> [input]`
+
+Calls a tool with a JSON object. The first positional argument is the primary input source.
+
+```bash
+node my-cli.js call greet '{"name":"Alice"}'
+```
+
+### `<tool> [input]`
+
+Each tool name is also registered directly as an alias for `call <tool>`, unless the tool name would collide with a reserved command (`tools`, `schema`, or `call`).
+
+```bash
+node my-cli.js greet '{"name":"Alice","loud":true}'
+```
 
-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.
+## Input sources
 
-## Argument types
+Tool calls accept exactly one input source:
 
-The transport maps JSON Schema types from your tool's input schema to yargs option types:
+- Positional JSON: `greet '{"name":"Alice"}'`
 
-| 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`    |
+All inputs must parse to a JSON object. If no input is provided, the transport sends `{}`.
 
-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`.
+## Output controls
+
+Tool calls support two static output flags:
+
+- `--output full|structured|content|text`
+- `--fields path1,path2`
+
+Examples:
+
+```bash
+node my-cli.js greet '{"name":"Alice"}' --output text
+
+node my-cli.js get-user '{"id":"1"}' --output structured --fields user.name,user.email
+```
+
+`--fields` uses comma-separated dot paths and is applied after the output mode is selected. It is not available with `--output text`.
+
+## Behavior
+
+- Output is written to stdout.
+- JSON outputs are pretty-printed.
+- Errors are written to stderr and set `process.exitCode` to `1`.
+- Running the CLI without a command prints help output.
+- The CLI initializes an MCP session, sends `notifications/initialized`, and paginates through `tools/list` automatically.
+- The program name shown in help output comes from `McpServer`'s `name`.
 
 ## Custom context
 
-If your server uses custom context, you can pass it as the first argument to `run()`:
+If your server uses custom context, 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`.
+The context is forwarded on every request, so handlers can read it from `server.ctx.custom`.
 
 ## API
 
@@ -100,24 +148,13 @@ The context is forwarded to the server on every request, so your tool handlers c
 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
+```typescript
+run(ctx?: TCustom, argv?: string[]): Promise<void>
+```
 
-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.
+Starts the CLI, initializes a session, discovers tools, and executes the requested static command or tool alias.
 
 ## Related Packages
 

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@tmcp/transport-cli",
-  "version": "0.0.1",
-  "description": "CLI transport for TMCP - exposes MCP tools as CLI commands via yargs",
+  "version": "0.0.3",
+  "description": "CLI transport for TMCP with static JSON-first tool commands",
   "type": "module",
   "main": "src/index.js",
   "types": "src/types/index.d.ts",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "files": [
     "src"
   ],
@@ -19,13 +22,14 @@
     "tmcp": "^1.16.3"
   },
   "dependencies": {
-    "yargs": "^17.7.2"
+    "sade": "^1.8.1"
   },
   "keywords": [
     "tmcp",
     "cli",
     "transport",
-    "yargs"
+    "mcp",
+    "json"
   ],
   "repository": {
     "type": "git",
@@ -34,7 +38,6 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.13",
-    "@types/yargs": "^17.0.33",
     "dts-buddy": "^0.6.2",
     "publint": "^0.3.12",
     "valibot": "^1.1.0",

package/src/index.js

@@ -1,107 +1,340 @@
 /**
  * @import { McpServer } from "tmcp";
- * @import { Options } from "yargs";
- * @import { InputSchema, Tool } from "./internal.js";
+ * @import { ListToolsResult, Tool } from "./internal.js";
  */
 import process from 'node:process';
+import { randomUUID } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import Yargs from 'yargs/yargs';
+import sade from 'sade';
 
 /**
- * Maps a JSON Schema type string to a yargs option type.
- * @param {string | undefined} json_schema_type
- * @returns {Options["type"]}
+ * @typedef {'full' | 'structured' | 'content' | 'text'} OutputMode
  */
-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';
+
+/**
+ * @typedef {{ output?: OutputMode; fields?: string }} ToolOptions
+ */
+
+const CLIENT_INFO = {
+	name: 'tmcp-cli',
+	version: '0.0.1',
+};
+
+const RESERVED_COMMANDS = new Set(['call', 'schema', 'tools']);
+const UNSAFE_ALIAS_NAME = /[<>[\]\s]/;
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function is_record(value) {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} source
+ * @returns {Record<string, unknown>}
+ */
+function parse_input_json(value, source) {
+	let parsed;
+
+	try {
+		parsed = JSON.parse(String(value));
+	} catch {
+		throw new Error(`Invalid JSON in ${source}`);
+	}
+
+	if (!is_record(parsed)) {
+		throw new Error(`Input from ${source} must be a JSON object`);
 	}
+
+	return parsed;
 }
 
 /**
- * Converts a JSON Schema inputSchema into a yargs options object.
- * @param {InputSchema} input_schema
- * @returns {Record<string, Options>}
+ * @param {Array<unknown>} args
+ * @returns {{ positionals: Array<unknown>; options: Record<string, unknown> }}
  */
-function json_schema_to_yargs_options(input_schema) {
-	/** @type {Record<string, Options>} */
-	const options = {};
+function extract_command_args(args) {
+	const last_arg = args.at(-1);
+
+	if (is_record(last_arg)) {
+		return {
+			positionals: args.slice(0, -1),
+			options: last_arg,
+		};
+	}
 
-	const properties = input_schema.properties ?? {};
-	const required = new Set(input_schema.required ?? []);
+	return {
+		positionals: args,
+		options: {},
+	};
+}
+
+/**
+ * @param {Record<string, unknown>} options
+ * @returns {ToolOptions}
+ */
+function normalize_tool_options(options) {
+	return {
+		output:
+			typeof options.output === 'string'
+				? /** @type {OutputMode} */ (options.output)
+				: 'full',
+		fields: typeof options.fields === 'string' ? options.fields : undefined,
+	};
+}
+
+/**
+ * @param {string | undefined} input
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function resolve_tool_input(input) {
+	if (typeof input === 'string') {
+		return parse_input_json(input, 'positional input');
+	}
+
+	return {};
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function format_json(value) {
+	return `${JSON.stringify(value === undefined ? null : value, null, 2)}\n`;
+}
+
+/**
+ * @param {string | undefined} fields
+ * @returns {Array<string>}
+ */
+function parse_fields(fields) {
+	if (!fields) return [];
+
+	const paths = fields
+		.split(',')
+		.map((field) => field.trim())
+		.filter(Boolean);
+
+	if (paths.length === 0) {
+		throw new Error('`--fields` must include at least one dot path');
+	}
+
+	return paths;
+}
 
-	for (const [name, schema] of Object.entries(properties)) {
-		/** @type {Options} */
-		const option = {};
+/**
+ * @param {string} path
+ * @returns {Array<string>}
+ */
+function split_path(path) {
+	return path.split('.').filter(Boolean);
+}
 
-		option.type = json_schema_type_to_yargs(schema.type);
-		option.demandOption = required.has(name);
+/**
+ * @param {unknown} value
+ * @param {Array<string>} path
+ * @returns {unknown}
+ */
+function get_path_value(value, path) {
+	let current = value;
+
+	for (const segment of path) {
+		if (Array.isArray(current)) {
+			const index = Number(segment);
+			if (
+				!Number.isInteger(index) ||
+				index < 0 ||
+				index >= current.length
+			) {
+				throw new Error(`Unknown field path: ${path.join('.')}`);
+			}
+			current = current[index];
+			continue;
+		}
 
-		if (schema.description) {
-			option.describe = schema.description;
+		if (!is_record(current) || !(segment in current)) {
+			throw new Error(`Unknown field path: ${path.join('.')}`);
 		}
 
-		if (schema.enum) {
-			option.choices =
-				/** @type {Array<string | number | true | undefined>} */ (
-					schema.enum
+		current = current[segment];
+	}
+
+	return current;
+}
+
+/**
+ * @param {Record<string, unknown> | Array<unknown>} target
+ * @param {Array<string>} path
+ * @param {unknown} value
+ */
+function set_path_value(target, path, value) {
+	let current = target;
+
+	for (let index = 0; index < path.length; index += 1) {
+		const segment = path[index];
+		const is_last = index === path.length - 1;
+		const next_segment = path[index + 1];
+		const next_value =
+			next_segment !== undefined && Number.isInteger(Number(next_segment))
+				? []
+				: {};
+
+		if (Array.isArray(current)) {
+			const array_index = Number(segment);
+			if (!Number.isInteger(array_index) || array_index < 0) {
+				throw new Error(
+					`Invalid array index in field path: ${path.join('.')}`,
 				);
+			}
+
+			if (is_last) {
+				current[array_index] = value;
+				return;
+			}
+
+			current[array_index] ??= next_value;
+			current = /** @type {Record<string, unknown> | Array<unknown>} */ (
+				current[array_index]
+			);
+			continue;
 		}
 
-		if (schema.default !== undefined) {
-			option.default = schema.default;
+		if (is_last) {
+			current[segment] = value;
+			return;
 		}
 
-		options[name] = option;
+		current[segment] ??= next_value;
+		current = /** @type {Record<string, unknown> | Array<unknown>} */ (
+			current[segment]
+		);
 	}
+}
 
-	return options;
+/**
+ * @param {unknown} value
+ * @param {Array<string>} paths
+ * @returns {unknown}
+ */
+function filter_fields(value, paths) {
+	if (paths.length === 0) return value;
+
+	if (!is_record(value) && !Array.isArray(value)) {
+		throw new Error(
+			'`--fields` can only be used with object or array output',
+		);
+	}
+
+	const result = Array.isArray(value) ? [] : {};
+
+	for (const path of paths) {
+		const segments = split_path(path);
+		if (segments.length === 0) {
+			throw new Error('`--fields` only supports dot-separated paths');
+		}
+		set_path_value(
+			result,
+			segments,
+			structuredClone(get_path_value(value, segments)),
+		);
+	}
+
+	return result;
 }
 
 /**
- * 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>}
+ * @param {Record<string, unknown>} result
+ * @param {OutputMode} output
+ * @returns {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;
+function select_output(result, output) {
+	if (output === 'full') return result;
+	if (output === 'structured') {
+		return result.structuredContent ?? null;
+	}
+	if (output === 'content') {
+		return result.content ?? [];
+	}
+	if (output === 'text') {
+		const content = result.content;
+
+		if (!Array.isArray(content)) {
+			throw new Error(
+				'`--output text` requires a tool result with content',
+			);
+		}
+
+		const lines = content.map((item) => {
+			if (
+				!is_record(item) ||
+				item.type !== 'text' ||
+				typeof item.text !== 'string'
+			) {
+				throw new Error(
+					'`--output text` only supports text content blocks',
+				);
 			}
-		} else {
-			result[key] = value;
+
+			return item.text;
+		});
+
+		return `${lines.join('\n')}\n`;
+	}
+
+	throw new Error(
+		`Invalid output mode: ${output}. Expected one of full, structured, content, text`,
+	);
+}
+
+/**
+ * @param {Record<string, unknown>} result
+ * @param {ToolOptions} options
+ * @returns {string}
+ */
+function format_tool_result(result, options) {
+	const selected = select_output(result, options.output ?? 'full');
+
+	if (typeof selected === 'string') {
+		if (options.fields) {
+			throw new Error('`--fields` cannot be used with `--output text`');
 		}
+		return selected;
 	}
 
-	return result;
+	return format_json(filter_fields(selected, parse_fields(options.fields)));
+}
+
+/**
+ * @param {Record<string, unknown>} result
+ * @returns {string}
+ */
+function format_tool_error(result) {
+	const content = result.content;
+
+	if (Array.isArray(content)) {
+		const text_blocks = content
+			.map((item) => {
+				if (
+					is_record(item) &&
+					item.type === 'text' &&
+					typeof item.text === 'string'
+				) {
+					return item.text;
+				}
+
+				return undefined;
+			})
+			.filter((item) => typeof item === 'string');
+
+		if (text_blocks.length > 0) {
+			return text_blocks.join('\n');
+		}
+	}
+
+	return JSON.stringify(result, null, 2);
 }
 
 /**
@@ -126,7 +359,7 @@ export class CliTransport {
 	/**
 	 * @type {string}
 	 */
-	#session_id = crypto.randomUUID();
+	#session_id = randomUUID();
 
 	/**
 	 * @param {McpServer<any, TCustom>} server
@@ -135,8 +368,11 @@ export class CliTransport {
 		this.#server = server;
 	}
 
+	#exit() {
+		process.exit(process.exitCode ?? 0);
+	}
+
 	/**
-	 * Sends a JSON-RPC request to the server and returns the result.
 	 * @param {string} method
 	 * @param {Record<string, unknown>} [params]
 	 * @param {TCustom} [ctx]
@@ -170,41 +406,76 @@ export class CliTransport {
 	}
 
 	/**
-	 * Initialize the MCP session with the server.
+	 * @param {string} method
+	 * @param {Record<string, unknown>} [params]
+	 * @param {TCustom} [ctx]
+	 */
+	async #notify(method, params, ctx) {
+		await this.#session_id_storage.run(this.#session_id, () =>
+			this.#server.receive(
+				{
+					jsonrpc: '2.0',
+					method,
+					...(params ? { params } : {}),
+				},
+				{
+					sessionId: this.#session_id,
+					custom: ctx,
+				},
+			),
+		);
+	}
+
+	/**
 	 * @param {TCustom} [ctx]
 	 * @returns {Promise<{ serverInfo?: { name?: string } }>}
 	 */
 	async #initialize(ctx) {
-		return this.#request(
+		const result = await this.#request(
 			'initialize',
 			{
 				protocolVersion: '2025-03-26',
 				capabilities: {},
-				clientInfo: {
-					name: 'tmcp-cli',
-					version: '0.0.1',
-				},
+				clientInfo: CLIENT_INFO,
 			},
 			ctx,
 		);
+
+		await this.#notify('notifications/initialized', undefined, ctx);
+
+		return result;
 	}
 
 	/**
-	 * 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 ?? [];
+		/** @type {Array<Tool>} */
+		const tools = [];
+		let cursor = undefined;
+
+		do {
+			const result = /** @type {ListToolsResult | undefined} */ (
+				await this.#request(
+					'tools/list',
+					cursor ? { cursor } : undefined,
+					ctx,
+				)
+			);
+
+			tools.push(...(result?.tools ?? []));
+			cursor = result?.nextCursor;
+		} while (cursor);
+
+		return tools;
 	}
 
 	/**
-	 * Calls a tool by name with arguments.
 	 * @param {string} name
 	 * @param {Record<string, unknown>} [args]
 	 * @param {TCustom} [ctx]
-	 * @returns {Promise<any>}
+	 * @returns {Promise<Record<string, unknown>>}
 	 */
 	async #call_tool(name, args, ctx) {
 		return this.#request(
@@ -218,60 +489,184 @@ export class CliTransport {
 	}
 
 	/**
-	 * Starts the CLI. Initializes the MCP session, lists tools,
-	 * builds yargs commands from the tool definitions, and parses argv.
+	 * @param {Map<string, Tool>} tool_map
+	 * @param {string} name
+	 * @returns {Tool}
+	 */
+	#get_tool(tool_map, name) {
+		const tool = tool_map.get(name);
+		if (!tool) {
+			throw new Error(`Unknown tool: ${name}`);
+		}
+		return tool;
+	}
+
+	/**
+	 * @param {Map<string, Tool>} tool_map
+	 * @param {string} name
+	 * @param {string | undefined} input
+	 * @param {ToolOptions} options
+	 * @param {TCustom} [ctx]
+	 */
+	async #run_tool(tool_map, name, input, options, ctx) {
+		const tool = this.#get_tool(tool_map, name);
+		const args = await resolve_tool_input(input);
+		const result = await this.#call_tool(tool.name, args, ctx);
+
+		if (result?.isError) {
+			process.stderr.write(`Error: ${format_tool_error(result)}\n`);
+			process.exitCode = 1;
+			return;
+		}
+
+		process.stdout.write(format_tool_result(result, options));
+	}
+
+	/**
 	 * @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;
-					}
-				},
+		try {
+			const init_result = await this.#initialize(ctx);
+			const tools = await this.#list_tools(ctx);
+			const script_name = init_result?.serverInfo?.name ?? 'tmcp';
+			const prog = sade(script_name);
+
+			/** @type {Map<string, Tool>} */
+			const tool_map = new Map();
+
+			for (const tool of tools) {
+				tool_map.set(tool.name, tool);
+			}
+
+			prog.command('tools', 'List available tools').action(() => {});
+			prog.command('schema <tool>', 'Print a tool schema').action(
+				() => {},
 			);
-		}
 
-		await cli.parseAsync();
+			prog.command('call <tool> [input]', 'Call a tool with JSON input')
+				.option(
+					'--output',
+					'Select full, structured, content, or text output',
+					'full',
+				)
+				.option(
+					'--fields',
+					'Select comma-separated dot paths from the chosen output',
+				)
+				.action(() => {});
+
+			for (const tool of tools) {
+				if (RESERVED_COMMANDS.has(tool.name)) {
+					process.stderr.write(
+						`Warning: skipping bare alias for tool "${tool.name}" because its name conflicts with a built-in command. Use \`call ${tool.name}\` instead.\n`,
+					);
+					continue;
+				}
+
+				if (UNSAFE_ALIAS_NAME.test(tool.name)) {
+					process.stderr.write(
+						`Warning: skipping bare alias for tool "${tool.name}" because its name contains CLI syntax characters. Use \`call ${tool.name}\` instead.\n`,
+					);
+					continue;
+				}
+
+				prog.command(`${tool.name} [input]`, tool.description ?? '')
+					.option(
+						'--output',
+						'Select full, structured, content, or text output',
+						'full',
+					)
+					.option(
+						'--fields',
+						'Select comma-separated dot paths from the chosen output',
+					)
+					.action(() => {});
+			}
+
+			const command_args = argv ?? process.argv.slice(2);
+			const args = [
+				'node',
+				script_name,
+				...(command_args.length === 0 ? ['--help'] : command_args),
+			];
+			const parsed = prog.parse(args, { lazy: true });
+
+			if (!parsed) {
+				this.#exit();
+				return;
+			}
+
+			const { name, args: handler_args } = parsed;
+			const { positionals, options } = extract_command_args(handler_args);
+
+			if (name === 'tools') {
+				process.stdout.write(format_json(tools));
+				this.#exit();
+				return;
+			}
+
+			if (name === 'schema') {
+				const tool_name = /** @type {string | undefined} */ (
+					positionals[0]
+				);
+				if (!tool_name) {
+					throw new Error('Missing tool name for `schema`');
+				}
+
+				process.stdout.write(
+					format_json(this.#get_tool(tool_map, tool_name)),
+				);
+				this.#exit();
+				return;
+			}
+
+			if (name === 'call') {
+				const tool_name = /** @type {string | undefined} */ (
+					positionals[0]
+				);
+				const input = /** @type {string | undefined} */ (
+					positionals[1]
+				);
+
+				if (!tool_name) {
+					throw new Error('Missing tool name for `call`');
+				}
+
+				await this.#run_tool(
+					tool_map,
+					tool_name,
+					input,
+					normalize_tool_options(options),
+					ctx,
+				);
+				this.#exit();
+				return;
+			}
+
+			if (tool_map.has(name)) {
+				const input = /** @type {string | undefined} */ (
+					positionals[0]
+				);
+				await this.#run_tool(
+					tool_map,
+					name,
+					input,
+					normalize_tool_options(options),
+					ctx,
+				);
+				this.#exit();
+				return;
+			}
+
+			this.#exit();
+		} catch (err) {
+			process.stderr.write(
+				`Error: ${err instanceof Error ? err.message : String(err)}\n`,
+			);
+			process.exitCode = 1;
+			this.#exit();
+		}
 	}
 }

package/src/internal.d.ts

@@ -1,20 +1,35 @@
-export type InputSchema = {
-	type: 'object';
-	properties?: Record<
-		string,
-		{
-			type?: string;
-			description?: string;
-			enum?: Array<unknown>;
-			default?: unknown;
-			items?: { type?: string };
-		}
-	>;
+export type JsonSchema = {
+	type?: string | Array<string>;
+	title?: string;
+	description?: string;
+	default?: unknown;
+	enum?: Array<unknown>;
+	properties?: Record<string, JsonSchema>;
 	required?: Array<string>;
+	items?: JsonSchema | Array<JsonSchema>;
+	additionalProperties?: boolean | JsonSchema;
+	oneOf?: Array<JsonSchema>;
+	anyOf?: Array<JsonSchema>;
+	allOf?: Array<JsonSchema>;
+	[key: string]: unknown;
+};
+
+export type InputSchema = JsonSchema & {
+	type: 'object';
 };
 
 export type Tool = {
 	name: string;
+	title?: string;
 	description?: string;
+	icons?: Array<unknown>;
+	annotations?: Record<string, unknown>;
+	_meta?: Record<string, unknown>;
 	inputSchema: InputSchema;
+	outputSchema?: JsonSchema;
+};
+
+export type ListToolsResult = {
+	tools: Array<Tool>;
+	nextCursor?: string;
 };

package/src/types/index.d.ts

@@ -3,14 +3,15 @@ declare module '@tmcp/transport-cli' {
 	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 type OutputMode = "full" | "structured" | "content" | "text";
+	export type ToolOptions = {
+		output?: OutputMode;
+		fields?: string;
+	};
 
 	export {};
 }

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

@@ -2,7 +2,9 @@
 	"version": 3,
 	"file": "index.d.ts",
 	"names": [
-		"CliTransport"
+		"CliTransport",
+		"OutputMode",
+		"ToolOptions"
 	],
 	"sources": [
 		"../index.js"
@@ -10,6 +12,6 @@
 	"sourcesContent": [
 		null
 	],
-	"mappings": ";;cA6GaA,YAAYA",
+	"mappings": ";;cAsVaA,YAAYA;;;;;;;aA5UgCC,UAAUA;aAIZC,WAAWA",
 	"ignoreList": []
 }

package/src/test.js

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