@absolutejs/mcp 0.4.2 → 0.5.0

package/dist/manifest.json

@@ -0,0 +1,124 @@
+{
+	"contract": 2,
+	"identity": {
+		"accent": "#0ea5e9",
+		"category": "ai",
+		"description": "Serve a remote Model Context Protocol endpoint with OAuth discovery, agency action enforcement, approval receipts, and caller-bound durable Tasks. Bridge installed AbsoluteJS packages' manifests with `toMcpToolRegistry` and enforce their declared effects before execution.",
+		"docsUrl": "https://github.com/absolutejs/mcp",
+		"name": "@absolutejs/mcp",
+		"tagline": "Let AI assistants connect to your site and use its tools."
+	},
+	"requires": {
+		"peers": [
+			{
+				"name": "elysia",
+				"range": ">=1.1.0",
+				"reason": "plugin host"
+			}
+		]
+	},
+	"settings": {
+		"type": "object",
+		"required": [
+			"issuer",
+			"path"
+		],
+		"properties": {
+			"instructions": {
+				"description": "A short note shown to the AI about what this server does and how to use it.",
+				"title": "Instructions for the AI",
+				"type": "string"
+			},
+			"issuer": {
+				"description": "The web address of the sign-in server that issues access tokens for this endpoint. Usually your site's own address.",
+				"examples": [
+					"https://yoursite.com"
+				],
+				"format": "uri",
+				"title": "Token issuer",
+				"type": "string"
+			},
+			"path": {
+				"default": "/mcp",
+				"description": "Where on your site the AI endpoint lives.",
+				"title": "Endpoint path",
+				"type": "string"
+			},
+			"scopesSupported": {
+				"description": "The permission scopes this endpoint advertises to connecting clients.",
+				"examples": [
+					[
+						"openid",
+						"mcp"
+					]
+				],
+				"title": "Advertised scopes",
+				"x-group": "advanced",
+				"type": "array",
+				"items": {
+					"type": "string"
+				}
+			},
+			"serveRootMetadata": {
+				"description": "Also answer discovery requests at the site root. Turn on for exactly one endpoint per site.",
+				"title": "Answer root discovery",
+				"x-group": "advanced",
+				"type": "boolean"
+			},
+			"serverInfo": {
+				"description": "How this server introduces itself to connecting AI clients.",
+				"title": "Server identity",
+				"type": "object",
+				"properties": {
+					"name": {
+						"title": "Machine name",
+						"examples": [
+							"your-site"
+						],
+						"type": "string"
+					},
+					"title": {
+						"title": "Display name",
+						"examples": [
+							"Your Site"
+						],
+						"type": "string"
+					},
+					"version": {
+						"title": "Version",
+						"examples": [
+							"1.0.0"
+						],
+						"type": "string"
+					}
+				}
+			}
+		}
+	},
+	"wiring": [
+		{
+			"description": "Mount a remote MCP endpoint that serves the tools of installed AbsoluteJS packages — bridge each package's manifest and any MCP client (Claude, etc.) can call them.",
+			"id": "default",
+			"server": {
+				"code": ".use(\n\tmcpServer({\n\t\t// TODO: decide who may call this endpoint — see verifyBearer for\n\t\t// the standard OAuth bearer-token checks. Denies everyone until\n\t\t// you wire it.\n\t\tauthorize: async () => ({\n\t\t\tok: false,\n\t\t\treason: 'authorization not configured'\n\t\t}),\n\t\tinstructions: ${settings.instructions},\n\t\tissuer: ${settings.issuer},\n\t\tpath: ${settings.path},\n\t\tscopesSupported: ${settings.scopesSupported},\n\t\tserveRootMetadata: ${settings.serveRootMetadata},\n\t\tserverInfo: ${settings.serverInfo} ?? { name: 'my-site', version: '0.1.0' },\n\t\ttools: async () => {\n\t\t\t// Every installed AbsoluteJS package ships a manifest; bridging\n\t\t\t// it exposes that package's tools here. Pass the live instance\n\t\t\t// you constructed for the package as `runtime` — tools without\n\t\t\t// their binding are omitted (fail closed).\n\t\t\t// TODO: list the packages this endpoint should expose.\n\t\t\tconst exposed: { name: string; runtime?: unknown }[] = [];\n\t\t\tconst registries = await Promise.all(\n\t\t\t\texposed.map(async ({ name, runtime }) => {\n\t\t\t\t\tconst loaded = await loadManifest(name);\n\n\t\t\t\t\treturn loaded.ok\n\t\t\t\t\t\t? toMcpToolRegistry(loaded.manifest, { runtime })\n\t\t\t\t\t\t: {};\n\t\t\t\t})\n\t\t\t);\n\n\t\t\treturn Object.assign({}, ...registries);\n\t\t}\n\t})\n)",
+				"imports": [
+					{
+						"from": "@absolutejs/mcp",
+						"names": [
+							"mcpServer"
+						]
+					},
+					{
+						"from": "@absolutejs/manifest",
+						"names": [
+							"loadManifest",
+							"toMcpToolRegistry"
+						]
+					}
+				],
+				"placement": "server-plugin"
+			},
+			"title": "Serve installed packages' tools over MCP"
+		}
+	]
+}

package/dist/src/index.d.ts

@@ -38,4 +38,5 @@ export { createMcpHandler } from "./handler";
 export { metadataPathFor, protectedResourceMetadata, type ProtectedResourceMetadata, } from "./metadata";
 export { mcpServer } from "./server";
 export { createSessionRegistry, type SessionRegistry } from "./sessions";
-export type { McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";
+export { createMemoryMcpTaskStore, publicMcpTask } from "./tasks";
+export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTask, McpTaskStatus, McpTaskStore, McpTasksOptions, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";

package/dist/src/jsonrpc.d.ts

@@ -3,13 +3,14 @@ export declare const JSONRPC_INVALID_REQUEST = -32600;
 export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
 export declare const JSONRPC_INVALID_PARAMS = -32602;
 export declare const JSONRPC_INTERNAL_ERROR = -32603;
+export declare const JSONRPC_MISSING_REQUIRED_CLIENT_CAPABILITY = -32003;
 export declare const HTTP_ACCEPTED = 202;
 export declare const HTTP_NO_CONTENT = 204;
 export declare const HTTP_UNAUTHORIZED = 401;
 export declare const HTTP_METHOD_NOT_ALLOWED = 405;
 export type JsonRpcId = string | number | null;
 export declare const rpcResult: (id: JsonRpcId, result: unknown) => Response;
-export declare const rpcError: (id: JsonRpcId, code: number, message: string) => Response;
+export declare const rpcError: (id: JsonRpcId, code: number, message: string, data?: Record<string, unknown>) => Response;
 export declare const notificationAck: () => Response;
 /** 401 with the RFC 9728 `WWW-Authenticate` challenge pointing at the
  *  protected-resource metadata, so the client can discover the auth server. */

package/dist/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { McpServerConfig } from "./types";
+export declare const manifest: import("@absolutejs/manifest").PackageManifest<McpServerConfig<unknown>, never>;

package/dist/src/tasks.d.ts

@@ -0,0 +1,14 @@
+import type { McpTask, McpTaskStore } from "./types";
+export declare const createMemoryMcpTaskStore: () => McpTaskStore;
+export declare const publicMcpTask: ({ authorizationKey, ...task }: McpTask) => {
+    createdAt: string;
+    error?: Record<string, unknown>;
+    inputRequests?: Record<string, unknown>;
+    lastUpdatedAt: string;
+    pollIntervalMs?: number;
+    result?: Record<string, unknown>;
+    status: import("./types").McpTaskStatus;
+    statusMessage?: string;
+    taskId: string;
+    ttlMs: number | null;
+};

package/dist/src/types.d.ts

@@ -1,3 +1,5 @@
+import type { Agency, AgentActor } from "@absolutejs/agency";
+import type { ToolAuthorization } from "@absolutejs/manifest";
 /** MCP behaviour hints, passed straight through to the client on `tools/list`.
  *  Structurally identical to `@absolutejs/ai`'s `AIToolAnnotations`, so a tool
  *  map from that package satisfies this without conversion. All optional. */
@@ -108,6 +110,9 @@ export type McpToolCallContext = {
 /** One callable tool. `inputSchema` is a JSON Schema object. */
 export type McpTool = {
     annotations?: McpToolAnnotations;
+    /** Enforceable semantic effects from manifest contract 2. A tool carrying
+     *  this is hidden unless the server configures `agency`. */
+    authorization?: ToolAuthorization;
     description: string;
     handler: (args: unknown, context: McpToolCallContext) => McpToolReturn | Promise<McpToolReturn>;
     inputSchema: Record<string, unknown>;
@@ -165,6 +170,50 @@ export type McpToolContext<Caller> = {
     caller: Caller;
     meta: McpCallMeta;
 };
+export type McpAgencyOptions<Caller> = {
+    enforcement: Agency;
+    resolveActor: (context: {
+        caller: Caller;
+        scopes: string[];
+    }) => Promise<AgentActor> | AgentActor;
+    serverId?: string;
+};
+export type McpTaskStatus = "cancelled" | "completed" | "failed" | "input_required" | "working";
+export type McpTask = {
+    authorizationKey: string;
+    createdAt: string;
+    error?: Record<string, unknown>;
+    inputRequests?: Record<string, unknown>;
+    lastUpdatedAt: string;
+    pollIntervalMs?: number;
+    result?: Record<string, unknown>;
+    status: McpTaskStatus;
+    statusMessage?: string;
+    taskId: string;
+    ttlMs: number | null;
+};
+export type McpTaskStore = {
+    cancel: (taskId: string) => Promise<void> | void;
+    get: (taskId: string) => Promise<McpTask | null> | McpTask | null;
+    save: (task: McpTask) => Promise<void> | void;
+    update: (taskId: string, update: Partial<Omit<McpTask, "authorizationKey" | "createdAt" | "taskId">>) => Promise<McpTask | null> | McpTask | null;
+};
+export type McpTasksOptions<Caller> = {
+    authorizationKey: (caller: Caller) => Promise<string> | string;
+    onUpdate?: (context: {
+        caller: Caller;
+        inputResponses: Record<string, unknown>;
+        task: McpTask;
+    }) => Promise<void> | void;
+    pollIntervalMs?: number;
+    shouldCreate: (context: {
+        args: unknown;
+        caller: Caller;
+        name: string;
+    }) => Promise<boolean> | boolean;
+    store: McpTaskStore;
+    ttlMs?: number | null;
+};
 export type McpPrompts<Caller> = {
     definitions: Record<string, McpPromptDefinition>;
     get: (ctx: {
@@ -190,6 +239,8 @@ export type McpServerInfo = {
     version: string;
 };
 export type McpServerConfig<Caller> = {
+    /** Per-tool action policy enforcement, approval, leases, and receipts. */
+    agency?: McpAgencyOptions<Caller>;
     /** Resolve the request into a caller, or a reason for the 401. The package
      *  emits the 401 + RFC 9728 `WWW-Authenticate` challenge; you decide who is
      *  allowed in. See {@link verifyBearer} for the standard token checks. */
@@ -244,6 +295,8 @@ export type McpServerConfig<Caller> = {
     /** Protocol versions this endpoint accepts; the first is the preferred one.
      *  Defaults to the versions this package knows. */
     supportedProtocols?: string[];
+    /** Final SEP-2663 `io.modelcontextprotocol/tasks` extension support. */
+    tasks?: McpTasksOptions<Caller>;
     /** Build the tool registry for this caller. Called once per request. */
     tools: (ctx: McpToolContext<Caller>) => McpToolRegistry | Promise<McpToolRegistry>;
 };

package/package.json

@@ -10,7 +10,28 @@
   "peerDependencies": {
     "elysia": ">=1.1.0"
   },
+  "dependencies": {
+    "@absolutejs/agency": "^0.1.0",
+    "@absolutejs/manifest": "^0.2.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
   "license": "BUSL-1.1",
+  "absolutejs": {
+    "manifestContract": 2
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/src/manifest.d.ts",
+      "import": "./dist/manifest.js",
+      "default": "./dist/manifest.js"
+    },
+    "./manifest.json": "./dist/manifest.json"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -30,12 +51,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target=bun --external elysia && tsc --emitDeclarationOnly --project tsconfig.json",
+    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --root ./src --target=bun --external elysia && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
     "release": "bun run format && bun run test && bun run build && bun publish",
     "test": "bun test",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.4.2"
+  "version": "0.5.0"
 }