toolcraft 0.0.145 → 0.0.147

package/README.md

@@ -334,6 +334,28 @@ defineCommand({
 });
 ```
 
+MCP assumes an unannotated tool may mutate data destructively, is not safe to retry, and can
+interact with an open world. Declare the standard hints on each MCP command so clients can present
+the operation accurately:
+
+```ts
+defineCommand({
+  name: "inspect",
+  title: "Inspect deployment",
+  description: "Inspect a deployment without changing it.",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  scope: ["mcp"],
+  params: S.Object({ deploymentId: S.String() }),
+  result: S.Object({ status: S.String() }),
+  handler: async ({ params }) => inspectDeployment(params.deploymentId)
+});
+```
+
 ## HTTP errors
 
 Toolcraft exports a fixed HTTP error hierarchy for transports and generated API clients:
@@ -554,7 +576,9 @@ Toolcraft configuration is code-first. Use `defineCommand(config)` and `defineGr
 ### `defineCommand(config)`
 
 - `name: string`
+- `title?: string` — human-readable MCP display name.
 - `description?: string`
+- `annotations?: { title?; readOnlyHint?; destructiveHint?; idempotentHint?; openWorldHint? }` — standard MCP behavior hints passed through unchanged.
 - `aliases?: string[]`
 - `positional?: string[]` — parameter names mapped from CLI argv order.
 - `params: S.Object(...)` — input schema from `toolcraft-schema`.

package/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.145",
+      "version": "0.0.147",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.145",
+      "version": "0.0.147",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -98,7 +98,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "license": "MIT"
     },
     {
@@ -113,7 +113,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.145",
+      "version": "0.0.147",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.145",
+      "version": "0.0.147",
       "license": "MIT"
     },
     {

package/dist/index.d.ts

@@ -95,6 +95,14 @@ export interface Renderers<TResult> {
     markdown?: (result: TResult, primitives: RenderPrimitives) => string;
     json?: (result: TResult, primitives: RenderPrimitives) => unknown;
 }
+/** Standard MCP hints that describe a tool's behavior to clients. */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 export type HandlerContext<TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TSecrets extends SecretDeclarations | undefined = undefined, TServices extends object = EmptyServices> = TServices & {
     params: Static<TParamsSchema>;
     secrets: InferSecrets<TSecrets>;
@@ -106,7 +114,9 @@ export type HandlerContext<TParamsSchema extends ObjectSchema<any> = AnyObjectSc
 };
 export interface CommandConfig<TServices extends object, TParamsSchema extends ObjectSchema<any>, TSecrets extends SecretDeclarations | undefined, TResult> {
     name: string;
+    title?: string;
     description?: string;
+    annotations?: ToolAnnotations;
     hidden?: boolean;
     examples?: CommandExample[];
     aliases?: string[];
@@ -138,7 +148,9 @@ export interface StreamCommandConfig<TServices extends object, TParamsSchema ext
 export interface Command<TServices extends object = EmptyServices, TParamsSchema extends ObjectSchema<any> = AnyObjectSchema, TSecrets extends SecretDeclarations | undefined = undefined, TResult = unknown> {
     kind: "command";
     name: string;
+    title?: string;
     description?: string;
+    annotations?: ToolAnnotations;
     hidden: boolean;
     examples: CommandExample[];
     aliases: string[];

package/dist/index.js

@@ -33,6 +33,9 @@ function cloneRequires(requires) {
         check: requires.check
     };
 }
+function cloneToolAnnotations(annotations) {
+    return annotations === undefined ? undefined : { ...annotations };
+}
 function cloneStringArray(values) {
     return values === undefined ? undefined : [...values];
 }
@@ -291,7 +294,9 @@ function createBaseCommand(config) {
     const command = {
         kind: "command",
         name: config.name,
+        title: config.title,
         description: config.description,
+        annotations: cloneToolAnnotations(config.annotations),
         hidden: config.hidden ?? false,
         examples: cloneCommandExamples(config.examples),
         aliases: [...(config.aliases ?? [])],
@@ -309,6 +314,8 @@ function createBaseCommand(config) {
     };
     Object.defineProperty(command, commandConfigSymbol, {
         value: {
+            title: config.title,
+            annotations: cloneToolAnnotations(config.annotations),
             scope: cloneScope(config.scope),
             hidden: config.hidden ?? false,
             examples: cloneCommandExamples(config.examples),
@@ -360,7 +367,9 @@ function materializeCommand(command, inherited) {
     const materialized = {
         kind: "command",
         name: command.name,
+        title: internal.title,
         description: command.description,
+        annotations: cloneToolAnnotations(internal.annotations),
         hidden: internal.hidden,
         examples: cloneCommandExamples(internal.examples),
         aliases: [...command.aliases],
@@ -378,6 +387,8 @@ function materializeCommand(command, inherited) {
     };
     Object.defineProperty(materialized, commandConfigSymbol, {
         value: {
+            title: internal.title,
+            annotations: cloneToolAnnotations(internal.annotations),
             scope: cloneScope(internal.scope),
             hidden: internal.hidden,
             examples: cloneCommandExamples(internal.examples),

package/dist/mcp-proxy.js

@@ -78,7 +78,9 @@ function createProxyCommand(parent, tool, commandName, connection) {
     return markProxyNode({
         kind: "command",
         name: commandName,
+        title: tool.title,
         description: tool.description,
+        annotations: tool.annotations === undefined ? undefined : { ...tool.annotations },
         hidden: false,
         examples: [],
         aliases: [],

package/dist/mcp.js

@@ -219,9 +219,11 @@ function enumerateTools(root, casing, allowlist, omitRootToolNamePrefix) {
             }
             commandPathsByToolName.set(name, resolvedCommandPath);
             tools.push({
+                ...(node.annotations === undefined ? {} : { annotations: { ...node.annotations } }),
                 command: node,
                 commandPath: resolvedCommandPath,
                 name,
+                ...(node.title === undefined ? {} : { title: node.title }),
                 description: buildToolDescription(node.description, params, node.examples, node.name, casing),
                 inputSchema: applySchemaCasing(toJsonSchema(params), casing),
                 ...(node.result === undefined
@@ -915,12 +917,18 @@ function createResolvedMCPServer(root, options, runtime = {}) {
                 throw toToolError(error, report?.displayPath);
             }
         };
-        if (tool.outputSchema === undefined) {
-            server.tool(tool.name, tool.description, tool.inputSchema, handler);
-        }
-        else {
-            server.tool(tool.name, tool.description, tool.inputSchema, handler, tool.outputSchema);
-        }
+        server.registerTool({
+            name: tool.name,
+            ...(tool.title === undefined ? {} : { title: tool.title }),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.outputSchema === undefined
+                ? {}
+                : {
+                    outputSchema: tool.outputSchema
+                }),
+            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations })
+        }, handler);
     }
     return {
         ...server,

package/node_modules/tiny-http-mcp-server/dist/composition.json

@@ -18,7 +18,7 @@
     },
     {
       "name": "tiny-http-mcp-server",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "license": "MIT"
     },
     {

package/node_modules/tiny-http-mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-http-mcp-server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Minimal MCP server over HTTP built on tiny-stdio-mcp-server",
   "type": "module",
   "main": "dist/index.js",

package/node_modules/tiny-mcp-client/dist/index.d.ts

@@ -304,6 +304,7 @@ declare class McpClient {
 }
 interface Tool {
     name: string;
+    title?: string;
     description?: string;
     inputSchema: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.145",
+      "version": "0.0.147",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.145",
+  "version": "0.0.147",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.145",
+  "version": "0.0.147",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -158,7 +158,7 @@
     "yaml"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.145",
+    "toolcraft-schema": "0.0.147",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",