@modeltoolsprotocol/sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @modeltoolsprotocol/sdk
 
-Add MTP `--describe` support to any Commander.js CLI. One function call, zero boilerplate.
+Add MTP `--mtp-describe` support to any Commander.js CLI. One function call, zero boilerplate.
 
 ## Install
 
@@ -42,7 +42,7 @@ program.parse();
 ```
 
 ```bash
-$ filetool --describe          # MTP JSON schema
+$ filetool --mtp-describe          # MTP JSON schema
 $ filetool convert data.csv    # normal operation
 ```
 
@@ -50,7 +50,7 @@ $ filetool convert data.csv    # normal operation
 
 ### `withDescribe(program, options?)`
 
-Adds `--describe` to an existing Commander program. When invoked, outputs MTP-compliant JSON and exits.
+Adds `--mtp-describe` to an existing Commander program. When invoked, outputs MTP-compliant JSON and exits.
 
 - **program** — a Commander `Command` instance (your root program)
 - **options.commands** — per-command annotations keyed by command name (stdin, stdout, examples, argTypes)
@@ -67,6 +67,8 @@ The SDK introspects Commander's own data structures — `cmd.options`, `cmd.regi
 
 ### Type Inference
 
+Arg types describe flags and positional arguments, which are always scalar on the command line:
+
 | Commander signal | MTP type |
 |---|---|
 | `option.isBoolean()` | `"boolean"` |
@@ -75,6 +77,49 @@ The SDK introspects Commander's own data structures — `cmd.options`, `cmd.regi
 | explicit `argTypes` override | whatever you say |
 | everything else | `"string"` |
 
+For structured data flowing through stdin/stdout, use the `schema` field in IO descriptors. This supports full JSON Schema (draft 2020-12): nested objects, arrays, unions, pattern validation, conditional fields.
+
+### Structured IO
+
+When a command accepts or produces JSON, describe the shape with a JSON Schema:
+
+```typescript
+withDescribe(program, {
+  commands: {
+    process: {
+      stdin: {
+        contentType: "application/json",
+        description: "Configuration to process",
+        schema: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            settings: {
+              type: "object",
+              properties: {
+                retries: { type: "integer" },
+                endpoints: { type: "array", items: { type: "string", format: "uri" } },
+              },
+            },
+          },
+          required: ["name"],
+        },
+      },
+      stdout: {
+        contentType: "application/json",
+        schema: {
+          type: "object",
+          properties: {
+            status: { type: "string", enum: ["ok", "error"] },
+            results: { type: "array", items: { type: "object" } },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
 ### Command Naming
 
 - Programs with subcommands: each leaf command gets a space-separated path (e.g., `"auth login"`)
@@ -83,7 +128,7 @@ The SDK introspects Commander's own data structures — `cmd.options`, `cmd.regi
 
 ### Filtered Options
 
-These are automatically excluded from schema output: `--help`, `--version`, `--describe`, and any hidden options.
+These are automatically excluded from schema output: `--help`, `--version`, `--mtp-describe`, and any hidden options.
 
 ## Single-Command Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modeltoolsprotocol/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Add MTP --describe support to any Commander.js CLI",
   "license": "Apache-2.0",
   "type": "module",

package/src/index.ts

@@ -10,9 +10,9 @@ export function withDescribe(
   program: Command,
   options?: DescribeOptions,
 ): Command {
-  program.option("--describe", "Output machine-readable MTP JSON schema");
+  program.option("--mtp-describe", "Output machine-readable MTP JSON schema");
 
-  program.on("option:describe", () => {
+  program.on("option:mtp-describe", () => {
     const schema = describe(program, options);
     const clean = JSON.parse(JSON.stringify(schema));
     console.log(JSON.stringify(clean, null, 2));

package/src/introspect.ts

@@ -7,6 +7,8 @@ import type {
   ToolSchema,
 } from "./types.js";
 
+const MTP_SPEC_VERSION = "2026-02-07";
+
 // Commander stores these as private fields. We access them for filtering.
 interface CommandInternals {
   _helpOption?: Option | null;
@@ -202,6 +204,7 @@ export function generateSchema(
   const internals = program as unknown as CommandInternals;
 
   const schema: ToolSchema = {
+    specVersion: MTP_SPEC_VERSION,
     name: program.name(),
     version: internals._version || "",
     description: program.description() || "",
@@ -209,7 +212,7 @@ export function generateSchema(
       program,
       options?.commands,
       undefined,
-      "describe",
+      "mtpDescribe",
     ),
   };
 

package/src/types.ts

@@ -35,6 +35,7 @@ export interface AuthConfig {
 }
 
 export interface ToolSchema {
+  specVersion: string;
   name: string;
   version: string;
   description: string;