toolcraft 0.0.146 → 0.0.148

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.146",
+      "version": "0.0.148",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.146",
+      "version": "0.0.148",
       "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.146",
+      "version": "0.0.148",
       "license": "MIT"
     },
     {
@@ -123,7 +123,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.146",
+      "version": "0.0.148",
       "license": "MIT"
     },
     {

package/dist/http-hosted-oauth.compile-check.js

@@ -1,4 +1,9 @@
 import { hostedOAuth } from "./http-hosted-oauth.js";
+const ignoredRevocationObserver = async (grant) => {
+    const ignoredSubject = grant.subject;
+    void ignoredSubject;
+};
+void ignoredRevocationObserver;
 const ignoredHostedOAuth = hostedOAuth({
     publicUrl: "https://calendar.example/mcp",
     storage: ignoredStorage,
@@ -30,6 +35,7 @@ const ignoredHostedOAuth = hostedOAuth({
     }
 });
 void ignoredHostedOAuth;
+void ignoredHostedOAuth.assertProductionReady();
 const ignoredRedirectHostedOAuth = hostedOAuth({
     publicUrl: "https://calendar.example/mcp",
     storage: ignoredStorage,

package/dist/http-hosted-oauth.d.ts

@@ -1,5 +1,5 @@
 import { type JWK } from "jose";
-import { type AuthorizationServerStore, type AuthorizationTransactionRecord, type OAuthAuthorizationServerSigningKey } from "mcp-oauth-server";
+import { type AuthorizationServerStore, type AuthorizationGrantRecord, type AuthorizationTransactionRecord, type OAuthAuthorizationServerSigningKey } from "mcp-oauth-server";
 import type { HttpAdditionalRequestHandler, TinyHttpMcpServerOAuthOptions } from "tiny-http-mcp-server/server";
 export type HostedOAuthLoginFieldName = "email" | "password" | "apiKey" | (string & {});
 export interface HostedOAuthLoginField {
@@ -33,6 +33,7 @@ export interface HostedOAuthStorage<TCredential = unknown> {
     resolveSubject(providerName: string, accountId: string): Promise<string>;
     healthCheck?(): Promise<void>;
     cleanup?(now?: number): Promise<void>;
+    onGrantRevoked?(grant: AuthorizationGrantRecord): Promise<void> | void;
 }
 export interface HostedOAuthCredentialAccess<TCredential = unknown> {
     read(): Promise<TCredential>;
@@ -105,6 +106,7 @@ export interface HostedOAuthConfiguration<TCredential = unknown, TServices exten
     prepare(options?: {
         production?: boolean;
     }): Promise<PreparedHostedOAuth>;
+    assertProductionReady(): Promise<PreparedHostedOAuth>;
 }
 export declare function isHostedOAuthConfiguration(value: unknown): value is HostedOAuthConfiguration<unknown, object>;
 export declare function hostedOAuth<TCredential = unknown, TServices extends object = object>(options: HostedOAuthOptions<TCredential, TServices>): HostedOAuthConfiguration<TCredential, TServices>;

package/dist/http-hosted-oauth.js

@@ -85,6 +85,9 @@ export function hostedOAuth(options) {
                 issuer: new URL(publicUrl.origin),
                 scopes: this.advanced?.scopes ?? ["mcp", "offline_access"]
             };
+        },
+        async assertProductionReady() {
+            return this.prepare({ production: true });
         }
     };
 }
@@ -225,7 +228,8 @@ export async function prepareHostedOAuthRuntime(config) {
         accessTokenTtlSeconds: config.advanced?.accessTokenTtlSeconds,
         authorizationCodeTtlSeconds: config.advanced?.authorizationCodeTtlSeconds,
         authorizationTransactionTtlSeconds: config.advanced?.authorizationTransactionTtlSeconds,
-        refreshTokenTtlSeconds: config.advanced?.refreshTokenTtlSeconds
+        refreshTokenTtlSeconds: config.advanced?.refreshTokenTtlSeconds,
+        onGrantRevoked: config.storage.onGrantRevoked
     });
     const requestHandler = async (request, response) => {
         const url = new URL(request.url ?? "/", prepared.issuer);

package/dist/index.d.ts

@@ -95,7 +95,9 @@ 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;

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,11 +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 }),
-                ...(node.annotations === undefined ? {} : { annotations: { ...node.annotations } }),
                 description: buildToolDescription(node.description, params, node.examples, node.name, casing),
                 inputSchema: applySchemaCasing(toJsonSchema(params), casing),
                 ...(node.result === undefined

package/dist/testing/hosted-oauth-storage.d.ts

@@ -0,0 +1,6 @@
+import type { HostedOAuthStorage } from "../http-hosted-oauth.js";
+export interface HostedOAuthStorageConformanceOptions<TCredential> {
+    createStorage(): HostedOAuthStorage<TCredential> | Promise<HostedOAuthStorage<TCredential>>;
+    credentials: readonly [TCredential, TCredential];
+}
+export declare function verifyHostedOAuthStorage<TCredential>(options: HostedOAuthStorageConformanceOptions<TCredential>): Promise<void>;

package/dist/testing/hosted-oauth-storage.js

@@ -0,0 +1,140 @@
+import { isDeepStrictEqual } from "node:util";
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(`Hosted OAuth storage conformance failed: ${message}`);
+}
+export async function verifyHostedOAuthStorage(options) {
+    const storage = await options.createStorage();
+    const [firstCredential, secondCredential] = options.credentials;
+    const firstSubject = await storage.resolveSubject("provider", "account-a");
+    const repeatedSubject = await storage.resolveSubject("provider", "account-a");
+    const secondSubject = await storage.resolveSubject("provider", "account-b");
+    const otherProviderSubject = await storage.resolveSubject("other-provider", "account-a");
+    assert(firstSubject === repeatedSubject, "subject resolution must be stable");
+    assert(firstSubject !== secondSubject, "different provider accounts must resolve independently");
+    assert(firstSubject !== otherProviderSubject, "provider namespaces must resolve independently");
+    await storage.credentials.set(firstSubject, firstCredential);
+    assert(isDeepStrictEqual(await storage.credentials.get(firstSubject), firstCredential), "credentials must round-trip");
+    await storage.credentials.update(firstSubject, () => secondCredential);
+    assert(isDeepStrictEqual(await storage.credentials.get(firstSubject), secondCredential), "credential updates must persist");
+    let releaseFirstUpdate;
+    let markFirstUpdateStarted;
+    const firstUpdateStarted = new Promise((resolve) => {
+        markFirstUpdateStarted = resolve;
+    });
+    const releaseFirst = new Promise((resolve) => {
+        releaseFirstUpdate = resolve;
+    });
+    const firstUpdate = storage.credentials.update(firstSubject, async (current) => {
+        assert(isDeepStrictEqual(current, secondCredential), "credential updates must read current data");
+        markFirstUpdateStarted?.();
+        await releaseFirst;
+        return firstCredential;
+    });
+    await firstUpdateStarted;
+    let secondUpdateStarted = false;
+    const secondUpdate = storage.credentials.update(firstSubject, (current) => {
+        secondUpdateStarted = true;
+        assert(isDeepStrictEqual(current, firstCredential), "credential updates must execute atomically");
+        return secondCredential;
+    });
+    const updates = Promise.all([firstUpdate, secondUpdate]);
+    await Promise.resolve();
+    assert(!secondUpdateStarted, "credential updates must be serialized");
+    releaseFirstUpdate?.();
+    await updates;
+    assert(isDeepStrictEqual(await storage.credentials.get(firstSubject), secondCredential), "serialized credential updates must persist");
+    await storage.credentials.delete(firstSubject);
+    assert((await storage.credentials.get(firstSubject)) === undefined, "credential deletion must persist");
+    const transaction = {
+        id: "interaction-1",
+        clientId: "client-1",
+        redirectUri: "https://client.example/callback",
+        codeChallenge: "challenge",
+        resource: "https://resource.example/mcp",
+        scopes: ["mcp"],
+        createdAt: 1,
+        expiresAt: 2
+    };
+    await storage.interactions.set(transaction);
+    assert(isDeepStrictEqual(await storage.interactions.get(transaction.id), transaction), "interactions must round-trip");
+    await storage.interactions.delete(transaction.id);
+    assert((await storage.interactions.get(transaction.id)) === undefined, "interaction deletion must persist");
+    const firstKey = await storage.signingKey();
+    const secondKey = await storage.signingKey();
+    assert(firstKey.keyId === secondKey.keyId && isDeepStrictEqual(firstKey.publicJwk, secondKey.publicJwk), "signing keys must remain stable");
+    const restartedStorage = await options.createStorage();
+    if (storage.capabilities.stableKeys) {
+        const restartedKey = await restartedStorage.signingKey();
+        assert(firstKey.keyId === restartedKey.keyId &&
+            isDeepStrictEqual(firstKey.publicJwk, restartedKey.publicJwk), "stable signing keys must survive adapter restart");
+    }
+    if (storage.capabilities.durable) {
+        assert((await restartedStorage.resolveSubject("provider", "account-a")) === firstSubject, "durable subject resolution must survive adapter restart");
+    }
+    const store = storage.authorizationServer;
+    const client = { id: "client-1", redirectUris: ["https://client.example/callback"], createdAt: 1 };
+    await store.putClient(client);
+    assert(isDeepStrictEqual(await store.getClient(client.id), client), "clients must round-trip");
+    await store.putAuthorizationTransaction(transaction);
+    assert(isDeepStrictEqual(await store.takeAuthorizationTransaction(transaction.id), transaction) &&
+        (await store.takeAuthorizationTransaction(transaction.id)) === undefined, "authorization transactions must be consumed atomically");
+    const grant = {
+        id: "grant-1",
+        clientId: client.id,
+        subject: firstSubject,
+        resource: transaction.resource,
+        scopes: ["mcp", "offline_access"],
+        createdAt: 1
+    };
+    const code = {
+        tokenHash: "code-1",
+        grantId: grant.id,
+        clientId: client.id,
+        subject: firstSubject,
+        redirectUri: transaction.redirectUri,
+        codeChallenge: transaction.codeChallenge,
+        resource: transaction.resource,
+        scopes: grant.scopes,
+        expiresAt: 10
+    };
+    await store.putAuthorizationCode(code);
+    assert(isDeepStrictEqual(await store.takeAuthorizationCode(code.tokenHash), code) &&
+        (await store.takeAuthorizationCode(code.tokenHash)) === undefined, "authorization codes must be consumed atomically");
+    await store.putGrant(grant);
+    assert(isDeepStrictEqual(await store.getGrant(grant.id), grant), "grants must round-trip");
+    const accessToken = {
+        tokenHash: "access-1",
+        tokenId: "token-1",
+        grantId: grant.id,
+        subject: firstSubject,
+        clientId: client.id,
+        resource: transaction.resource,
+        expiresAt: 10
+    };
+    await store.putAccessToken(accessToken);
+    assert(isDeepStrictEqual(await store.getAccessToken(accessToken.tokenHash), accessToken), "access tokens must round-trip");
+    await store.revokeToken(accessToken.tokenHash, 5);
+    assert((await store.getAccessToken(accessToken.tokenHash))?.revokedAt === 5, "access-token revocation must persist");
+    const refreshToken = {
+        tokenHash: "refresh-1",
+        familyId: "family-1",
+        grantId: grant.id,
+        clientId: client.id,
+        subject: firstSubject,
+        resource: transaction.resource,
+        scopes: grant.scopes,
+        createdAt: 1,
+        expiresAt: 10,
+        status: "active"
+    };
+    await store.putRefreshToken(refreshToken);
+    const rotation = await store.rotateRefreshToken(refreshToken.tokenHash, "refresh-2", 2, 20);
+    assert(rotation.status === "rotated" && isDeepStrictEqual(rotation.previous, refreshToken), "refresh tokens must rotate atomically");
+    assert((await store.rotateRefreshToken(refreshToken.tokenHash, "refresh-3", 3, 20)).status ===
+        "replay", "refresh-token replay must be detected");
+    await store.revokeGrant(grant.id, 6);
+    assert((await store.getGrant(grant.id))?.revokedAt === 6, "grant revocation must persist");
+    await storage.healthCheck?.();
+    await storage.cleanup?.(Date.now());
+}

package/dist/testing/index.d.ts

@@ -2,3 +2,4 @@ export { createCommandTestHarness, type CommandTestHarness, type ConfirmationReq
 export { fakeFetch, fakeService, type FetchRoute, type ServiceCall } from "./fakes.js";
 export { createMemoryFs, type FsChange, type MemoryFs } from "./memory-fs.js";
 export type { ParityResult, SurfaceOutcome } from "./parity.js";
+export { verifyHostedOAuthStorage, type HostedOAuthStorageConformanceOptions } from "./hosted-oauth-storage.js";

package/dist/testing/index.js

@@ -1,3 +1,4 @@
 export { createCommandTestHarness } from "./harness.js";
 export { fakeFetch, fakeService } from "./fakes.js";
 export { createMemoryFs } from "./memory-fs.js";
+export { verifyHostedOAuthStorage } from "./hosted-oauth-storage.js";

package/node_modules/mcp-oauth-server/dist/index.d.ts

@@ -63,6 +63,7 @@ export type RefreshTokenRotationResult = {
     previous: RefreshTokenRecord;
 } | {
     status: "replay";
+    grant?: AuthorizationGrantRecord;
 } | {
     status: "invalid";
 };
@@ -79,7 +80,7 @@ export interface AuthorizationServerStore {
     getAccessToken(tokenHash: string): Promise<AccessTokenRecord | undefined>;
     putRefreshToken(token: RefreshTokenRecord): Promise<void>;
     rotateRefreshToken(tokenHash: string, replacementTokenHash: string, now: number, expiresAt: number): Promise<RefreshTokenRotationResult>;
-    revokeToken(tokenHash: string, now: number): Promise<void>;
+    revokeToken(tokenHash: string, now: number): Promise<void | AuthorizationGrantRecord>;
     revokeGrant(grantId: string, now: number): Promise<void>;
 }
 export interface AuthorizationInteractionStartContext {
@@ -111,6 +112,7 @@ export interface OAuthAuthorizationServerOptions {
     maxRequestBodyBytes?: number;
     now?: () => number;
     randomToken?: () => string;
+    onGrantRevoked?(grant: AuthorizationGrantRecord): Promise<void> | void;
 }
 export interface CompleteAuthorizationInput {
     transactionId: string;

package/node_modules/mcp-oauth-server/dist/index.js

@@ -206,7 +206,11 @@ export function createInMemoryAuthorizationServerStore() {
             }
             if (token.status === "rotated") {
                 revokeFamily(token.familyId, now);
-                return { status: "replay" };
+                const grant = grants.get(token.grantId);
+                return {
+                    status: "replay",
+                    ...(grant === undefined ? {} : { grant: structuredClone(grant) })
+                };
             }
             refreshTokens.set(tokenHash, { ...token, status: "rotated" });
             refreshTokens.set(replacementTokenHash, {
@@ -220,13 +224,19 @@ export function createInMemoryAuthorizationServerStore() {
         },
         async revokeToken(tokenHash, now) {
             const refreshToken = refreshTokens.get(tokenHash);
+            const accessToken = accessTokens.get(tokenHash);
+            const grantId = refreshToken?.grantId ?? accessToken?.grantId;
+            const grant = grantId === undefined ? undefined : grants.get(grantId);
+            const alreadyRevoked = grant?.revokedAt !== undefined ||
+                refreshToken?.status === "revoked" ||
+                accessToken?.revokedAt !== undefined;
             if (refreshToken !== undefined) {
                 revokeFamily(refreshToken.familyId, now);
             }
-            const accessToken = accessTokens.get(tokenHash);
             if (accessToken !== undefined) {
                 accessTokens.set(tokenHash, { ...accessToken, revokedAt: now });
             }
+            return grant === undefined || alreadyRevoked ? undefined : structuredClone(grant);
         },
         async revokeGrant(grantId, now) {
             const grant = grants.get(grantId);
@@ -258,6 +268,10 @@ export function createOAuthAuthorizationServer(options) {
     }
     const now = options.now ?? Date.now;
     const randomToken = options.randomToken ?? opaqueToken;
+    async function notifyGrantRevoked(grant) {
+        if (grant !== undefined)
+            await options.onGrantRevoked?.(grant);
+    }
     const accessTokenTtlMs = (options.accessTokenTtlSeconds ?? 300) * 1000;
     const authorizationCodeTtlMs = (options.authorizationCodeTtlSeconds ?? 60) * 1000;
     const authorizationTransactionTtlMs = (options.authorizationTransactionTtlSeconds ?? 600) * 1000;
@@ -534,11 +548,15 @@ export function createOAuthAuthorizationServer(options) {
         const tokenHash = hashToken(refreshToken);
         const existing = await options.store.rotateRefreshToken(tokenHash, replacementTokenHash, currentTime, currentTime + refreshTokenTtlMs);
         if (existing.status !== "rotated") {
+            if (existing.status === "replay")
+                await notifyGrantRevoked(existing.grant);
             throw new OAuthProtocolError("invalid_grant", "Refresh token is invalid or replayed.");
         }
         if (existing.previous.clientId !== body.get("client_id") ||
             existing.previous.resource !== requestedResource) {
+            const revokedGrant = await options.store.getGrant(existing.previous.grantId);
             await options.store.revokeGrant(existing.previous.grantId, currentTime);
+            await notifyGrantRevoked(revokedGrant);
             throw new OAuthProtocolError("invalid_grant", "Refresh token binding is invalid.");
         }
         const grant = await options.store.getGrant(existing.previous.grantId);
@@ -563,8 +581,9 @@ export function createOAuthAuthorizationServer(options) {
         requireFormContentType(request);
         const body = new URLSearchParams(await readRequestBody(request));
         const token = body.get("token");
-        if (token !== null)
-            await options.store.revokeToken(hashToken(token), now());
+        if (token !== null) {
+            await notifyGrantRevoked(await options.store.revokeToken(hashToken(token), now()));
+        }
         return new Response(null, { status: 200, headers: { "cache-control": "no-store" } });
     }
     async function handle(request) {
@@ -655,7 +674,9 @@ export function createOAuthAuthorizationServer(options) {
         denyAuthorization,
         verifyAccessToken,
         async revokeGrant(grantId) {
+            const grant = await options.store.getGrant(grantId);
             await options.store.revokeGrant(grantId, now());
+            await notifyGrantRevoked(grant?.revokedAt === undefined ? grant : undefined);
         }
     };
 }

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.146",
+      "version": "0.0.148",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

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

package/package.json

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