@adminforth/mcp 1.1.0 → 1.1.1

package/dist/oauthEndpoints.js

@@ -0,0 +1,126 @@
+import { logger } from 'adminforth';
+import { OAUTH_PATHS } from './oauth.js';
+import { OAuthError } from './oauthError.js';
+import { MCP_PATH } from './urls.js';
+const MAX_FORM_BODY_BYTES = 16 * 1024;
+/**
+ * RFC 6749 token requests are application/x-www-form-urlencoded. The host app may already have parsed the body
+ * with its own urlencoded middleware; otherwise the stream is still unread.
+ */
+async function readFormBody(req) {
+    if (req.body && typeof req.body === 'object' && Object.keys(req.body).length) {
+        return req.body;
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_FORM_BODY_BYTES) {
+            throw new OAuthError('invalid_request', `Request body is larger than ${MAX_FORM_BODY_BYTES} bytes`);
+        }
+        chunks.push(chunk);
+    }
+    return Object.fromEntries(new URLSearchParams(Buffer.concat(chunks).toString('utf8')));
+}
+async function oauthResponse(input, handler) {
+    try {
+        const result = await handler();
+        // A handler that answered through the raw response returns null; headers can no longer be set then.
+        if (result !== null)
+            input.response.setHeader('Cache-Control', 'no-store');
+        return result;
+    }
+    catch (error) {
+        if (!(error instanceof OAuthError))
+            throw error;
+        input.response.setHeader('Cache-Control', 'no-store');
+        input.response.setStatus(400);
+        return error.toResponseObject();
+    }
+}
+export function setupOAuthEndpoints(server, oauth, apiPrefix) {
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.protectedResourceMetadata,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => oauth.protectedResourceMetadata(),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorizationServerMetadata,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => oauth.authorizationServerMetadata(),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.jwks,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async () => ({ keys: [] }),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorize,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        noAuth: true,
+        handler: async (input) => oauthResponse(input, async () => {
+            const consentPageUrl = await oauth.authorize(input.query);
+            input._raw_express_res.set('Cache-Control', 'no-store').redirect(302, consentPageUrl);
+            return null;
+        }),
+    });
+    server.endpoint({
+        method: 'GET',
+        path: OAUTH_PATHS.authorization,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        handler: async (input) => oauthResponse(input, () => oauth.describeAuthorization(String(input.query.request))),
+    });
+    server.endpoint({
+        method: 'POST',
+        path: OAUTH_PATHS.authorization,
+        agent: {
+            hiddenFromAgents: true,
+        },
+        handler: async (input) => oauthResponse(input, async () => ({
+            redirectUrl: await oauth.resolveAuthorization(String(input.body.request), input.body.approved === true, input.adminUser, input.body.readOnly === true),
+        })),
+    });
+    const { expressApp } = server;
+    // MCP clients try the host-root well-known URLs first and stop at the first 200 response. The AdminForth SPA
+    // answers every unknown path with 200 HTML, so unless these are served the client fails before it reaches
+    // `<issuer>/.well-known/openid-configuration`. Behind a proxy that forwards only the AdminForth path they 404,
+    // and the client goes on to that URL.
+    const mcpPath = `${apiPrefix}${MCP_PATH}`;
+    expressApp.get(`/.well-known/oauth-protected-resource${mcpPath}`, async (_req, res) => {
+        res.json(oauth.protectedResourceMetadata());
+    });
+    expressApp.get(`/.well-known/oauth-authorization-server${mcpPath}`, async (_req, res) => {
+        res.json(oauth.authorizationServerMetadata());
+    });
+    expressApp.post(`${apiPrefix}${OAUTH_PATHS.token}`, async (req, res) => {
+        res.set('Cache-Control', 'no-store');
+        try {
+            res.json(await oauth.exchangeToken(await readFormBody(req)));
+        }
+        catch (error) {
+            if (error instanceof OAuthError) {
+                res.status(400).json(error.toResponseObject());
+                return;
+            }
+            logger.error(`AdminForthMcpPlugin: OAuth token request failed: ${error.stack ?? String(error)}`);
+            res.status(500).json({ error: 'server_error', error_description: 'Internal server error' });
+        }
+    });
+}

package/dist/oauthError.d.ts

@@ -0,0 +1,9 @@
+/** OAuth error answered as RFC 6749 `{ error, error_description }` with HTTP 400. */
+export declare class OAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, description: string);
+    toResponseObject(): {
+        error: string;
+        error_description: string;
+    };
+}

package/dist/oauthError.js

@@ -0,0 +1,11 @@
+/** OAuth error answered as RFC 6749 `{ error, error_description }` with HTTP 400. */
+export class OAuthError extends Error {
+    code;
+    constructor(code, description) {
+        super(description);
+        this.code = code;
+    }
+    toResponseObject() {
+        return { error: this.code, error_description: this.message };
+    }
+}

package/dist/skills.d.ts

@@ -0,0 +1,19 @@
+import type { McpToolDefinition } from './apiTools.js';
+export declare const FETCH_SKILL_TOOL_NAME = "fetch_skill";
+type TemplateValues = Record<string, string | number>;
+/**
+ * Guidance for MCP clients, kept as Markdown in the plugin `custom` folder: `instructions.md` holds the rules every
+ * client gets in the server instructions, `skills/<name>/SKILL.md` the detailed rules clients load with fetch_skill.
+ */
+export declare class McpSkills {
+    private readonly instructions;
+    private readonly skills;
+    constructor(customFolderPath: string, values: TemplateValues);
+    serverInstructions(): string;
+    toolDefinition(): McpToolDefinition;
+    call(args: Record<string, unknown> | undefined): {
+        output: unknown;
+        isError: boolean;
+    };
+}
+export {};

package/dist/skills.js

@@ -0,0 +1,79 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+export const FETCH_SKILL_TOOL_NAME = 'fetch_skill';
+const INSTRUCTIONS_FILE_NAME = 'instructions.md';
+const SKILLS_DIR_NAME = 'skills';
+const SKILL_FILE_NAME = 'SKILL.md';
+// SKILL.md starts with YAML frontmatter between two --- lines, the rest is the skill body.
+const SKILL_FILE_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+// Placeholders like {{pageSize.max}} in instructions and skills are filled from plugin options.
+const TEMPLATE_PLACEHOLDER_RE = /\{\{\s*([\w.]+)\s*\}\}/g;
+function renderTemplate(template, values, source) {
+    return template.replace(TEMPLATE_PLACEHOLDER_RE, (_, key) => {
+        if (!(key in values)) {
+            throw new Error(`AdminForthMcpPlugin: unknown placeholder {{${key}}} in ${source}`);
+        }
+        return String(values[key]);
+    });
+}
+function readSkill(skillsDir, directoryName, values) {
+    const file = join(skillsDir, directoryName, SKILL_FILE_NAME);
+    const [, frontmatter, body] = readFileSync(file, 'utf8').match(SKILL_FILE_RE);
+    const metadata = YAML.parse(frontmatter);
+    return {
+        name: metadata.name,
+        description: renderTemplate(metadata.description, values, file),
+        instructions: renderTemplate(body.trim(), values, file),
+    };
+}
+/**
+ * Guidance for MCP clients, kept as Markdown in the plugin `custom` folder: `instructions.md` holds the rules every
+ * client gets in the server instructions, `skills/<name>/SKILL.md` the detailed rules clients load with fetch_skill.
+ */
+export class McpSkills {
+    instructions;
+    skills;
+    constructor(customFolderPath, values) {
+        const instructionsFile = join(customFolderPath, INSTRUCTIONS_FILE_NAME);
+        this.instructions = renderTemplate(readFileSync(instructionsFile, 'utf8').trim(), values, instructionsFile);
+        const skillsDir = join(customFolderPath, SKILLS_DIR_NAME);
+        this.skills = new Map(readdirSync(skillsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => readSkill(skillsDir, entry.name, values))
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((skill) => [skill.name, skill]));
+    }
+    serverInstructions() {
+        const skillList = Array.from(this.skills.values())
+            .map((skill) => `- ${skill.name}: ${skill.description}`)
+            .join('\n');
+        return [
+            this.instructions,
+            `Before a task, load the matching skill with ${FETCH_SKILL_TOOL_NAME}; it has the detailed rules:\n${skillList}`,
+        ].join('\n\n');
+    }
+    toolDefinition() {
+        return {
+            name: FETCH_SKILL_TOOL_NAME,
+            description: `Returns the detailed rules of a skill for working with this admin panel. Load the matching skill before the task. Skills: ${Array.from(this.skills.keys()).join(', ')}.`,
+            inputSchema: {
+                type: 'object',
+                required: ['skillName'],
+                properties: {
+                    skillName: { type: 'string', enum: Array.from(this.skills.keys()) },
+                },
+            },
+        };
+    }
+    call(args) {
+        const skill = this.skills.get(String(args?.skillName));
+        if (!skill) {
+            return {
+                output: { error: `Unknown skill: ${args?.skillName}`, skills: Array.from(this.skills.keys()) },
+                isError: true,
+            };
+        }
+        return { output: skill.instructions, isError: false };
+    }
+}

package/dist/types.d.ts

@@ -9,11 +9,49 @@ export interface McpAuthSecretResourceOptions {
     lastUsedAtField: string;
     lastUsedByAgentField: string;
     readOnlyField: string;
+    /**
+     * Client ID Metadata Document URL of the MCP client connected through OAuth; empty for personal auth secrets.
+     * Setting it enables OAuth sign-in, which also needs adminPanelOrigin. Without it only auth secrets work.
+     */
+    oauthClientIdField?: string;
+}
+/** An MCP client allowed to connect through OAuth, as its Client ID Metadata Document describes it. */
+export interface McpOAuthClient {
+    clientId: string;
+    clientName: string;
+    redirectUris: string[];
+}
+export interface McpPageSize {
+    /** Rows get_resource_data returns when the client does not pass limit. */
+    default: number;
+    /** Most rows get_resource_data returns per call; larger limits are capped. */
+    max: number;
 }
 export interface PluginOptions extends PluginsCommonOptions {
     authSecretResource: McpAuthSecretResourceOptions;
-    /** Public origin of this AdminForth installation, without the AdminForth baseUrl path. */
+    /**
+     * Public origin of this AdminForth installation, without the AdminForth baseUrl path, e.g. https://example.com.
+     * The MCP server URL shown on the settings page, the OAuth issuer and resource URLs are built from it, so it must
+     * be the origin MCP clients connect to. Required with OAuth sign-in; without it the settings page shows the MCP URL
+     * of the address it was opened at.
+     */
     adminPanelOrigin?: string;
+    /**
+     * MCP clients resolved from this list instead of fetching their Client ID Metadata Document, so OAuth can be
+     * tried locally without a public https URL. Ignored when NODE_ENV is "production": there every client_id is
+     * fetched as a document with SSRF checks. Unlisted client_ids are fetched in development too.
+     */
+    devOAuthClients?: McpOAuthClient[];
+    /** Page size limits for get_resource_data, also quoted in the MCP instructions and skills. Defaults to 10 and 100. */
+    pageSize?: Partial<McpPageSize>;
+    /** How long a tool handler may run before the call fails with a timeout error. Defaults to 15000 ms. */
+    toolTimeoutMs?: number;
+    /**
+     * Tool calls an agent may make for one user request before it must ask the user to continue. Defaults to 10.
+     * MCP clients do not tell the server where a user request starts, so this is a rule in the MCP instructions,
+     * not a server-side limit.
+     */
+    toolCallsPerRequest?: number;
     /**
      * Expose only endpoints marked with `agent: { onlyReadsData: true }` to every auth secret.
      * Without it, read-only mode is chosen per auth secret.

package/dist/urls.d.ts

@@ -0,0 +1,13 @@
+export declare const MCP_PATH = "/mcp";
+/** Path prefix of AdminForth API endpoints, e.g. `/admin/adminapi/v1`. */
+export declare function adminApiPrefix(baseUrl: string): string;
+/**
+ * Public URLs of the plugin, built once from adminPanelOrigin: the settings page, OAuth metadata and the MCP server
+ * info must all name the same URL, because OAuth accepts tokens only for the exact MCP resource URL.
+ */
+export interface McpUrls {
+    apiUrl: string;
+    mcpUrl: string;
+    adminPanelUrl: string;
+}
+export declare function createMcpUrls(adminPanelOrigin: string, baseUrl: string): McpUrls;

package/dist/urls.js

@@ -0,0 +1,13 @@
+export const MCP_PATH = '/mcp';
+/** Path prefix of AdminForth API endpoints, e.g. `/admin/adminapi/v1`. */
+export function adminApiPrefix(baseUrl) {
+    return `${baseUrl}/adminapi/v1`;
+}
+export function createMcpUrls(adminPanelOrigin, baseUrl) {
+    const apiUrl = new URL(adminApiPrefix(baseUrl), adminPanelOrigin).href;
+    return {
+        apiUrl,
+        mcpUrl: `${apiUrl}${MCP_PATH}`,
+        adminPanelUrl: new URL(baseUrl || '/', adminPanelOrigin).href,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Expose AdminForth APIs as an authenticated MCP server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -73,5 +73,8 @@
         "prerelease": true
       }
     ]
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
   }
 }