@cyanheads/mcp-ts-core 0.7.6 → 0.8.1

package/dist/mcp-server/tools/tool-registration.js

@@ -1,10 +1,10 @@
 import { config } from '../../config/index.js';
-import { createContext } from '../../core/context.js';
+import { attachTypedFail, createContext } from '../../core/context.js';
 import { isTaskToolDefinition, } from '../../mcp-server/tasks/utils/taskToolDefinition.js';
 import { createToolHandler, } from '../../mcp-server/tools/utils/toolHandlerFactory.js';
 import { authContext } from '../../mcp-server/transports/auth/lib/authContext.js';
 import { withRequiredScopes } from '../../mcp-server/transports/auth/lib/authUtils.js';
-import { JsonRpcErrorCode } from '../../types-global/errors.js';
+import { buildMetaWithErrorContract, JsonRpcErrorCode } from '../../types-global/errors.js';
 import { ErrorHandler } from '../../utils/internal/error-handler/errorHandler.js';
 import { getErrorMessage } from '../../utils/internal/error-handler/helpers.js';
 import { logger } from '../../utils/internal/logger.js';
@@ -97,13 +97,14 @@ export class ToolRegistry {
             const handler = createToolHandler(tool, this.services, notifiers);
             const title = tool.title ?? tool.annotations?.title ?? this.deriveTitleFromName(tool.name);
             // Type assertion required: SDK's conditional types don't resolve with erased generics
+            const mergedMeta = buildMetaWithErrorContract(tool._meta, tool.errors);
             server.registerTool(tool.name, {
                 title,
                 description: tool.description,
                 inputSchema: tool.input,
                 outputSchema: tool.output,
                 ...(tool.annotations && { annotations: tool.annotations }),
-                ...(tool._meta && { _meta: tool._meta }),
+                ...(mergedMeta && { _meta: mergedMeta }),
             }, handler);
             logger.debug(`Tool '${tool.name}' registered successfully.`, registrationContext);
         }, {
@@ -135,13 +136,14 @@ export class ToolRegistry {
             const formatter = (result) => tool.format
                 ? tool.format(result)
                 : [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+            const mergedAutoTaskMeta = buildMetaWithErrorContract(tool._meta, tool.errors);
             server.experimental.tasks.registerToolTask(tool.name, {
                 title,
                 description: tool.description,
                 inputSchema: tool.input,
                 outputSchema: tool.output,
                 ...(tool.annotations && { annotations: tool.annotations }),
-                ...(tool._meta && { _meta: tool._meta }),
+                ...(mergedAutoTaskMeta && { _meta: mergedAutoTaskMeta }),
                 execution: { taskSupport: 'optional' },
             }, {
                 createTask: async (args, extra) => {
@@ -218,7 +220,10 @@ export class ToolRegistry {
                     operation: 'AutoTaskHandler',
                     additionalContext: { toolName: tool.name, taskId },
                 });
-            const ctx = createContext({
+            // Mirror createToolHandler's ctx construction so auto-task handlers that
+            // call `ctx.fail(...)` work — without `attachTypedFail` they would crash
+            // with `ctx.fail is not a function` when the contract is declared.
+            const ctx = attachTypedFail(createContext({
                 appContext,
                 logger: services.logger,
                 storage: services.storage,
@@ -226,7 +231,7 @@ export class ToolRegistry {
                 taskCtx: { store: taskStore, taskId },
                 notifyResourceListChanged: notifiers.notifyResourceListChanged,
                 notifyResourceUpdated: notifiers.notifyResourceUpdated,
-            });
+            }), tool.errors);
             const result = await Promise.resolve(tool.handler(input, ctx));
             const validatedResult = tool.output.parse(result);
             await taskStore.storeTaskResult(taskId, 'completed', {
@@ -281,7 +286,8 @@ export class ToolRegistry {
         this.assertUniqueName(tool.name);
         await ErrorHandler.tryCatch(() => {
             const title = tool.title ?? tool.annotations?.title ?? this.deriveTitleFromName(tool.name);
-            // Use the experimental Tasks API to register task-based tools
+            // TaskToolDefinition is the escape hatch for fully-custom task lifecycle
+            // and does not declare an `errors[]` contract — `_meta` flows through unchanged.
             server.experimental.tasks.registerToolTask(tool.name, {
                 title,
                 description: tool.description,

package/dist/mcp-server/tools/tool-registration.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registration.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/tool-registration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-registration.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/tool-registration.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EACL,oBAAoB,GAErB,MAAM,gDAAgD,CAAC;AAExD,OAAO,EACL,iBAAiB,GAGlB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,iDAAiD,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACnF,OAAO,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAU3E,uEAAuE;AACvE,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAWzC,MAAM,OAAO,YAAY;IAKb;IACA;IALV,oEAAoE;IACnD,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAErD,YACU,QAAsB,EACtB,QAAiC;QADjC,aAAQ,GAAR,QAAQ,CAAc;QACtB,aAAQ,GAAR,QAAQ,CAAyB;IACxC,CAAC;IAEJ;;;;OAIG;IACI,KAAK,CAAC,WAAW,CAAC,MAAiB;QACxC,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAE7B,sEAAsE;QACtE,qEAAqE;QACrE,qEAAqE;QACrE,MAAM,SAAS,GAAqB;YAClC,yBAAyB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,uBAAuB,EAAE;YACjE,qBAAqB,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,EAAE,CAAC;SACnF,CAAC;QAEF,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,0BAA0B;SACtC,CAAC,CAAC;QAEH,MAAM,aAAa,GAAwB,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAyE,EAAE,CAAC;QAE3F,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,IAAI,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,aAAa,CAAC,IAAI,CAAC,GAAwB,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,MAAM,CAAC,KAAK,CACV,eAAe,aAAa,CAAC,MAAM,wBAAwB,SAAS,CAAC,MAAM,kBAAkB,EAC7F,OAAO,CACR,CAAC;QAEF,0EAA0E;QAC1E,yEAAyE;QACzE,iEAAiE;QAChE,MAAkD,CAAC,sBAAsB,EAAE,CAAC;QAE7E,kDAAkD;QAClD,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;YACpC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,MAAM,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAC9D,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QAED,wDAAwD;QACxD,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,6EAA6E;IACrE,gBAAgB,CAAC,IAAY;QACnC,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,kDAAkD;gBAC5E,oCAAoC,CACvC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAEO,mBAAmB,CAAC,IAAY;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,YAAY,CACxB,MAAiB,EACjB,IAAuB,EACvB,SAA2B;QAE3B,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrE,SAAS,EAAE,2BAA2B;YACtC,QAAQ,EAAE,IAAI,CAAC,IAAI;SACpB,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,sBAAsB,IAAI,CAAC,IAAI,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAEtE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEjC,MAAM,YAAY,CAAC,QAAQ,CACzB,GAAG,EAAE;YACH,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,IAAI,wDAAwD,CAC3F,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAClE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE3F,sFAAsF;YACtF,MAAM,UAAU,GAAG,0BAA0B,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACvE,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;gBACE,KAAK;gBACL,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;gBACvB,YAAY,EAAE,IAAI,CAAC,MAAM;gBACzB,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC1D,GAAG,CAAC,UAAU,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;aACzC,EACD,OAA0C,CAC3C,CAAC;YAEF,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,4BAA4B,EAAE,mBAAmB,CAAC,CAAC;QACpF,CAAC,EACD;YACE,SAAS,EAAE,mBAAmB,IAAI,CAAC,IAAI,EAAE;YACzC,OAAO,EAAE,mBAAmB;YAC5B,SAAS,EAAE,gBAAgB,CAAC,oBAAoB;YAChD,QAAQ,EAAE,IAAI;SACf,CACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,oBAAoB,CAChC,MAAiB,EACjB,IAAuB,EACvB,SAA2B;QAE3B,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrE,SAAS,EAAE,mCAAmC;YAC9C,QAAQ,EAAE,IAAI,CAAC,IAAI;SACpB,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,6CAA6C,IAAI,CAAC,IAAI,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAE7F,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEjC,MAAM,YAAY,CAAC,QAAQ,CACzB,GAAG,EAAE;YACH,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CACb,mCAAmC,IAAI,CAAC,IAAI,wDAAwD,CACrG,CAAC;YACJ,CAAC;YAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3F,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,wBAAwB,CAAC;YACxE,MAAM,SAAS,GAAG,CAAC,MAAe,EAAkB,EAAE,CACpD,IAAI,CAAC,MAAM;gBACT,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAiC,CAAC;gBAChD,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;YAEhE,MAAM,kBAAkB,GAAG,0BAA0B,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC/E,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,gBAAgB,CACxC,IAAI,CAAC,IAAI,EACT;gBACE,KAAK;gBACL,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;gBACvB,YAAY,EAAE,IAAI,CAAC,MAAM;gBACzB,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC1D,GAAG,CAAC,kBAAkB,IAAI,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;gBACxD,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;aACvC,EACD;gBACE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;oBAChC,6DAA6D;oBAC7D,6DAA6D;oBAC7D,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC;oBAEpD,oEAAoE;oBACpE,4DAA4D;oBAC5D,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACtC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAChC,CAAC;oBAED,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAE9C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC;wBAC5C,GAAG,EAAE,SAAS;wBACd,YAAY,EAAE,IAAI;qBACnB,CAAC,CAAC;oBAEH,6CAA6C;oBAC7C,KAAK,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE;wBACjF,MAAM,EAAE,IAAI,CAAC,MAAM;wBACnB,SAAS,EAAE,KAAK,CAAC,SAAS;wBAC1B,KAAK,EAAE,SAAS;wBAChB,UAAU;qBACX,CAAC,CAAC;oBAEH,OAAO,EAAE,IAAI,EAAE,CAAC;gBAClB,CAAC;gBACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBACtE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CACpC,CAAC,MAAM,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAmB;aACxE,CACF,CAAC;YAEF,MAAM,CAAC,KAAK,CACV,mBAAmB,IAAI,CAAC,IAAI,2CAA2C,EACvE,mBAAmB,CACpB,CAAC;QACJ,CAAC,EACD;YACE,SAAS,EAAE,2BAA2B,IAAI,CAAC,IAAI,EAAE;YACjD,OAAO,EAAE,mBAAmB;YAC5B,SAAS,EAAE,gBAAgB,CAAC,oBAAoB;YAChD,QAAQ,EAAE,IAAI;SACf,CACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,kBAAkB,CAC9B,IAAuB,EACvB,KAAc,EACd,QAAgC,EAChC,SAA2B,EAC3B,SAA8C,EAC9C,IAAqB;QAErB,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;QACtD,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAE9C,kEAAkE;QAClE,oEAAoE;QACpE,mFAAmF;QACnF,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,KAAK,CAAC,CAAC;QAEnF,wCAAwC;QACxC,MAAM,cAAc,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;YAC5C,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBAChC,eAAe,CAAC,KAAK,EAAE,CAAC;gBAC1B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;gBAC3D,eAAe,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAC;QAET,IAAI,CAAC;YACH,4EAA4E;YAC5E,2EAA2E;YAC3E,2EAA2E;YAC3E,MAAM,UAAU,GAAG,UAAU;gBAC3B,CAAC,CAAC,qBAAqB,CAAC,YAAY,CAAC,UAAU,EAAE;oBAC7C,SAAS,EAAE,iBAAiB;oBAC5B,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,MAAM;iBACP,CAAC;gBACJ,CAAC,CAAC,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,iBAAiB;oBAC5B,iBAAiB,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE;iBACnD,CAAC,CAAC;YAEP,yEAAyE;YACzE,yEAAyE;YACzE,mEAAmE;YACnE,MAAM,GAAG,GAAG,eAAe,CACzB,aAAa,CAAC;gBACZ,UAAU;gBACV,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,MAAM,EAAE,eAAe,CAAC,MAAM;gBAC9B,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE;gBACrC,yBAAyB,EAAE,SAAS,CAAC,yBAAyB;gBAC9D,qBAAqB,EAAE,SAAS,CAAC,qBAAqB;aACvD,CAAC,EACF,IAAI,CAAC,MAAM,CACZ,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAgC,EAAE,GAAG,CAAC,CAAC,CAAC;YAC1F,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAElD,MAAM,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE;gBACnD,OAAO,EAAE,SAAS,CAAC,eAAe,CAAC;gBACnC,iBAAiB,EAAE,eAAe;aACnC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,yEAAyE;YACzE,IAAI,eAAe,CAAC,MAAM,CAAC,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;gBACzF,OAAO;YACT,CAAC;YAED,mFAAmF;YACnF,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE;gBAC9B,SAAS,EAAE,aAAa,IAAI,CAAC,IAAI,EAAE;gBACnC,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE;gBACxC,KAAK;aACN,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,KAAK,gBAAgB,CAAC;gBACrE,MAAM,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,wBAAwB,KAAK,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;gBAC5F,MAAM,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE;oBAChD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,YAAY,EAAE,EAAE,CAAC;oBAC3D,OAAO,EAAE,IAAI;iBACd,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,aAAa,CAAC,cAAc,CAAC,CAAC;YAC9B,wEAAwE;YACxE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,gBAAgB,CAG5B,MAAiB,EAAE,IAAqD;QACxE,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrE,SAAS,EAAE,+BAA+B;YAC1C,QAAQ,EAAE,IAAI,CAAC,IAAI;SACpB,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,IAAI,kBAAkB,EAAE,mBAAmB,CAAC,CAAC;QAE1F,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEjC,MAAM,YAAY,CAAC,QAAQ,CACzB,GAAG,EAAE;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE3F,yEAAyE;YACzE,iFAAiF;YACjF,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,gBAAgB,CACxC,IAAI,CAAC,IAAI,EACT;gBACE,KAAK;gBACL,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;gBACvB,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjD,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC1D,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;gBACxC,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B,EACD,IAAI,CAAC,YAAY,CAClB,CAAC;YAEF,MAAM,CAAC,KAAK,CACV,cAAc,IAAI,CAAC,IAAI,2CAA2C,EAClE,mBAAmB,CACpB,CAAC;QACJ,CAAC,EACD;YACE,SAAS,EAAE,uBAAuB,IAAI,CAAC,IAAI,EAAE;YAC7C,OAAO,EAAE,mBAAmB;YAC5B,SAAS,EAAE,gBAAgB,CAAC,oBAAoB;YAChD,QAAQ,EAAE,IAAI;SACf,CACF,CAAC;IACJ,CAAC;CACF"}

package/dist/mcp-server/tools/utils/toolDefinition.d.ts

@@ -6,7 +6,8 @@
  */
 import type { ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 import type { ZodObject, ZodRawShape, z } from 'zod';
-import type { Context } from '../../../core/context.js';
+import type { HandlerContext, ReasonOf } from '../../../core/context.js';
+import type { ErrorContract } from '../../../types-global/errors.js';
 /**
  * Defines the annotations that provide hints about a tool's behavior.
  * These are not guarantees but are useful for client-side rendering and decision-making.
@@ -44,8 +45,13 @@ export interface ToolAnnotations {
 }
 /**
  * Represents the complete, self-contained definition of an MCP tool.
+ *
+ * `TErrors` is the const tuple of `ErrorContract` entries declared on the
+ * definition (or `undefined` when none are declared). The reason union extracted
+ * from `TErrors` flows into the handler's `ctx.fail` for compile-time-checked
+ * error throws.
  */
-export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>> {
+export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TErrors extends readonly ErrorContract[] | undefined = undefined> {
     /** Protocol-level metadata (e.g., MCP Apps extension). */
     _meta?: Record<string, unknown>;
     /** UI/behavior hints for clients. */
@@ -54,6 +60,26 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     auth?: string[];
     /** LLM-facing description. */
     description: string;
+    /**
+     * Declarative contract describing the failure modes this tool can surface.
+     *
+     * Each entry pairs a `JsonRpcErrorCode` with a stable `reason` string and a
+     * `when` description. Surfaces in `tools/list` under `_meta['mcp-ts-core/errors']`,
+     * so clients and agents can preview failure modes alongside the schema.
+     *
+     * **Type-driven.** When declared, the handler receives `ctx.fail(reason, …)`
+     * typed against the union of `reason` strings — TypeScript enforces that you
+     * can only `fail()` with a declared reason, and the runtime auto-populates
+     * `data.reason` on the thrown `McpError`.
+     *
+     * Optional. Without it, handlers still throw `McpError` directly and the
+     * framework's auto-classifier produces correct codes at runtime — the
+     * contract just adds compile-time enforcement and surfacing in tools/list.
+     *
+     * The startup linter validates each entry's `code` is a real `JsonRpcErrorCode`
+     * and that `reason` strings are unique within the contract.
+     */
+    errors?: TErrors;
     /**
      * Optional formatter mapping output to MCP `content[]`. Different MCP clients
      * forward different surfaces to the model: some (e.g., Claude Code) read
@@ -71,8 +97,16 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     /**
      * The core handler function. Receives validated input and unified Context.
      * Throw on failure — no try/catch needed.
+     *
+     * When `errors[]` is declared, `ctx` carries a typed `fail(reason, message?, data?)`
+     * helper keyed by the declared reason union — `ctx.fail('typo')` is a TS error.
+     * Without `errors[]`, `ctx` is plain `Context` and you throw `McpError` directly.
+     *
+     * Declared as a method (not an arrow property) so TypeScript checks the
+     * signature bivariantly — concrete tools with narrow `ctx.fail` types remain
+     * assignable to the type-erased `AnyToolDefinition` array.
      */
-    handler: (input: z.infer<TInput>, ctx: Context) => Promise<z.infer<TOutput>> | z.infer<TOutput>;
+    handler(input: z.infer<TInput>, ctx: HandlerContext<ReasonOf<TErrors>>): Promise<z.infer<TOutput>> | z.infer<TOutput>;
     /** Zod schema for input validation. All fields need `.describe()`. */
     input: TInput;
     /** Programmatic unique name (snake_case). */
@@ -93,11 +127,15 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     title?: string;
 }
 /** Type-erased union for mixed arrays passed to createApp(). */
-export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject<ZodRawShape>>;
+export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject<ZodRawShape>, readonly ErrorContract[] | undefined>;
 /**
  * Creates a tool definition with full type inference from Zod schemas.
  *
- * @example
+ * The `const` modifier on `TErrors` preserves literal types in the `errors[]`
+ * array without requiring `as const` at the call site, so the reason union
+ * flows into `ctx.fail` automatically.
+ *
+ * @example Without an error contract — throw `McpError` directly:
  * ```ts
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
@@ -106,23 +144,33 @@ export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject
  *     items: z.array(z.object({
  *       id: z.string().describe('Item ID'),
  *       name: z.string().describe('Item name'),
- *       status: z.string().describe('Current status'),
  *     })).describe('Matching items'),
  *   }),
- *   auth: ['tool:my_tool:read'],
- *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
- *     ctx.log.info('Processing', { query: input.query });
+ *     if (!input.query) throw notFound('Empty query');
  *     return { items: await search(input.query) };
  *   },
- *   // format() populates content[] — the markdown twin of structuredContent.
- *   // Different clients read different surfaces; both must be content-complete.
- *   format: (result) => [{
- *     type: 'text',
- *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
- *   }],
+ * });
+ * ```
+ *
+ * @example With a typed error contract — `ctx.fail(reason, …)`:
+ * ```ts
+ * const myTool = tool('my_tool', {
+ *   errors: [
+ *     { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items match the query' },
+ *     { reason: 'rate_limited', code: JsonRpcErrorCode.RateLimited,
+ *       when: 'Upstream rate limit hit', retryable: true },
+ *   ],
+ *   input: z.object({ query: z.string().describe('Search query') }),
+ *   output: z.object({ items: z.array(z.string()).describe('Matched items') }),
+ *   async handler(input, ctx) {
+ *     const items = await search(input.query);
+ *     if (items.length === 0) throw ctx.fail('no_match', `No matches for "${input.query}"`);
+ *     // ctx.fail('typo')  ← TypeScript error: 'typo' isn't in the contract
+ *     return { items };
+ *   },
  * });
  * ```
  */
-export declare function tool<TInput extends ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape>>(name: string, options: Omit<ToolDefinition<TInput, TOutput>, 'name'>): ToolDefinition<TInput, TOutput>;
+export declare function tool<TInput extends ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape>, const TErrors extends readonly ErrorContract[] | undefined = undefined>(name: string, options: Omit<ToolDefinition<TInput, TOutput, TErrors>, 'name'>): ToolDefinition<TInput, TOutput, TErrors>;
 //# sourceMappingURL=toolDefinition.d.ts.map

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAC9D,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC;IAE/D,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,qCAAqC;IACrC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;IACtD;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChG,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAM/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAChG,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,GACrD,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjC"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/utils/toolDefinition.js

@@ -10,7 +10,11 @@
 /**
  * Creates a tool definition with full type inference from Zod schemas.
  *
- * @example
+ * The `const` modifier on `TErrors` preserves literal types in the `errors[]`
+ * array without requiring `as const` at the call site, so the reason union
+ * flows into `ctx.fail` automatically.
+ *
+ * @example Without an error contract — throw `McpError` directly:
  * ```ts
  * const myTool = tool('my_tool', {
  *   description: 'Does something useful.',
@@ -19,21 +23,31 @@
  *     items: z.array(z.object({
  *       id: z.string().describe('Item ID'),
  *       name: z.string().describe('Item name'),
- *       status: z.string().describe('Current status'),
  *     })).describe('Matching items'),
  *   }),
- *   auth: ['tool:my_tool:read'],
- *   annotations: { readOnlyHint: true },
  *   async handler(input, ctx) {
- *     ctx.log.info('Processing', { query: input.query });
+ *     if (!input.query) throw notFound('Empty query');
  *     return { items: await search(input.query) };
  *   },
- *   // format() populates content[] — the markdown twin of structuredContent.
- *   // Different clients read different surfaces; both must be content-complete.
- *   format: (result) => [{
- *     type: 'text',
- *     text: result.items.map(i => `**${i.id}**: ${i.name} (${i.status})`).join('\n'),
- *   }],
+ * });
+ * ```
+ *
+ * @example With a typed error contract — `ctx.fail(reason, …)`:
+ * ```ts
+ * const myTool = tool('my_tool', {
+ *   errors: [
+ *     { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No items match the query' },
+ *     { reason: 'rate_limited', code: JsonRpcErrorCode.RateLimited,
+ *       when: 'Upstream rate limit hit', retryable: true },
+ *   ],
+ *   input: z.object({ query: z.string().describe('Search query') }),
+ *   output: z.object({ items: z.array(z.string()).describe('Matched items') }),
+ *   async handler(input, ctx) {
+ *     const items = await search(input.query);
+ *     if (items.length === 0) throw ctx.fail('no_match', `No matches for "${input.query}"`);
+ *     // ctx.fail('typo')  ← TypeScript error: 'typo' isn't in the contract
+ *     return { items };
+ *   },
  * });
  * ```
  */

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoGH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,IAAI,CAClB,IAAY,EACZ,OAAsD;IAEtD,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8IH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,IAAI,CAKlB,IAAY,EACZ,OAA+D;IAE/D,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAmG9E"}
+{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAwG9E"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.js

@@ -4,7 +4,7 @@
  * @module src/mcp-server/tools/utils/toolHandlerFactory
  */
 import { ZodError } from 'zod';
-import { createContext } from '../../../core/context.js';
+import { attachTypedFail, createContext } from '../../../core/context.js';
 import { withRequiredScopes } from '../../../mcp-server/transports/auth/lib/authUtils.js';
 import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
 import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
@@ -73,8 +73,10 @@ export function createToolHandler(def, services, notifiers) {
             }
             // Validate input
             const validatedInput = def.input.parse(input);
-            // Construct Context with detected capabilities
-            const ctx = createContext({
+            // Construct Context with detected capabilities. When the definition
+            // declares an error contract, `attachTypedFail` adds `ctx.fail` so
+            // handlers can `throw ctx.fail('reason', ...)`; otherwise ctx is unchanged.
+            const ctx = attachTypedFail(createContext({
                 appContext,
                 logger: services.logger,
                 storage: services.storage,
@@ -83,7 +85,7 @@ export function createToolHandler(def, services, notifiers) {
                 sample: wrapSample(sdkCaps),
                 notifyResourceListChanged: notifiers.notifyResourceListChanged,
                 notifyResourceUpdated: notifiers.notifyResourceUpdated,
-            });
+            }), def.errors);
             // Execute handler with performance measurement.
             // Wrap with Promise.resolve — handler may return sync or async.
             const result = await measureToolExecution(() => Promise.resolve(def.handler(validatedInput, ctx)), { ...appContext, toolName: def.name }, validatedInput);

package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -10,11 +10,19 @@ import type { z } from 'zod';
 import type { AuthContext, Context, ContextLogger, SamplingOpts } from '../core/context.js';
 import { StorageService } from '../storage/core/StorageService.js';
 import { type InMemoryProviderOptions } from '../storage/providers/inMemory/inMemoryProvider.js';
+import type { ErrorContract } from '../types-global/errors.js';
 export interface MockContextOptions {
     /** Auth context. */
     auth?: AuthContext;
     /** Mock elicitation handler. */
     elicit?: (message: string, schema: z.ZodObject<z.ZodRawShape>) => Promise<ElicitResult>;
+    /**
+     * Error contract to attach a typed `ctx.fail` against. Pass the definition's
+     * own `errors` array (`createMockContext({ errors: myTool.errors })`) so the
+     * mock's `fail` matches what the production handler factory wires up. Tests
+     * can then assert on `data.reason` without manually composing `createFail`.
+     */
+    errors?: readonly ErrorContract[];
     /** Mock resource list changed notifier. */
     notifyResourceListChanged?: () => void;
     /** Mock resource updated notifier. */

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAGb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAM1D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5F,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAoB3E;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAGb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5F,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAwB3E;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}

package/dist/testing/index.js

@@ -5,6 +5,7 @@
  * `createInMemoryStorage()` for unit-testing services in isolation.
  * @module src/testing/index
  */
+import { attachTypedFail } from '../core/context.js';
 import { StorageService } from '../storage/core/StorageService.js';
 import { InMemoryProvider, } from '../storage/providers/inMemory/inMemoryProvider.js';
 /**
@@ -156,7 +157,7 @@ export function createMockContext(options = {}) {
     const log = createMockLogger();
     const state = createMockState(options.tenantId);
     const progress = options.progress ? createMockProgress() : undefined;
-    return {
+    const ctx = {
         requestId: options.requestId ?? 'test-request-id',
         timestamp: new Date().toISOString(),
         log,
@@ -171,6 +172,9 @@ export function createMockContext(options = {}) {
         progress,
         uri: options.uri,
     };
+    // Mirror the production handler factory: when a contract is declared, attach
+    // a typed `fail` keyed by the contract's reasons. Empty contracts no-op.
+    return attachTypedFail(ctx, options.errors);
 }
 // ---------------------------------------------------------------------------
 // Storage helpers

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/dist/types-global/errors.d.ts

@@ -84,6 +84,12 @@ export declare const timeout: (message: string, data?: Record<string, unknown>,
 export declare const serviceUnavailable: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
 /** Create a ConfigurationError (-32008) error. */
 export declare const configurationError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
+/** Create an InternalError (-32603) error. */
+export declare const internalError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
+/** Create a SerializationError (-32070) error — JSON/XML/parser failures. */
+export declare const serializationError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
+/** Create a DatabaseError (-32010) error. */
+export declare const databaseError: (message: string, data?: Record<string, unknown>, options?: ErrorFactoryOptions) => McpError;
 /**
  * Zod schema for validating error objects. This schema can be used for:
  * - Validating error structures when parsing error responses from external services.
@@ -104,4 +110,80 @@ export declare const ErrorSchema: z.ZodObject<{
  * for error responses or when passing error information within the application.
  */
 export type ErrorResponse = z.infer<typeof ErrorSchema>;
+/**
+ * Declarative entry in a tool or resource's `errors[]` contract.
+ *
+ * Lets a definition advertise what it can fail with — the JSON-RPC code, a
+ * stable machine-readable `reason`, and a human-readable `when` description.
+ *
+ * **Where it shows up:**
+ * - Surfaced in `tools/list` / `resources/list` under
+ *   `_meta['mcp-ts-core/errors']`, so MCP clients and agents can preview failure
+ *   modes alongside the input/output schema.
+ * - Validated by the startup linter — invalid codes, duplicate `reason` strings
+ *   within a single definition, and (with the conformance check enabled)
+ *   handler bodies that throw codes not in the contract are flagged.
+ *
+ * **Authoring guidance:**
+ * - Keep `reason` short, snake_case, stable. Treat it like a CSS class name
+ *   the client can switch on. Don't change them across versions without notice.
+ * - Use `when` for the natural-language explanation, not the message that ends
+ *   up on the error itself. The error's runtime `message` is per-occurrence;
+ *   `when` is the type-level description.
+ * - Set `retryable` for ergonomics — clients can adjust their backoff strategy
+ *   without re-deriving from the code. When omitted, callers can infer from
+ *   the code (see `getErrorCategory`).
+ *
+ * @example
+ * ```ts
+ * tool('pubmed_fetch_articles', {
+ *   // ...
+ *   errors: [
+ *     { code: JsonRpcErrorCode.NotFound, reason: 'no_pmid_match',
+ *       when: 'None of the requested PMIDs returned data.' },
+ *     { code: JsonRpcErrorCode.RateLimited, reason: 'queue_full',
+ *       when: 'Local request queue is at capacity.', retryable: true },
+ *     { code: JsonRpcErrorCode.ServiceUnavailable, reason: 'ncbi_down',
+ *       when: 'NCBI E-utilities is unreachable after 6 retries.', retryable: true },
+ *   ],
+ *   // ...
+ * });
+ * ```
+ */
+export interface ErrorContract {
+    /** JSON-RPC error code this entry surfaces as. */
+    code: JsonRpcErrorCode;
+    /**
+     * Stable machine-readable identifier for this failure mode.
+     * Should be `snake_case`, unique within a single definition's `errors[]`,
+     * and treated as part of the public API — clients may switch on it.
+     */
+    reason: string;
+    /**
+     * Whether the failure is transient (eligible for retry). Optional hint for
+     * clients; when omitted, callers fall back to inferring from the code.
+     */
+    retryable?: boolean;
+    /**
+     * Human-readable description of when this error occurs. Surfaced to LLMs and
+     * UI clients via `tools/list`. Type-level, not per-occurrence — different
+     * from the actual `error.message` thrown at runtime.
+     */
+    when: string;
+}
+/**
+ * The MCP `_meta` namespace key under which `errors[]` is published in
+ * `tools/list` and `resources/list`. Namespaced to avoid collisions with
+ * other framework or vendor extensions.
+ */
+export declare const ERROR_CONTRACT_META_KEY = "mcp-ts-core/errors";
+/**
+ * Merges a tool/resource's `errors[]` contract into its `_meta` object under
+ * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
+ * absent so callers can spread conditionally without producing an empty
+ * `_meta` field. Used by the tool and resource registries.
+ *
+ * @internal
+ */
+export declare function buildMetaWithErrorContract(baseMeta: Record<string, unknown> | undefined, errors: readonly unknown[] | undefined): Record<string, unknown> | undefined;
 //# sourceMappingURL=errors.d.ts.map

package/dist/types-global/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"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"}

package/dist/types-global/errors.js

@@ -96,6 +96,12 @@ export const timeout = (message, data, options) => new McpError(JsonRpcErrorCode
 export const serviceUnavailable = (message, data, options) => new McpError(JsonRpcErrorCode.ServiceUnavailable, message, data, options);
 /** Create a ConfigurationError (-32008) error. */
 export const configurationError = (message, data, options) => new McpError(JsonRpcErrorCode.ConfigurationError, message, data, options);
+/** Create an InternalError (-32603) error. */
+export const internalError = (message, data, options) => new McpError(JsonRpcErrorCode.InternalError, message, data, options);
+/** Create a SerializationError (-32070) error — JSON/XML/parser failures. */
+export const serializationError = (message, data, options) => new McpError(JsonRpcErrorCode.SerializationError, message, data, options);
+/** Create a DatabaseError (-32010) error. */
+export const databaseError = (message, data, options) => new McpError(JsonRpcErrorCode.DatabaseError, message, data, options);
 /**
  * Zod schema for validating error objects. This schema can be used for:
  * - Validating error structures when parsing error responses from external services.
@@ -132,4 +138,23 @@ export const ErrorSchema = z
         .describe('Optional structured data providing more context about the error'),
 })
     .describe('Schema for validating structured error objects, ensuring consistency in error reporting.');
+/**
+ * The MCP `_meta` namespace key under which `errors[]` is published in
+ * `tools/list` and `resources/list`. Namespaced to avoid collisions with
+ * other framework or vendor extensions.
+ */
+export const ERROR_CONTRACT_META_KEY = 'mcp-ts-core/errors';
+/**
+ * Merges a tool/resource's `errors[]` contract into its `_meta` object under
+ * {@link ERROR_CONTRACT_META_KEY}. Returns `undefined` when both sides are
+ * absent so callers can spread conditionally without producing an empty
+ * `_meta` field. Used by the tool and resource registries.
+ *
+ * @internal
+ */
+export function buildMetaWithErrorContract(baseMeta, errors) {
+    if (!errors || errors.length === 0)
+        return baseMeta;
+    return { ...(baseMeta ?? {}), [ERROR_CONTRACT_META_KEY]: errors };
+}
 //# sourceMappingURL=errors.js.map