@softure-ai/mcp-access 0.2.9 → 0.3.0

package/src/index.ts

@@ -34,6 +34,16 @@ export const MCP_RATE_LIMIT_BUCKETS = {
   "mcp-oauth": { limit: 60, windowMinutes: 15, key: "ip" },
 } as const satisfies Readonly<Record<string, RateLimitBucketInput>>;
 
+/**
+ * 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" },
+} as const satisfies Readonly<Record<string, RateLimitBucketInput>>;
+
 /**
  * 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." } }] })`.
@@ -41,11 +51,17 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.2.9",
+    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: [],
+    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: [
@@ -78,8 +94,14 @@ export {
   type McpClientSetupInput,
 } from "./client-setup.js";
 export type {
+  AccessTokenKind,
   AccessTokenStatus,
   AccessTokenView,
+  ApiTokenErrorCode,
+  ApiTokenExample,
+  ApiTokenIdentity,
+  ApiTokenRefusal,
+  IssuedApiTokenView,
   IssuedToken,
   IssueTokenFormState,
   McpAccessErrorCode,
@@ -94,12 +116,18 @@ export type {
 } from "./contract.js";
 export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.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,

package/src/jobs/index.ts

@@ -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, type JobHandlers, type JobSchedulesInput } from "@softure-ai/jobs";
 import { z } from "zod";
@@ -21,3 +22,41 @@ export const mcpAccessJobHandlers = {
 export const mcpAccessJobSchedules = {
   "mcp-access.prune": { every: "1d" },
 } satisfies JobSchedulesInput;
+
+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";

package/src/jobs/operation-state.ts

@@ -0,0 +1,119 @@
+// 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, type Job, type JobProgress } from "@softure-ai/jobs";
+import { getJob, type JobsContext } from "@softure-ai/jobs/server";
+import type { McpServerIdentity } from "../contract.js";
+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"] as const;
+
+/** 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 function getOperationStatus(job: Pick<Job, "status" | "attempts">): OperationStatus {
+  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: number, poll: OperationPollOptions = {}): number {
+  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: JobsContext, job: Job, options: GetOperationOptions): Promise<OperationAnswer> {
+  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: JobsContext, identity: McpServerIdentity, operationId: string): Promise<Job | null> {
+  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: string): string {
+  return `${OPERATION_ORIGIN}:${userId}:`;
+}
+
+export function getPollMin(poll: OperationPollOptions = {}): number {
+  return poll.minSeconds ?? DEFAULT_MIN_POLL_SECONDS;
+}
+
+export function fillToolName(text: string, toolName: string): string {
+  return text.replaceAll("{tool}", toolName);
+}

package/src/jobs/operation-tasks.ts

@@ -0,0 +1,229 @@
+// Long operations as MCP Tasks (#977): the Tasks extension `io.modelcontextprotocol/tasks` of protocol revision
+// 2026-07-28. A client that declares the extension on a tool call gets a task instead of an operation id and follows it
+// through `tasks/get`; every other client keeps the polling tools (`get_operation`, `cancel_operation`) of #952.
+//
+//   registerOperationTasks(server, { ctx, identity, readResult: (job) => findRenderUrl(job.id) });
+//   server.registerTool("render_video", { inputSchema }, (args, request) =>
+//     startOperation(ctx, identity, { queue: "video.render", payload: args, taskRequest: request }));
+//
+// A task id is random (the spec requires ids nobody can guess) and lives in `mcp.operation_tasks` with its owner, the
+// operation's job and an expiry. Every task request checks the owner too, and reads the job's state as it is now.
+import { randomBytes } from "node:crypto";
+import {
+  CLIENT_CAPABILITIES_META_KEY,
+  MissingRequiredClientCapabilityError,
+  ProtocolError,
+  ProtocolErrorCode,
+  type CallToolResult,
+  type McpServer,
+} from "@modelcontextprotocol/server";
+import type { Job } from "@softure-ai/jobs";
+import { requestJobCancel, type JobsContext } from "@softure-ai/jobs/server";
+import { and, eq, sql } from "drizzle-orm";
+import { z } from "zod";
+import type { McpServerIdentity } from "../contract.js";
+import { operationTasks } from "../schema.js";
+import { getMcpAccessMessages } from "../server/options.js";
+import { toolResult } from "../server/tools.js";
+import {
+  describeOperation,
+  findOwnedJob,
+  getOperationStatus,
+  getPollAfterSeconds,
+  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 const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+export const DEFAULT_TASK_TTL_SECONDS = 86_400;
+export const MIN_TASK_TTL_SECONDS = 60;
+/** Thirty days: a task outlives its operation only so long. */
+export const MAX_TASK_TTL_SECONDS = 2_592_000;
+
+const TASK_ID_BYTES = 32;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TASK_NOT_FOUND = "Failed to retrieve task: Task not found";
+const TASK_EXPIRED = "Failed to retrieve task: Task has expired";
+const CANCEL_NEEDS_WRITE = "Cancelling a task needs a token with write access";
+
+/** 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;
+}
+
+type TaskRow = typeof operationTasks.$inferSelect;
+
+const taskIdParams = z.looseObject({ taskId: z.string() });
+const taskResult = z.looseObject({});
+const clientCapabilities = z.looseObject({ extensions: z.record(z.string(), z.unknown()).optional() });
+
+/** True when the request's client declared the Tasks extension in its per-request capabilities (revision 2026-07-28). */
+export function isTasksRequest(request: OperationTaskRequest): boolean {
+  const envelope: Partial<Record<string, unknown>> = { ...request.mcpReq.envelope };
+  const capabilities = clientCapabilities.safeParse(envelope[CLIENT_CAPABILITIES_META_KEY]);
+  return capabilities.success && capabilities.data.extensions?.[TASKS_EXTENSION] !== undefined;
+}
+
+export function isTaskTtlValid(seconds: number): boolean {
+  return Number.isInteger(seconds) && seconds >= MIN_TASK_TTL_SECONDS && seconds <= MAX_TASK_TTL_SECONDS;
+}
+
+/**
+ * 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 async function answerOperationTask(ctx: JobsContext, identity: McpServerIdentity, input: AnswerOperationTaskInput): Promise<CallToolResult> {
+  const row = await storeTask(ctx, identity, input);
+  const job = await findOwnedJob(ctx, identity, input.jobId);
+  if (job === null) throw new Error(`answerOperationTask: job ${input.jobId} is not an operation of this account`);
+  const task = await describeTask(ctx, row, job, input.poll === undefined ? {} : { poll: input.poll });
+  // On revision 2026-07-28 the SDK passes a tool's own `resultType` through; its `CallToolResult` type does not know
+  // the extension's task shape, and the `content` it would add anyway is ignored by clients.
+  return { content: [], ...task, resultType: "task" };
+}
+
+/** The caller's task with its operation's state now; `null` when unknown, another account's, or its job is gone. */
+export async function getOperationTask(
+  ctx: JobsContext,
+  identity: McpServerIdentity,
+  taskId: string,
+  options: Pick<OperationTasksOptions, "readResult" | "poll"> = {},
+): Promise<OperationTask | "expired" | null> {
+  const found = await findTask(ctx, identity, taskId);
+  if (found === null || found === "expired") return found;
+  return describeTask(ctx, found.row, found.job, options);
+}
+
+/**
+ * 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 function registerOperationTasks(server: McpServer, options: OperationTasksOptions): void {
+  const { ctx, identity } = options;
+  const describeOptions = { ...(options.readResult === undefined ? {} : { readResult: options.readResult }), ...(options.poll === undefined ? {} : { poll: options.poll }) };
+  server.server.registerCapabilities({ extensions: { [TASKS_EXTENSION]: {} } });
+
+  server.server.setRequestHandler("tasks/get", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+    requireTasksCapability(request);
+    return { ...(await requireTask(ctx, identity, taskId, describeOptions)) };
+  });
+
+  // Operations never ask for input, so there is nothing to update; an owned task is acknowledged, as the spec asks.
+  server.server.setRequestHandler("tasks/update", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+    requireTasksCapability(request);
+    await requireTask(ctx, identity, taskId, describeOptions);
+    return {};
+  });
+
+  server.server.setRequestHandler("tasks/cancel", { params: taskIdParams, result: taskResult }, async ({ taskId }, request) => {
+    requireTasksCapability(request);
+    const found = await findTask(ctx, identity, taskId);
+    if (found === null) throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_NOT_FOUND);
+    if (found === "expired") throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_EXPIRED);
+    if (!identity.canWrite) throw new ProtocolError(ProtocolErrorCode.InvalidRequest, CANCEL_NEEDS_WRITE);
+    // Cancelling is cooperative: an operation that has already ended is acknowledged all the same.
+    await requestJobCancel(ctx, found.job.id);
+    return {};
+  });
+}
+
+async function storeTask(ctx: JobsContext, identity: McpServerIdentity, input: AnswerOperationTaskInput): Promise<TaskRow> {
+  const now = ctx.clock.now();
+  const expiresAt = new Date(now.getTime() + (input.ttlSeconds ?? DEFAULT_TASK_TTL_SECONDS) * 1000);
+  // One task per account and job: joining a running operation answers its task again, kept alive at least as long.
+  const [row] = await ctx.db
+    .insert(operationTasks)
+    .values({ taskId: randomBytes(TASK_ID_BYTES).toString("base64url"), userId: identity.userId, jobId: BigInt(input.jobId), createdAt: now, expiresAt })
+    .onConflictDoUpdate({
+      target: [operationTasks.userId, operationTasks.jobId],
+      set: { expiresAt: sql`greatest(${operationTasks.expiresAt}, excluded.expires_at)` },
+    })
+    .returning();
+  if (row === undefined) throw new Error(`answerOperationTask: no task row for job ${input.jobId}`);
+  return row;
+}
+
+async function findTask(ctx: JobsContext, identity: McpServerIdentity, taskId: string): Promise<{ readonly row: TaskRow; readonly job: Job } | "expired" | null> {
+  if (!UUID.test(identity.userId)) return null;
+  const [row] = await ctx.db
+    .select()
+    .from(operationTasks)
+    .where(and(eq(operationTasks.taskId, taskId), eq(operationTasks.userId, identity.userId)))
+    .limit(1);
+  if (row === undefined) return null;
+  if (row.expiresAt.getTime() <= ctx.clock.now().getTime()) return "expired";
+  const job = await findOwnedJob(ctx, identity, row.jobId.toString());
+  return job === null ? null : { row, job };
+}
+
+async function requireTask(
+  ctx: JobsContext,
+  identity: McpServerIdentity,
+  taskId: string,
+  options: Pick<OperationTasksOptions, "readResult" | "poll">,
+): Promise<OperationTask> {
+  const task = await getOperationTask(ctx, identity, taskId, options);
+  if (task === null) throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_NOT_FOUND);
+  if (task === "expired") throw new ProtocolError(ProtocolErrorCode.InvalidParams, TASK_EXPIRED);
+  return task;
+}
+
+/** The spec's rule for `tasks/*`: a client that did not declare the extension on this request gets `-32021`. */
+function requireTasksCapability(request: OperationTaskRequest): void {
+  if (!isTasksRequest(request)) throw new MissingRequiredClientCapabilityError({ requiredCapabilities: { extensions: { [TASKS_EXTENSION]: {} } } });
+}
+
+async function describeTask(ctx: JobsContext, row: TaskRow, job: Job, options: Pick<OperationTasksOptions, "readResult" | "poll">): Promise<OperationTask> {
+  const messages = getMcpAccessMessages(ctx.config).operations;
+  const status = getOperationStatus(job);
+  const base = {
+    taskId: row.taskId,
+    createdAt: row.createdAt.toISOString(),
+    lastUpdatedAt: job.updatedAt.toISOString(),
+    ttlMs: row.expiresAt.getTime() - row.createdAt.getTime(),
+  };
+  if (status === "queued" || status === "running") {
+    const ageSeconds = (ctx.clock.now().getTime() - job.createdAt.getTime()) / 1000;
+    const statusMessage = job.cancelRequestedAt !== null ? messages.taskCancelRequested : status === "queued" ? messages.taskQueued : messages.taskRunning;
+    return { ...base, status: "working", statusMessage, pollIntervalMs: getPollAfterSeconds(ageSeconds, options.poll) * 1000 };
+  }
+  if (status === "cancelled") return { ...base, status: "cancelled", statusMessage: messages.cancelled };
+  // A failed job is a tool-level failure, not a JSON-RPC error: the spec makes it `completed` with `isError`.
+  const answer = await describeOperation(ctx, job, options);
+  const result = status === "failed" ? { ...toolResult(answer), isError: true } : toolResult(answer);
+  return { ...base, status: "completed", statusMessage: answer.message, result };
+}