@absolutejs/mcp 0.4.2 → 0.5.0

package/README.md

@@ -7,6 +7,49 @@ package owns the JSON-RPC protocol, protocol-version negotiation, RFC 9728
 discovery metadata, and the `401` challenge that lets a client find your
 authorization server.
 
+## Agent action enforcement
+
+Tools carrying manifest contract 2 `authorization` metadata fail closed unless
+an `agency` enforcement point is configured. Every call becomes an exact-input
+action request; allowed calls execute through a short-lived single-use lease and
+produce a receipt. Requestable denials return an `absolute.action_decision`
+payload containing the action id for an approval workflow.
+
+```ts
+import { createAgency, createMemoryAgencyStore } from "@absolutejs/agency";
+
+const agency = createAgency({ policy, store: createMemoryAgencyStore() });
+
+mcpServer<Caller>({
+  agency: {
+    enforcement: agency,
+    resolveActor: ({ caller, scopes }) => ({
+      agentId: caller.agentId,
+      delegationId: caller.delegationId,
+      scopes,
+      userId: caller.userId,
+    }),
+  },
+  // normal MCP config…
+});
+```
+
+## Durable Tasks
+
+The package implements the final `io.modelcontextprotocol/tasks` extension from
+SEP-2663: server-directed task creation, `tasks/get`, `tasks/update`, and
+`tasks/cancel`. There is intentionally no `tasks/list`; task handles are bound
+to an authorization key and checked on every request.
+
+```ts
+tasks: {
+  authorizationKey: (caller) => caller.userId,
+  shouldCreate: ({ name }) => name === "long_running_report",
+  store: createMemoryMcpTaskStore(), // use a durable shared store in production
+  ttlMs: 60 * 60 * 1000,
+}
+```
+
 Nothing here depends on a model. The tool shape is structurally compatible with
 [`@absolutejs/ai`](https://github.com/absolutejs/ai)'s `AIToolMap`, so an AI tool
 registry serves over MCP without conversion — but any typed tool registry works.

package/dist/index.js

@@ -1,4 +1,19 @@
 // @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
 // src/guards.ts
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -270,12 +285,32 @@ var createMcpClient = (options) => {
   };
   return { callTool, initialize, listResources, listTools, ping, readResource };
 };
+// node_modules/@absolutejs/agency/dist/authzen.js
+var createCoazActionInput = ({
+  actor,
+  call,
+  effects = ["read"],
+  requiredScopes = []
+}) => ({
+  action: "call_tool",
+  actor,
+  context: { required_scopes: requiredScopes, source: "mcp" },
+  effects,
+  input: call.arguments,
+  resource: {
+    id: call.name,
+    properties: { server_id: call.serverId },
+    type: "mcp_tool"
+  }
+});
+
 // src/jsonrpc.ts
 var JSONRPC_PARSE_ERROR = -32700;
 var JSONRPC_INVALID_REQUEST = -32600;
 var JSONRPC_METHOD_NOT_FOUND = -32601;
 var JSONRPC_INVALID_PARAMS = -32602;
 var JSONRPC_INTERNAL_ERROR = -32603;
+var JSONRPC_MISSING_REQUIRED_CLIENT_CAPABILITY = -32003;
 var HTTP_ACCEPTED = 202;
 var HTTP_NO_CONTENT = 204;
 var HTTP_UNAUTHORIZED = 401;
@@ -286,7 +321,11 @@ var jsonHeaders = {
 var rpcResult = (id, result) => new Response(JSON.stringify({ id, jsonrpc: "2.0", result }), {
   headers: jsonHeaders
 });
-var rpcError = (id, code, message) => new Response(JSON.stringify({ error: { code, message }, id, jsonrpc: "2.0" }), {
+var rpcError = (id, code, message, data) => new Response(JSON.stringify({
+  error: { code, message, ...data === undefined ? {} : { data } },
+  id,
+  jsonrpc: "2.0"
+}), {
   headers: jsonHeaders
 });
 var notificationAck = () => new Response(null, { status: HTTP_ACCEPTED });
@@ -302,6 +341,49 @@ var unauthorized = (metadataUrl, detail) => new Response(JSON.stringify({
   status: HTTP_UNAUTHORIZED
 });
 
+// src/tasks.ts
+var clone = (value) => structuredClone(value);
+var createMemoryMcpTaskStore = () => {
+  const tasks = new Map;
+  return {
+    cancel: (taskId) => {
+      const task = tasks.get(taskId);
+      if (task === undefined)
+        return;
+      tasks.set(taskId, {
+        ...task,
+        lastUpdatedAt: new Date().toISOString(),
+        status: "cancelled"
+      });
+    },
+    get: (taskId) => {
+      const task = tasks.get(taskId);
+      return task === undefined ? null : clone(task);
+    },
+    save: (task) => {
+      tasks.set(task.taskId, clone(task));
+    },
+    update: (taskId, update) => {
+      const task = tasks.get(taskId);
+      if (task === undefined)
+        return null;
+      if (["cancelled", "completed", "failed"].includes(task.status)) {
+        return clone(task);
+      }
+      const next = {
+        ...task,
+        ...update,
+        lastUpdatedAt: new Date().toISOString()
+      };
+      tasks.set(taskId, next);
+      return clone(next);
+    }
+  };
+};
+var publicMcpTask = ({ authorizationKey, ...task }) => {
+  return task;
+};
+
 // src/dispatch.ts
 var DEFAULT_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var DEFAULT_RESOURCE_MIME = "text/markdown";
@@ -332,6 +414,16 @@ var negotiateProtocol = (supported, params) => {
   return supported.includes(requested) ? requested : preferred;
 };
 var scopeAllows = (tool, scopes) => tool.scope === undefined || scopes.includes(tool.scope);
+var valueAtPath = (value, path) => {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (!isRecord(current))
+      return;
+    current = current[segment];
+  }
+  return current;
+};
+var agencyAllows = (config, tool, scopes) => tool.authorization === undefined || config.agency !== undefined && (tool.authorization.requiredScopes ?? []).every((scope) => scopes.includes(scope));
 var normalizeResult = (value) => {
   if (typeof value === "string") {
     return { content: [{ text: value, type: "text" }], isError: false };
@@ -350,6 +442,9 @@ var initialize = async (config, id, params, context) => {
   const capabilities = {
     tools: { listChanged: false }
   };
+  if (config.tasks !== undefined) {
+    capabilities.extensions = { "io.modelcontextprotocol/tasks": {} };
+  }
   if (config.prompts)
     capabilities.prompts = { listChanged: false };
   if (config.resources) {
@@ -369,7 +464,7 @@ var initialize = async (config, id, params, context) => {
 };
 var toolsList = async (config, caller, scopes, id, params) => {
   const tools = await config.tools({ caller, meta: {} });
-  const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes)).map(([name, tool]) => ({
+  const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes) && agencyAllows(config, tool, scopes)).map(([name, tool]) => ({
     annotations: tool.annotations,
     description: tool.description,
     inputSchema: tool.inputSchema,
@@ -396,11 +491,70 @@ var SSE_HEADERS = {
 var sseFrame = (message) => `data: ${JSON.stringify(message)}
 
 `;
-var runTool = async (config, caller, id, name, args, meta, tool, context) => {
+var runTool = async (config, caller, scopes, id, name, args, meta, tool, context) => {
   let ok = false;
   let payload;
   try {
-    const result = normalizeResult(await tool.handler(args, context));
+    const invoke = async () => normalizeResult(await tool.handler(args, context));
+    let result;
+    if (tool.authorization === undefined) {
+      result = await invoke();
+    } else {
+      const agency = config.agency;
+      if (agency === undefined)
+        throw new Error("Agent action policy is not configured");
+      const actor = await agency.resolveActor({ caller, scopes });
+      const actionInput = createCoazActionInput({
+        actor,
+        call: {
+          arguments: args,
+          name,
+          serverId: agency.serverId ?? config.serverInfo.name
+        },
+        effects: tool.authorization.effects,
+        requiredScopes: tool.authorization.requiredScopes
+      });
+      const amount = tool.authorization.spend ? valueAtPath(args, tool.authorization.spend.amountMinorField) : undefined;
+      const currency = tool.authorization.spend ? valueAtPath(args, tool.authorization.spend.currencyField) : undefined;
+      const idempotencyKey = tool.authorization.idempotencyKeyField ? valueAtPath(args, tool.authorization.idempotencyKeyField) : undefined;
+      const requested = await agency.enforcement.request({
+        ...actionInput,
+        context: {
+          ...actionInput.context,
+          manifest_authorization: tool.authorization
+        },
+        idempotencyKey: typeof idempotencyKey === "string" ? idempotencyKey : undefined,
+        spend: typeof amount === "number" && typeof currency === "string" ? { amountMinor: amount, currency } : undefined
+      });
+      meta.agencyActionId = requested.action.actionId;
+      meta.agencyDecisionId = requested.decision.decisionId;
+      if (requested.decision.kind === "deny") {
+        result = {
+          content: [
+            {
+              text: requested.decision.requestable ? `Action requires approval (${requested.action.actionId})` : `Action denied: ${requested.decision.reason}`,
+              type: "text"
+            }
+          ],
+          isError: true,
+          structuredContent: {
+            actionId: requested.action.actionId,
+            decision: requested.decision,
+            type: "absolute.action_decision"
+          }
+        };
+      } else {
+        const lease = await agency.enforcement.issueLease(requested.action.actionId);
+        const executed = await agency.enforcement.execute({
+          executor: `mcp:${config.serverInfo.name}/${name}`,
+          leaseId: lease.leaseId,
+          run: invoke
+        });
+        meta.agencyLeaseId = lease.leaseId;
+        meta.agencyReceiptId = executed.receipt.receiptId;
+        result = executed.result;
+      }
+    }
     ok = result.isError !== true;
     payload = { id, jsonrpc: "2.0", result };
   } catch (error) {
@@ -418,7 +572,7 @@ var runTool = async (config, caller, id, name, args, meta, tool, context) => {
     await config.onCall({ args, caller, meta, name, ok });
   return payload;
 };
-var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions, canElicit) => {
+var toolsCallStreaming = (config, caller, scopes, id, name, args, meta, tool, sessions, canElicit) => {
   const encoder = new TextEncoder;
   const body = new ReadableStream({
     async start(controller) {
@@ -447,7 +601,7 @@ var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions,
           return await pending.answer;
         }
       };
-      const payload = await runTool(config, caller, id, name, args, meta, tool, context);
+      const payload = await runTool(config, caller, scopes, id, name, args, meta, tool, context);
       send(payload);
       if (open) {
         try {
@@ -474,19 +628,101 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
   }
   const tools = await config.tools({ caller, meta });
   const tool = tools[name];
-  if (!tool || !scopeAllows(tool, scopes)) {
+  if (!tool || !scopeAllows(tool, scopes) || !agencyAllows(config, tool, scopes)) {
     return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${name}`);
   }
+  const tasks = config.tasks;
+  if (tasks !== undefined && await tasks.shouldCreate({ args, caller, name })) {
+    if (!supportsTasks(params)) {
+      return rpcError(id, JSONRPC_MISSING_REQUIRED_CLIENT_CAPABILITY, "Missing required client capability", {
+        requiredCapabilities: {
+          extensions: { "io.modelcontextprotocol/tasks": {} }
+        }
+      });
+    }
+    const createdAt = new Date().toISOString();
+    const task = {
+      authorizationKey: await tasks.authorizationKey(caller),
+      createdAt,
+      lastUpdatedAt: createdAt,
+      pollIntervalMs: tasks.pollIntervalMs,
+      status: "working",
+      taskId: crypto.randomUUID(),
+      ttlMs: tasks.ttlMs ?? null
+    };
+    await tasks.store.save(task);
+    setTimeout(() => {
+      runTool(config, caller, scopes, id, name, args, meta, tool, noElicit).then(async (payload2) => {
+        const result = isRecord(payload2) && isRecord(payload2.result) ? payload2.result : { content: [], isError: true };
+        await tasks.store.update(task.taskId, {
+          result,
+          status: "completed"
+        });
+      }).catch(async (error) => {
+        await tasks.store.update(task.taskId, {
+          error: {
+            code: JSONRPC_INTERNAL_ERROR,
+            message: error instanceof Error ? error.message : "Task failed"
+          },
+          status: "failed"
+        });
+      });
+    }, 0);
+    return rpcResult(id, { ...publicMcpTask(task), resultType: "task" });
+  }
   const sessions = context.sessions;
   const session = sessions ? await sessions.get(context.sessionId ?? null) : null;
   if (tool.mayElicit === true && config.elicitation?.enabled === true && sessions && session) {
-    return toolsCallStreaming(config, caller, id, name, args, meta, tool, sessions, session.canElicit);
+    return toolsCallStreaming(config, caller, scopes, id, name, args, meta, tool, sessions, session.canElicit);
   }
-  const payload = await runTool(config, caller, id, name, args, meta, tool, noElicit);
+  const payload = await runTool(config, caller, scopes, id, name, args, meta, tool, noElicit);
   return new Response(JSON.stringify(payload), {
     headers: { "content-type": "application/json" }
   });
 };
+var supportsTasks = (params) => {
+  if (!isRecord(params) || !isRecord(params._meta))
+    return false;
+  const capabilities = params._meta["io.modelcontextprotocol/clientCapabilities"];
+  if (!isRecord(capabilities) || !isRecord(capabilities.extensions))
+    return false;
+  return isRecord(capabilities.extensions["io.modelcontextprotocol/tasks"]);
+};
+var authorizedTask = async (config, caller, params) => {
+  if (config.tasks === undefined || !isRecord(params) || typeof params.taskId !== "string") {
+    return null;
+  }
+  const task = await config.tasks.store.get(params.taskId);
+  if (task === null)
+    return null;
+  const authorizationKey = await config.tasks.authorizationKey(caller);
+  return task.authorizationKey === authorizationKey ? task : null;
+};
+var tasksGet = async (config, caller, id, params) => {
+  const task = await authorizedTask(config, caller, params);
+  if (task === null)
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
+  return rpcResult(id, { ...publicMcpTask(task), resultType: "complete" });
+};
+var tasksUpdate = async (config, caller, id, params) => {
+  const task = await authorizedTask(config, caller, params);
+  if (task === null || !isRecord(params) || !isRecord(params.inputResponses)) {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task or invalid inputResponses");
+  }
+  await config.tasks?.onUpdate?.({
+    caller,
+    inputResponses: params.inputResponses,
+    task
+  });
+  return rpcResult(id, { resultType: "complete" });
+};
+var tasksCancel = async (config, caller, id, params) => {
+  const task = await authorizedTask(config, caller, params);
+  if (task === null)
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "Unknown task");
+  await config.tasks?.store.cancel(task.taskId);
+  return rpcResult(id, { resultType: "complete" });
+};
 var promptsList = (config, id, params) => {
   const definitions = config.prompts?.definitions ?? {};
   const all = Object.entries(definitions).map(([name, def]) => ({
@@ -578,6 +814,14 @@ var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   if (method === "initialize") {
     return await initialize(config, id, params, context);
   }
+  if (method === "server/discover") {
+    return rpcResult(id, {
+      capabilities: {
+        extensions: config.tasks === undefined ? {} : { "io.modelcontextprotocol/tasks": {} }
+      },
+      serverInfo: config.serverInfo
+    });
+  }
   if (method === "ping")
     return rpcResult(id, {});
   if (method === "tools/list") {
@@ -586,6 +830,12 @@ var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   if (method === "tools/call") {
     return toolsCall(config, caller, scopes, id, params, context);
   }
+  if (method === "tasks/get")
+    return tasksGet(config, caller, id, params);
+  if (method === "tasks/update")
+    return tasksUpdate(config, caller, id, params);
+  if (method === "tasks/cancel")
+    return tasksCancel(config, caller, id, params);
   if (method === "prompts/list")
     return promptsList(config, id, params);
   if (method === "prompts/get")
@@ -881,12 +1131,14 @@ var mcpServer = (config) => {
 };
 export {
   verifyBearer,
+  publicMcpTask,
   protectedResourceMetadata,
   metadataPathFor,
   mcpServer,
   feedbackTools,
   dispatchMcp,
   createSessionRegistry,
+  createMemoryMcpTaskStore,
   createMcpHandler,
   createMcpClient,
   McpClientError,