keryx 0.13.0 → 0.14.0

package/README.md

@@ -187,14 +187,24 @@ task = { queue: "default", frequency: 1000 * 60 * 60 }; // every hour
 
 ### MCP Actions
 
-When the MCP server is enabled (`MCP_SERVER_ENABLED=true`), every action is automatically registered as an [MCP](https://modelcontextprotocol.io) tool. AI agents and LLM clients (Claude Desktop, VS Code, etc.) can discover and call your actions through the standard Model Context Protocol.
+When the MCP server is enabled (`MCP_SERVER_ENABLED=true`), every action is automatically registered as an [MCP](https://modelcontextprotocol.io) tool. AI agents and LLM clients (Claude Desktop, VS Code, etc.) can discover and call your actions through the standard Model Context Protocol. Actions can also be exposed as MCP **resources** (URI-addressed data) and **prompts** (named templates) via `mcp.resource` and `mcp.prompt`.
 
-Action names are converted to valid MCP tool names by replacing `:` with `-` (e.g., `user:create` becomes `user-create`). The action's Zod schema is converted to JSON Schema for tool parameter definitions.
+Action names are converted to valid MCP tool names by replacing `:` with `-` (e.g., `user:create` becomes `user-create`). The action's Zod schema is converted to JSON Schema for tool and prompt parameter definitions.
 
-To exclude an action from MCP:
+To exclude an action from MCP tools:
 
 ```ts
-mcp = { enabled: false };
+mcp = { tool: false };
+```
+
+To expose an action as an MCP resource or prompt:
+
+```ts
+// Resource — clients fetch this by URI
+mcp = { tool: false, resource: { uri: "myapp://status", mimeType: "application/json" } };
+
+// Prompt — clients invoke this as a named template
+mcp = { tool: false, prompt: { title: "Greeting" } };
 ```
 
 OAuth 2.1 with PKCE is used for authentication — MCP clients go through a browser-based login flow, and subsequent tool calls carry a Bearer token tied to the authenticated user's session.

package/classes/Action.ts

@@ -19,11 +19,33 @@ export type OAuthActionResponse = {
 
 export type McpActionConfig = {
   /** Expose this action as an MCP tool (default true) */
-  enabled?: boolean;
+  tool?: boolean;
   /** Tag as the OAuth login action */
   isLoginAction?: boolean;
   /** Tag as the OAuth signup action */
   isSignupAction?: boolean;
+  /**
+   * Register this action as an MCP resource.
+   * The action's `run()` must return `{ text: string; mimeType?: string }` or `{ blob: string; mimeType?: string }` (base64).
+   * URI template variables (e.g., `{userId}` in `keryx://users/{userId}`) are passed as action params.
+   */
+  resource?: {
+    /** Static URI, e.g. `"keryx://status"`. Mutually exclusive with `uriTemplate`. */
+    uri?: string;
+    /** URI template (RFC 6570), e.g. `"keryx://users/{userId}"`. Variables become action params. */
+    uriTemplate?: string;
+    /** MIME type of the resource content (e.g., `"application/json"`, `"text/plain"`) */
+    mimeType?: string;
+  };
+  /**
+   * Register this action as an MCP prompt.
+   * The action's `inputs` schema becomes the prompt's argument schema.
+   * The action's `run()` must return `{ description?: string; messages: PromptMessage[] }`.
+   */
+  prompt?: {
+    /** Human-readable display title for the prompt */
+    title?: string;
+  };
 };
 
 export type ActionConstructorInputs = {
@@ -39,7 +61,7 @@ export type ActionConstructorInputs = {
   /** Middleware hooks to run before/after `run()` */
   middleware?: ActionMiddleware[];
 
-  /** Expose this action via the MCP server (defaults to `{ enabled: true }`) */
+  /** Expose this action via the MCP server (defaults to `{ tool: true }`) */
   mcp?: McpActionConfig;
 
   /** Expose this action via HTTP (defaults: route `/${name}`, method `GET`) */
@@ -115,7 +137,7 @@ export abstract class Action {
     this.inputs = args.inputs;
     this.middleware = args.middleware ?? [];
     this.timeout = args.timeout;
-    this.mcp = { enabled: true, ...args.mcp };
+    this.mcp = { tool: true, ...args.mcp };
     this.web = {
       route: args.web?.route ?? `/${this.name}`,
       method: args.web?.method ?? HTTP_METHOD.GET,

package/config/server/mcp.ts

@@ -1,8 +1,13 @@
+import pkg from "../../package.json";
 import { loadFromEnvIfSet } from "../../util/config";
 
 export const configServerMcp = {
   enabled: await loadFromEnvIfSet("MCP_SERVER_ENABLED", false),
   route: await loadFromEnvIfSet("MCP_SERVER_ROUTE", "/mcp"),
+  instructions: await loadFromEnvIfSet(
+    "MCP_SERVER_INSTRUCTIONS",
+    pkg.description as string,
+  ),
   oauthClientTtl: await loadFromEnvIfSet(
     "MCP_OAUTH_CLIENT_TTL",
     60 * 60 * 24 * 30,

package/initializers/actionts.ts

@@ -638,7 +638,7 @@ export class Actions extends Initializer {
 
     for (const a of actions) {
       if (!a.description) a.description = `An Action: ${a.name}`;
-      a.mcp = { enabled: true, ...a.mcp };
+      a.mcp = { tool: true, ...a.mcp };
     }
 
     logger.info(`loaded ${Object.keys(actions).length} actions`);

package/initializers/mcp.ts

@@ -1,4 +1,7 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import colors from "colors";
 import { randomUUID } from "crypto";
@@ -347,18 +350,18 @@ export class McpInitializer extends Initializer {
 }
 
 /**
- * Create a new McpServer instance with all actions registered as tools.
+ * Create a new McpServer instance with all actions registered as tools, resources, and prompts.
  * Each MCP session gets its own McpServer (the SDK requires 1:1 mapping).
- * Actions with `mcp === false` are excluded from tool registration.
+ * Actions with `mcp.tool === false` are excluded from tool registration.
  */
 function createMcpServer(): McpServer {
   const mcpServer = new McpServer(
     { name: pkg.name, version: pkg.version },
-    { instructions: pkg.description },
+    { instructions: config.server.mcp.instructions },
   );
 
   for (const action of api.actions.actions) {
-    if (!action.mcp?.enabled) continue;
+    if (action.mcp?.tool === false) continue;
 
     const toolName = formatToolName(action.name);
     const toolConfig: {
@@ -382,7 +385,13 @@ function createMcpServer(): McpServer {
 
         const clientIp = (authInfo?.extra?.ip as string) || "unknown";
         const mcpSessionId = extra.sessionId || "";
-        const connection = new Connection("mcp", clientIp, randomUUID());
+        const connection = new Connection(
+          "mcp",
+          clientIp,
+          randomUUID(),
+          undefined,
+          authInfo?.token,
+        );
 
         try {
           // If Bearer token was verified, set up authenticated session
@@ -430,6 +439,154 @@ function createMcpServer(): McpServer {
     );
   }
 
+  // Register actions as MCP resources
+  for (const action of api.actions.actions) {
+    if (!action.mcp?.resource) continue;
+    const { uri, uriTemplate, mimeType } = action.mcp.resource;
+
+    const readCb = async (
+      mcpUri: URL,
+      variables: Record<string, string | string[]>,
+      extra: any,
+    ) => {
+      const authInfo = extra.authInfo;
+      const clientIp = (authInfo?.extra?.ip as string) || "unknown";
+      const mcpSessionId = extra.sessionId || "";
+      const connection = new Connection(
+        "mcp",
+        clientIp,
+        randomUUID(),
+        undefined,
+        authInfo?.token,
+      );
+
+      try {
+        if (authInfo?.extra?.userId) {
+          await connection.loadSession();
+          await connection.updateSession({ userId: authInfo.extra.userId });
+        }
+
+        const params: Record<string, unknown> = { ...variables };
+        const { response, error } = await connection.act(
+          action.name,
+          params,
+          "",
+          mcpSessionId,
+        );
+
+        if (error) {
+          throw new TypedError({
+            message: error.message,
+            type: error.type ?? ErrorType.CONNECTION_ACTION_RUN,
+          });
+        }
+
+        const content = response as {
+          text?: string;
+          blob?: string;
+          mimeType?: string;
+        };
+        const resolvedMimeType =
+          content.mimeType ?? mimeType ?? "application/json";
+
+        return {
+          contents: [
+            {
+              uri: mcpUri.toString(),
+              mimeType: resolvedMimeType,
+              ...(content.blob
+                ? { blob: content.blob }
+                : {
+                    text:
+                      typeof content.text === "string"
+                        ? content.text
+                        : JSON.stringify(response),
+                  }),
+            },
+          ],
+        };
+      } finally {
+        connection.destroy();
+      }
+    };
+
+    if (uriTemplate) {
+      mcpServer.registerResource(
+        formatToolName(action.name),
+        new ResourceTemplate(uriTemplate, { list: undefined }),
+        { description: action.description, mimeType },
+        readCb,
+      );
+    } else if (uri) {
+      mcpServer.registerResource(
+        formatToolName(action.name),
+        uri,
+        { description: action.description, mimeType },
+        (mcpUri: URL, extra: any) => readCb(mcpUri, {}, extra),
+      );
+    }
+  }
+
+  // Register actions as MCP prompts
+  for (const action of api.actions.actions) {
+    if (!action.mcp?.prompt) continue;
+    const { title } = action.mcp.prompt;
+
+    mcpServer.registerPrompt(
+      formatToolName(action.name),
+      {
+        title: title ?? action.name,
+        description: action.description,
+        // argsSchema expects a Record<string, ZodType> (the shape), not a z.object()
+        argsSchema: action.inputs
+          ? sanitizeSchemaForMcp(action.inputs)?.shape
+          : undefined,
+      },
+      async (args: any, extra: any) => {
+        const authInfo = extra.authInfo;
+        const clientIp = (authInfo?.extra?.ip as string) || "unknown";
+        const mcpSessionId = extra.sessionId || "";
+        const connection = new Connection(
+          "mcp",
+          clientIp,
+          randomUUID(),
+          undefined,
+          authInfo?.token,
+        );
+
+        try {
+          if (authInfo?.extra?.userId) {
+            await connection.loadSession();
+            await connection.updateSession({ userId: authInfo.extra.userId });
+          }
+
+          const params =
+            args && typeof args === "object"
+              ? (args as Record<string, unknown>)
+              : {};
+
+          const { response, error } = await connection.act(
+            action.name,
+            params,
+            "",
+            mcpSessionId,
+          );
+
+          if (error) {
+            throw new TypedError({
+              message: error.message,
+              type: error.type ?? ErrorType.CONNECTION_ACTION_RUN,
+            });
+          }
+
+          return response as any;
+        } finally {
+          connection.destroy();
+        }
+      },
+    );
+  }
+
   return mcpServer;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",