@softure-ai/mcp-access 0.2.8 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 export declare const MODULE_ID = "mcp-access";
+/**
+ * Name of the runtime switch that turns writes off without a deploy. Defined in
+ * `@softure-ai/feature-switches`, writes need it on as well as `allowWrites` and the token's write access;
+ * not defined, `allowWrites` alone decides.
+ */
+export declare const WRITES_ENABLED_SWITCH = "mcp-access.writes_enabled";
 /**
  * The rate limit bucket of `POST /api/mcp`, to spread into `security({ buckets })`: requests per
  * client address, counted before the token is verified. Every request counts, so the limit is for
@@ -21,6 +27,23 @@ export declare const MCP_RATE_LIMIT_BUCKETS: {
         readonly key: "ip";
     };
 };
+/**
+ * The rate limit buckets of `requireApiToken`, to spread into `security({ buckets })` when the app sets
+ * `apiTokens`: `api` counts requests per client address before the token is looked up (guessing),
+ * `api-token` counts requests per verified token (one script or Shortcut cannot flood a route).
+ */
+export declare const API_TOKEN_RATE_LIMIT_BUCKETS: {
+    readonly api: {
+        readonly limit: 300;
+        readonly windowMinutes: 15;
+        readonly key: "ip";
+    };
+    readonly "api-token": {
+        readonly limit: 120;
+        readonly windowMinutes: 15;
+        readonly key: "subject";
+    };
+};
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
  * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
@@ -54,6 +77,28 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
         pending: string;
         limit: string;
     };
+    apiScopes: {
+        title: string;
+        lead: string;
+        read: string;
+        write: string;
+        writeUnavailable: string;
+    };
+    apiIssue: {
+        title: string;
+        name: string;
+        nameHint: string;
+        scopes: string;
+        submit: string;
+        pending: string;
+    };
+    apiIssued: {
+        title: string;
+        once: string;
+        scopes: string;
+        tokenTitle: string;
+        headerTitle: string;
+    };
     issued: {
         title: string;
         once: string;
@@ -76,6 +121,8 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
     };
     list: {
         title: string;
+        kindMcp: string;
+        kindApi: string;
         empty: string;
         readOnly: string;
         readWrite: string;
@@ -104,7 +151,8 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
         title: string;
         lead: string;
         app: string;
-        returnsTo: string;
+        redirectLabel: string;
+        redirectHint: string;
         account: string;
         access: string;
         readAccess: string;
@@ -124,9 +172,36 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
         noFields: string;
         fieldRenamed: string;
     };
+    confirmation: {
+        ask: string;
+        fieldDescription: string;
+        invalid: string;
+        otherTool: string;
+        otherAccount: string;
+        expired: string;
+        argumentsChanged: string;
+        estimateChanged: string;
+        used: string;
+    };
     serverInfoTool: {
         description: string;
     };
+    operations: {
+        statusToolDescription: string;
+        cancelToolDescription: string;
+        started: string;
+        queued: string;
+        running: string;
+        cancelRequested: string;
+        succeeded: string;
+        failed: string;
+        cancelled: string;
+        notFound: string;
+        finished: string;
+        taskQueued: string;
+        taskRunning: string;
+        taskCancelRequested: string;
+    };
     errors: {
         "mcp-access": {
             name_required: string;
@@ -136,6 +211,9 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
             grant_not_found: string;
             issue_refused: string;
             write_refused: string;
+            api_disabled: string;
+            scope_required: string;
+            scope_unknown: string;
         };
         auth: {
             unauthenticated: string;
@@ -180,11 +258,26 @@ export declare const mcpAccess: import("@softure-ai/core").ModuleFactory<{
             protectedResource: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodCustom<(origins: import("./origins.js").McpOrigins) => Readonly<Record<string, unknown>>, (origins: import("./origins.js").McpOrigins) => Readonly<Record<string, unknown>>>, import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>]>>;
         }, import("zod/v4/core").$strict>>;
     }, import("zod/v4/core").$strict>>;
+    apiTokens: import("zod").ZodOptional<import("zod").ZodObject<{
+        prefix: import("zod").ZodDefault<import("zod").ZodString>;
+        scopes: import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            access: import("zod").ZodEnum<{
+                read: "read";
+                write: "write";
+            }>;
+            description: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>;
+        examples: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodObject<{
+            title: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+            text: import("zod").ZodRecord<import("zod").ZodString & import("zod").ZodType<string, string, import("zod/v4/core").$ZodTypeInternals<string, string>>, import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>>;
+    }, import("zod/v4/core").$strict>>;
 }, import("zod/v4/core").$strict>>;
 export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, type McpClientSetupInput, } from "./client-setup.js";
-export type { AccessTokenStatus, AccessTokenView, IssuedToken, IssueTokenFormState, McpAccessErrorCode, McpIssueRefusal, McpIssueRefusalCode, McpClientSetup, McpServerIdentity, OAuthGrantView, RevokeGrantFormState, RevokeTokenFormState, TokenFormErrorCode, } from "./contract.js";
+export type { AccessTokenKind, AccessTokenStatus, AccessTokenView, ApiTokenErrorCode, ApiTokenExample, ApiTokenIdentity, ApiTokenRefusal, IssuedApiTokenView, IssuedToken, IssueTokenFormState, McpAccessErrorCode, McpIssueRefusal, McpIssueRefusalCode, McpClientSetup, McpServerIdentity, OAuthGrantView, RevokeGrantFormState, RevokeTokenFormState, TokenFormErrorCode, } from "./contract.js";
 export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.js";
-export { MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, type McpAccessOptions, type McpAccessOptionsInput, type McpAppOriginResolver, type McpMetadataExtension, type McpOAuthOptions, type McpToolAccess, type McpToolDefinition, type McpToolDefinitionInput, } from "./options.js";
+export { API_SCOPE_PATTERN, API_TOKEN_PREFIX_PATTERN, MAX_API_TOKEN_SCOPES, MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, type ApiScopeDefinition, type ApiTokenOptions, type ApiTokenOptionsInput, type McpAccessOptions, type McpAccessOptionsInput, type McpAppOriginResolver, type McpMetadataExtension, type McpOAuthOptions, type McpToolAccess, type McpToolDefinition, type McpToolDefinitionInput, } from "./options.js";
 export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin, type McpOriginRequest, type McpOrigins } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, type OAuthClientRow, type OAuthTokenEndpointAuthMethod } from "./schema.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;IAEjC;;;;OAIG;;;;;;CAE8D,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCA4BpB,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,mCAAmC,EACnC,iCAAiC,EACjC,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,4BAA4B,EAAE,MAAM,aAAa,CAAC;AACvJ,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,8BAA8B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;IAEjC;;;;OAIG;;;;;;CAE8D,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;CAG0B,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAkCpB,CAAC;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,mCAAmC,EACnC,iCAAiC,EACjC,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,4BAA4B,EAAE,MAAM,aAAa,CAAC;AACvJ,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -9,6 +9,12 @@ import { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 import { checkAccessTokensTable } from "./server/health.js";
 import { mcpAccessPrivacyContributor } from "./server/privacy.js";
 export const MODULE_ID = "mcp-access";
+/**
+ * Name of the runtime switch that turns writes off without a deploy. Defined in
+ * `@softure-ai/feature-switches`, writes need it on as well as `allowWrites` and the token's write access;
+ * not defined, `allowWrites` alone decides.
+ */
+export const WRITES_ENABLED_SWITCH = "mcp-access.writes_enabled";
 /**
  * The rate limit bucket of `POST /api/mcp`, to spread into `security({ buckets })`: requests per
  * client address, counted before the token is verified. Every request counts, so the limit is for
@@ -23,6 +29,15 @@ export const MCP_RATE_LIMIT_BUCKETS = {
      */
     "mcp-oauth": { limit: 60, windowMinutes: 15, key: "ip" },
 };
+/**
+ * The rate limit buckets of `requireApiToken`, to spread into `security({ buckets })` when the app sets
+ * `apiTokens`: `api` counts requests per client address before the token is looked up (guessing),
+ * `api-token` counts requests per verified token (one script or Shortcut cannot flood a route).
+ */
+export const API_TOKEN_RATE_LIMIT_BUCKETS = {
+    api: { limit: 300, windowMinutes: 15, key: "ip" },
+    "api-token": { limit: 120, windowMinutes: 15, key: "subject" },
+};
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
  * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
@@ -30,12 +45,18 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
     manifest: {
         id: MODULE_ID,
-        version: "0.2.8",
+        version: "0.3.0",
         dependsOn: { security: "^0.2.0", auth: "^0.2.0", jobs: "^0.1.1?", ops: "^0.2.0?" },
         dbSchema: "mcp",
-        tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window"],
-        env: [],
-        switches: [],
+        tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window", "used_confirmations", "operation_tasks"],
+        env: [
+            {
+                name: "MCP_CONFIRMATION_SECRET",
+                required: false,
+                description: "Signs and verifies the confirmation tokens of confirmed tool calls (withConfirmation), at least 32 characters; required only by an app that confirms tool calls. Changing it voids the tokens in flight.",
+            },
+        ],
+        switches: [WRITES_ENABLED_SWITCH],
         routes: { ...DEFAULT_MCP_ACCESS_ROUTES },
         mount: [
             { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
@@ -58,7 +79,7 @@ export const mcpAccess = defineModule({
 });
 export { getAuthorizationHeader, getClaudeCodeCommand, getClaudeCodeLink, getDesktopConfig, getJsonConfig, getMcpClientSetup, } from "./client-setup.js";
 export { getTokenErrorMessage, mcpAccessMessages } from "./messages/index.js";
-export { MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, } from "./options.js";
+export { API_SCOPE_PATTERN, API_TOKEN_PREFIX_PATTERN, MAX_API_TOKEN_SCOPES, MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, GENERATED_AUTHORIZATION_SERVER_KEYS, GENERATED_PROTECTED_RESOURCE_KEYS, } from "./options.js";
 export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants } from "./schema.js";

package/dist/index.js.map

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

package/dist/jobs/index.d.ts

@@ -9,4 +9,6 @@ export declare const mcpAccessJobSchedules: {
         every: string;
     };
 };
+export { cancelOperation, getOperation, getOperationStatus, getPollAfterSeconds, MAX_OPERATION_DEDUP_KEY_LENGTH, OPERATION_CANCEL_TOOL_NAME, OPERATION_ORIGIN, OPERATION_STATUS_TOOL_NAME, OPERATION_STATUSES, registerOperationCancelTool, registerOperationStatusTool, startOperation, type GetOperationOptions, type OperationAnswer, type OperationCancelToolOptions, type OperationErrorCode, type OperationJob, type OperationPollOptions, type OperationStatus, type OperationStatusToolOptions, type ReadOperationResult, type StartOperationInput, } from "./operations.js";
+export { DEFAULT_TASK_TTL_SECONDS, getOperationTask, isTasksRequest, MAX_TASK_TTL_SECONDS, MIN_TASK_TTL_SECONDS, registerOperationTasks, TASKS_EXTENSION, type OperationTask, type OperationTaskRequest, type OperationTasksOptions, type OperationTaskStatus, } from "./operation-tasks.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAOA,wEAAwE;AACxE,eAAO,MAAM,oBAAoB;IAC/B,+EAA+E;;CAQ1D,CAAC;AAExB,gFAAgF;AAChF,eAAO,MAAM,qBAAqB;;;;CAEL,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAQA,wEAAwE;AACxE,eAAO,MAAM,oBAAoB;IAC/B,+EAA+E;;CAQ1D,CAAC;AAExB,gFAAgF;AAChF,eAAO,MAAM,qBAAqB;;;;CAEL,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,8BAA8B,EAC9B,0BAA0B,EAC1B,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/jobs/index.js

@@ -1,5 +1,6 @@
-// The jobs adapter of @softure-ai/mcp-access: its daily cleanup as a `@softure-ai/jobs` handler and schedule (an
-// optional peer dependency; only apps that import this entry need it).
+// The jobs adapter of @softure-ai/mcp-access: its daily cleanup as a `@softure-ai/jobs` handler and schedule, and long
+// operations as MCP tools (`startOperation`, `get_operation`, `cancel_operation`) or as MCP Tasks
+// (`registerOperationTasks`). Jobs is an optional peer dependency; only apps that import this entry need it.
 import { ok } from "@softure-ai/core";
 import { defineJobHandler } from "@softure-ai/jobs";
 import { z } from "zod";
@@ -19,4 +20,6 @@ export const mcpAccessJobHandlers = {
 export const mcpAccessJobSchedules = {
     "mcp-access.prune": { every: "1d" },
 };
+export { cancelOperation, getOperation, getOperationStatus, getPollAfterSeconds, MAX_OPERATION_DEDUP_KEY_LENGTH, OPERATION_CANCEL_TOOL_NAME, OPERATION_ORIGIN, OPERATION_STATUS_TOOL_NAME, OPERATION_STATUSES, registerOperationCancelTool, registerOperationStatusTool, startOperation, } from "./operations.js";
+export { DEFAULT_TASK_TTL_SECONDS, getOperationTask, isTasksRequest, MAX_TASK_TTL_SECONDS, MIN_TASK_TTL_SECONDS, registerOperationTasks, TASKS_EXTENSION, } from "./operation-tasks.js";
 //# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,uEAAuE;AACvE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAA4C,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+EAA+E;IAC/E,kBAAkB,EAAE,gBAAgB,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;YAC3B,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;KACF,CAAC;CACmB,CAAC;AAExB,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;CACR,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,kGAAkG;AAClG,6GAA6G;AAC7G,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAA4C,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+EAA+E;IAC/E,kBAAkB,EAAE,gBAAgB,CAAC;QACnC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;YAC3B,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO,EAAE,EAAE,CAAC;QACd,CAAC;KACF,CAAC;CACmB,CAAC;AAExB,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;CACR,CAAC;AAE9B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,8BAA8B,EAC9B,0BAA0B,EAC1B,gBAAgB,EAChB,0BAA0B,EAC1B,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,cAAc,GAWf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAKhB,MAAM,sBAAsB,CAAC"}

package/dist/jobs/operation-state.d.ts

@@ -0,0 +1,58 @@
+import { type Job, type JobProgress } from "@softure-ai/jobs";
+import { type JobsContext } from "@softure-ai/jobs/server";
+import type { McpServerIdentity } from "../contract.js";
+/** The origin of every operation's job: the jobs admin page and run log show where it came from. */
+export declare const OPERATION_ORIGIN = "mcp";
+export declare const OPERATION_STATUS_TOOL_NAME = "get_operation";
+export declare const OPERATION_CANCEL_TOOL_NAME = "cancel_operation";
+/** The longest dedup key an app may pass: the column holds 200 characters and the owner's prefix takes 42. */
+export declare const MAX_OPERATION_DEDUP_KEY_LENGTH = 150;
+export declare const OPERATION_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+/** An operation's status as the assistant reads it: a retrying job is `running`, since the operation has not ended. */
+export type OperationStatus = (typeof OPERATION_STATUSES)[number];
+export type OperationErrorCode = "mcp-access.operation_not_found" | "mcp-access.operation_finished";
+/** How often the assistant is told to ask again: between `minSeconds` (default 2) and `maxSeconds` (default 30). */
+export interface OperationPollOptions {
+    readonly minSeconds?: number;
+    readonly maxSeconds?: number;
+}
+/** The job behind an operation, as `readResult` receives it. */
+export interface OperationJob {
+    readonly id: string;
+    readonly queue: string;
+    readonly payload: unknown;
+    readonly finishedAt: Date | null;
+}
+/** The app's result of a succeeded operation (a URL, an id, counts), read from its own tables; never a secret. */
+export type ReadOperationResult = (job: OperationJob) => unknown;
+/** What `get_operation` answers. `pollAfterSeconds` only while the operation runs, `result` and `errorCode` once ended. */
+export interface OperationAnswer {
+    readonly operationId: string;
+    readonly status: OperationStatus;
+    /** The running attempt's progress (`context.reportProgress`): codes and counts only. */
+    readonly progress: JobProgress | null;
+    readonly pollAfterSeconds?: number;
+    /** True once someone asked a running operation to stop and it has not ended yet. */
+    readonly cancelRequested?: boolean;
+    readonly result?: unknown;
+    /** The failure's code (`lastError`), `jobs.cancelled` for a cancelled operation. */
+    readonly errorCode?: string;
+    /** What the assistant should do next, in a sentence. */
+    readonly message: string;
+}
+export interface GetOperationOptions {
+    readonly readResult?: ReadOperationResult;
+    readonly poll?: OperationPollOptions;
+    readonly statusToolName?: string;
+}
+/** The operation's status: a pending job that has used an attempt is waiting for a retry, so it is `running`. */
+export declare function getOperationStatus(job: Pick<Job, "status" | "attempts">): OperationStatus;
+/** Seconds until the next status call: a quarter of the operation's age, clamped to the poll bounds. */
+export declare function getPollAfterSeconds(ageSeconds: number, poll?: OperationPollOptions): number;
+export declare function describeOperation(ctx: JobsContext, job: Job, options: GetOperationOptions): Promise<OperationAnswer>;
+/** The job behind the caller's operation, or null: not a job, not an operation, or another account's. */
+export declare function findOwnedJob(ctx: JobsContext, identity: McpServerIdentity, operationId: string): Promise<Job | null>;
+export declare function getOwnerPrefix(userId: string): string;
+export declare function getPollMin(poll?: OperationPollOptions): number;
+export declare function fillToolName(text: string, toolName: string): string;
+//# sourceMappingURL=operation-state.d.ts.map

package/dist/jobs/operation-state.d.ts.map

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

package/dist/jobs/operation-state.js

@@ -0,0 +1,68 @@
+// The state of a long operation (#952) as both answers read it: the polling tools (`get_operation`) and MCP Tasks
+// (#977). An operation is a job of origin `mcp` whose dedup key starts with `mcp:<userId>:`.
+import { JOB_CANCELLED_CODE } from "@softure-ai/jobs";
+import { getJob } from "@softure-ai/jobs/server";
+import { getMcpAccessMessages } from "../server/options.js";
+/** The origin of every operation's job: the jobs admin page and run log show where it came from. */
+export const OPERATION_ORIGIN = "mcp";
+export const OPERATION_STATUS_TOOL_NAME = "get_operation";
+export const OPERATION_CANCEL_TOOL_NAME = "cancel_operation";
+/** The longest dedup key an app may pass: the column holds 200 characters and the owner's prefix takes 42. */
+export const MAX_OPERATION_DEDUP_KEY_LENGTH = 150;
+const DEFAULT_MIN_POLL_SECONDS = 2;
+const DEFAULT_MAX_POLL_SECONDS = 30;
+/** The wait grows with the operation's age: a quarter of the seconds since it started. */
+const POLL_AGE_FACTOR = 0.25;
+export const OPERATION_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled"];
+/** The operation's status: a pending job that has used an attempt is waiting for a retry, so it is `running`. */
+export function getOperationStatus(job) {
+    if (job.status === "pending")
+        return job.attempts === 0 ? "queued" : "running";
+    return job.status;
+}
+/** Seconds until the next status call: a quarter of the operation's age, clamped to the poll bounds. */
+export function getPollAfterSeconds(ageSeconds, poll = {}) {
+    const min = getPollMin(poll);
+    const max = Math.max(min, poll.maxSeconds ?? DEFAULT_MAX_POLL_SECONDS);
+    return Math.min(max, Math.max(min, Math.round(Math.max(0, ageSeconds) * POLL_AGE_FACTOR)));
+}
+export async function describeOperation(ctx, job, options) {
+    const messages = getMcpAccessMessages(ctx.config).operations;
+    const status = getOperationStatus(job);
+    const statusToolName = options.statusToolName ?? OPERATION_STATUS_TOOL_NAME;
+    const base = { operationId: job.id, status, progress: status === "running" ? job.progress : null };
+    if (status === "queued" || status === "running") {
+        const ageSeconds = (ctx.clock.now().getTime() - job.createdAt.getTime()) / 1000;
+        const cancelRequested = job.cancelRequestedAt !== null;
+        return {
+            ...base,
+            pollAfterSeconds: getPollAfterSeconds(ageSeconds, options.poll),
+            ...(cancelRequested ? { cancelRequested } : {}),
+            message: fillToolName(cancelRequested ? messages.cancelRequested : messages[status], statusToolName),
+        };
+    }
+    if (status === "succeeded") {
+        const result = options.readResult === undefined ? undefined : await options.readResult({ id: job.id, queue: job.queue, payload: job.payload, finishedAt: job.finishedAt });
+        return { ...base, ...(result === undefined ? {} : { result }), message: messages.succeeded };
+    }
+    if (status === "cancelled")
+        return { ...base, errorCode: JOB_CANCELLED_CODE, message: messages.cancelled };
+    return { ...base, ...(job.lastError === null ? {} : { errorCode: job.lastError }), message: messages.failed };
+}
+/** The job behind the caller's operation, or null: not a job, not an operation, or another account's. */
+export async function findOwnedJob(ctx, identity, operationId) {
+    const job = await getJob(ctx, operationId);
+    if (job === null || job.origin !== OPERATION_ORIGIN || job.dedupKey?.startsWith(getOwnerPrefix(identity.userId)) !== true)
+        return null;
+    return job;
+}
+export function getOwnerPrefix(userId) {
+    return `${OPERATION_ORIGIN}:${userId}:`;
+}
+export function getPollMin(poll = {}) {
+    return poll.minSeconds ?? DEFAULT_MIN_POLL_SECONDS;
+}
+export function fillToolName(text, toolName) {
+    return text.replaceAll("{tool}", toolName);
+}
+//# sourceMappingURL=operation-state.js.map

package/dist/jobs/operation-state.js.map

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

package/dist/jobs/operation-tasks.d.ts

@@ -0,0 +1,61 @@
+import { type CallToolResult, type McpServer } from "@modelcontextprotocol/server";
+import { type JobsContext } from "@softure-ai/jobs/server";
+import type { McpServerIdentity } from "../contract.js";
+import { type OperationPollOptions, type ReadOperationResult } from "./operation-state.js";
+/** The extension's identifier, in the client's per-request capabilities and the server's `capabilities.extensions`. */
+export declare const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+export declare const DEFAULT_TASK_TTL_SECONDS = 86400;
+export declare const MIN_TASK_TTL_SECONDS = 60;
+/** Thirty days: a task outlives its operation only so long. */
+export declare const MAX_TASK_TTL_SECONDS = 2592000;
+/** The tool handler's request context (its second argument): only its per-request `_meta` envelope is read. */
+export interface OperationTaskRequest {
+    readonly mcpReq: {
+        readonly envelope?: object;
+    };
+}
+/** A task's status as the extension defines it; operations never ask for input, nor fail at the protocol level. */
+export type OperationTaskStatus = "working" | "completed" | "cancelled";
+/** A task as `tasks/get` answers it. `result` once completed: the `get_operation` answer, `isError` when it failed. */
+export interface OperationTask {
+    readonly taskId: string;
+    readonly status: OperationTaskStatus;
+    readonly statusMessage?: string;
+    /** ISO 8601. */
+    readonly createdAt: string;
+    /** ISO 8601: the job's last change. */
+    readonly lastUpdatedAt: string;
+    readonly ttlMs: number;
+    /** Only while working: the operation's wait (`pollAfterSeconds`) in milliseconds. */
+    readonly pollIntervalMs?: number;
+    readonly result?: CallToolResult;
+}
+export interface OperationTasksOptions {
+    /** `{ db, clock, config }` of the request. */
+    readonly ctx: JobsContext;
+    /** The request's identity: a task is found only for its owner, and only a writer may cancel it. */
+    readonly identity: McpServerIdentity;
+    readonly readResult?: ReadOperationResult;
+    readonly poll?: OperationPollOptions;
+}
+export interface AnswerOperationTaskInput {
+    readonly jobId: string;
+    readonly ttlSeconds?: number;
+    readonly poll?: OperationPollOptions;
+}
+/** True when the request's client declared the Tasks extension in its per-request capabilities (revision 2026-07-28). */
+export declare function isTasksRequest(request: OperationTaskRequest): boolean;
+export declare function isTaskTtlValid(seconds: number): boolean;
+/**
+ * The tool's answer as a task (`resultType: "task"`) for the operation's job: stores the task before answering, as the
+ * spec requires, and gives the same account the same task id for the same job.
+ */
+export declare function answerOperationTask(ctx: JobsContext, identity: McpServerIdentity, input: AnswerOperationTaskInput): Promise<CallToolResult>;
+/** The caller's task with its operation's state now; `null` when unknown, another account's, or its job is gone. */
+export declare function getOperationTask(ctx: JobsContext, identity: McpServerIdentity, taskId: string, options?: Pick<OperationTasksOptions, "readResult" | "poll">): Promise<OperationTask | "expired" | null>;
+/**
+ * Serves the Tasks extension on the app's server: declares the capability and answers `tasks/get`, `tasks/update` and
+ * `tasks/cancel` for the request's account. Register it on every server whose tools pass `taskRequest`.
+ */
+export declare function registerOperationTasks(server: McpServer, options: OperationTasksOptions): void;
+//# sourceMappingURL=operation-tasks.d.ts.map

package/dist/jobs/operation-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-tasks.d.ts","sourceRoot":"","sources":["../../src/jobs/operation-tasks.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,uHAAuH;AACvH,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAQ9C,+GAA+G;AAC/G,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED,mHAAmH;AACnH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAExE,uHAAuH;AACvH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAQD,yHAAyH;AACzH,wBAAgB,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAIrE;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQjJ;AAED,oHAAoH;AACpH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,GAAG,MAAM,CAAM,GAC/D,OAAO,CAAC,aAAa,GAAG,SAAS,GAAG,IAAI,CAAC,CAI3C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CA2B9F"}