strapi-mcp-server 0.1.1

package/server/src/register.ts

@@ -0,0 +1,48 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig } from './config';
+
+/**
+ * Runs once at Strapi init, before bootstrap. Validates config again as a
+ * belt-and-suspenders measure (config.validator is the primary gate) and
+ * registers RBAC permission actions for the plugin's admin pages.
+ */
+export async function register({ strapi }: { strapi: Core.Strapi }): Promise<void> {
+  const cfg = getConfig(strapi);
+
+  if (!cfg.enabled) {
+    strapi.log.info('[mcp-server] plugin disabled — skipping registration');
+    return;
+  }
+
+  // Three permissions, each gating a distinct slice of the admin API:
+  //   read         → dashboard, settings (read-only), tools list, sidebar entry
+  //   audit.read   → audit log
+  //   clients.manage → OAuth client CRUD
+  // Settings has no "manage" because mutations happen in config/plugins.ts —
+  // the admin UI is view-only.
+  const actionProvider = strapi.service('admin::permission').actionProvider;
+  await actionProvider.registerMany([
+    {
+      uid: 'read',
+      displayName: 'Read MCP dashboard',
+      pluginName: 'mcp-server',
+      section: 'plugins',
+    },
+    {
+      uid: 'audit.read',
+      displayName: 'Read MCP audit log',
+      pluginName: 'mcp-server',
+      section: 'plugins',
+    },
+    {
+      uid: 'clients.manage',
+      displayName: 'Manage OAuth clients',
+      pluginName: 'mcp-server',
+      section: 'plugins',
+    },
+  ]);
+
+  strapi.log.info('[mcp-server] registered RBAC actions and validated config');
+}

package/server/src/routes/admin.ts

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Admin API routes. Every route requires an authenticated admin AND a
+ * specific permission registered in `register.ts`. The role UI checkboxes
+ * map onto these endpoints 1:1 so toggling them in **Settings →
+ * Administration Panel → Roles** has the obvious effect.
+ *
+ * Permissions:
+ *   `plugin::mcp-server.read`           → dashboard, settings, tools
+ *   `plugin::mcp-server.audit.read`     → audit log
+ *   `plugin::mcp-server.clients.manage` → OAuth clients CRUD
+ *
+ * Settings are read-only from the UI (mutations happen in `config/plugins.ts`),
+ * so there's no separate "manage settings" permission — exposing a runtime
+ * mutation surface would let admins weaken security without an audit trail.
+ */
+const requirePermission = (action: string) => [
+  'admin::isAuthenticatedAdmin',
+  { name: 'admin::hasPermissions', config: { actions: [action] } },
+];
+
+const readPolicies = requirePermission('plugin::mcp-server.read');
+const auditPolicies = requirePermission('plugin::mcp-server.audit.read');
+const clientPolicies = requirePermission('plugin::mcp-server.clients.manage');
+
+export default {
+  type: 'admin' as const,
+  routes: [
+    {
+      method: 'GET',
+      path: '/dashboard',
+      handler: 'dashboard.overview',
+      config: { policies: readPolicies },
+    },
+    {
+      method: 'GET',
+      path: '/clients',
+      handler: 'clients.list',
+      config: { policies: clientPolicies },
+    },
+    {
+      method: 'POST',
+      path: '/clients',
+      handler: 'clients.create',
+      config: { policies: clientPolicies },
+    },
+    {
+      method: 'GET',
+      path: '/clients/:clientId',
+      handler: 'clients.findOne',
+      config: { policies: clientPolicies },
+    },
+    {
+      method: 'PUT',
+      path: '/clients/:clientId',
+      handler: 'clients.update',
+      config: { policies: clientPolicies },
+    },
+    {
+      method: 'DELETE',
+      path: '/clients/:clientId',
+      handler: 'clients.destroy',
+      config: { policies: clientPolicies },
+    },
+    {
+      method: 'GET',
+      path: '/audit',
+      handler: 'audit.list',
+      config: { policies: auditPolicies },
+    },
+    {
+      method: 'GET',
+      path: '/settings',
+      handler: 'settings.get',
+      config: { policies: readPolicies },
+    },
+    {
+      method: 'GET',
+      path: '/tools',
+      handler: 'tools.list',
+      config: { policies: readPolicies },
+    },
+  ],
+};

package/server/src/routes/index.ts

@@ -0,0 +1,13 @@
+'use strict';
+
+import mcp from './mcp';
+import oauth from './oauth';
+import admin from './admin';
+import proxy from './proxy';
+
+export default {
+  mcp,
+  oauth,
+  admin,
+  proxy,
+};

package/server/src/routes/mcp.ts

@@ -0,0 +1,31 @@
+'use strict';
+
+const policies = ['plugin::mcp-server.origin', 'plugin::mcp-server.authenticate', 'plugin::mcp-server.rateLimit'];
+
+// type: 'admin' + prefix: '' mounts at the host root (no /api prefix). Strapi's
+// admin router itself has prefix '', so admin-typed routes with prefix '' land
+// at `/<path>` exactly. Auth is bypassed per-route via `auth: false`.
+export default {
+  type: 'admin' as const,
+  prefix: '',
+  routes: [
+    {
+      method: 'POST',
+      path: '/mcp',
+      handler: 'mcp.handle',
+      config: { auth: false, policies },
+    },
+    {
+      method: 'GET',
+      path: '/mcp',
+      handler: 'mcp.handle',
+      config: { auth: false, policies },
+    },
+    {
+      method: 'DELETE',
+      path: '/mcp',
+      handler: 'mcp.end',
+      config: { auth: false, policies },
+    },
+  ],
+};

package/server/src/routes/oauth.ts

@@ -0,0 +1,81 @@
+'use strict';
+
+const originPolicy = ['plugin::mcp-server.origin'];
+
+// type: 'admin' + prefix: '' mounts at the host root — required so the
+// well-known URLs and /oauth/* paths match what AS metadata advertises.
+export default {
+  type: 'admin' as const,
+  prefix: '',
+  routes: [
+    {
+      method: 'GET',
+      path: '/.well-known/oauth-protected-resource',
+      handler: 'metadata.protectedResource',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'GET',
+      path: '/.well-known/oauth-authorization-server',
+      handler: 'metadata.authorizationServer',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'GET',
+      path: '/oauth/jwks',
+      handler: 'metadata.jwks',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'GET',
+      path: '/oauth/authorize',
+      handler: 'authorize.start',
+      config: { auth: false, policies: originPolicy },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/consent',
+      handler: 'authorize.consent',
+      config: { auth: false, policies: originPolicy },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/sso-handoff',
+      handler: 'authorize.ssoHandoff',
+      config: { auth: false, policies: originPolicy },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/token',
+      handler: 'token.token',
+      config: { auth: false, policies: originPolicy },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/revoke',
+      handler: 'token.revoke',
+      config: { auth: false, policies: originPolicy },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/introspect',
+      handler: 'introspect.introspect',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'POST',
+      path: '/oauth/register',
+      handler: 'dcr-register.register',
+      config: { auth: false, policies: originPolicy },
+    },
+    // Some MCP clients (Claude Code's SDK is one) fall back to a default
+    // `/register` path when DCR metadata is absent. Alias it so the response is
+    // a parseable JSON error instead of a plain-text 405 from Koa.
+    {
+      method: 'POST',
+      path: '/register',
+      handler: 'dcr-register.register',
+      config: { auth: false, policies: originPolicy },
+    },
+  ],
+};

package/server/src/routes/proxy.ts

@@ -0,0 +1,29 @@
+'use strict';
+
+// Internal cluster-peer endpoint. Bypasses origin/auth/rate-limit policies;
+// the proxy controller validates the HMAC on `X-MCP-Proxy-Auth` and dispatches
+// directly into a local session. Mounted at root, not under /api.
+export default {
+  type: 'admin' as const,
+  prefix: '',
+  routes: [
+    {
+      method: 'POST',
+      path: '/__mcp/proxy/:sessionId',
+      handler: 'proxy.receive',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'GET',
+      path: '/__mcp/proxy/:sessionId',
+      handler: 'proxy.receive',
+      config: { auth: false, policies: [] },
+    },
+    {
+      method: 'DELETE',
+      path: '/__mcp/proxy/:sessionId',
+      handler: 'proxy.receive',
+      config: { auth: false, policies: [] },
+    },
+  ],
+};

package/server/src/services/audit.ts

@@ -0,0 +1,158 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+
+const UID = 'plugin::mcp-server.audit-log';
+
+export interface AuditEntry {
+  ts: Date;
+  principalType: 'admin' | 'system';
+  principalId: string;
+  sessionId?: string;
+  clientId?: string;
+  tool: string;
+  params?: unknown;
+  resultStatus: 'ok' | 'error';
+  errorCode?: string;
+  ip?: string;
+  userAgent?: string;
+  durationMs?: number;
+}
+
+let queue: AuditEntry[] = [];
+
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  const cfg = () => getConfig(strapi);
+
+  return {
+    record(entry: AuditEntry): void {
+      const redacted: AuditEntry = {
+        ...entry,
+        params: redact(entry.params, cfg().audit.redactKeyPatterns),
+      };
+      queue.push(redacted);
+      if (queue.length >= cfg().audit.drainBatchSize) {
+        void this.drain();
+      }
+    },
+
+    async drain(): Promise<void> {
+      if (queue.length === 0) return;
+      const batch = queue;
+      queue = [];
+      try {
+        await strapi.db.query(UID).createMany({ data: batch });
+      } catch (err) {
+        strapi.log.error('[mcp-server] audit write failed; dropping batch', err as Error);
+      }
+    },
+
+    async purgeOlderThan(days: number): Promise<number> {
+      const cutoff = new Date(Date.now() - days * 86400 * 1000);
+      const { count } = await strapi.db.query(UID).deleteMany({ where: { ts: { $lt: cutoff } } });
+      return count ?? 0;
+    },
+
+    async recent(limit = 50, filters: Record<string, unknown> = {}): Promise<AuditEntry[]> {
+      return strapi.db
+        .query(UID)
+        .findMany({ where: filters, orderBy: { ts: 'desc' }, limit: Math.min(500, limit) });
+    },
+
+    /**
+     * Resolve admin user + OAuth client info for a batch of audit rows. Used
+     * by both the audit list and the dashboard's recent-calls panel so they
+     * present principal as a human name instead of a raw numeric ID, and so
+     * the OAuth client (Claude Code, etc.) is identified by name.
+     */
+    async enrich(
+      rows: Array<{ principalId?: string | null; clientId?: string | null }>
+    ): Promise<
+      Array<{
+        principalAdmin: AdminUserRow | null;
+        client: { clientId: string; clientName: string } | null;
+      }>
+    > {
+      const adminIds = Array.from(
+        new Set(
+          rows
+            .map((r) => r.principalId)
+            .filter((v): v is string => typeof v === 'string' && v.length > 0)
+            .map((s) => Number(s))
+            .filter((n) => Number.isFinite(n))
+        )
+      );
+      const clientIds = Array.from(
+        new Set(
+          rows
+            .map((r) => r.clientId)
+            .filter((v): v is string => typeof v === 'string' && v.length > 0)
+        )
+      );
+
+      const [admins, clients] = await Promise.all([
+        adminIds.length
+          ? (strapi.db.query('admin::user').findMany({
+              where: { id: { $in: adminIds } },
+              select: ['id', 'email', 'firstname', 'lastname', 'username'],
+            }) as Promise<AdminUserRow[]>)
+          : Promise.resolve<AdminUserRow[]>([]),
+        clientIds.length
+          ? (strapi.db.query('plugin::mcp-server.oauth-client').findMany({
+              where: { clientId: { $in: clientIds } },
+              select: ['clientId', 'clientName'],
+            }) as Promise<Array<{ clientId: string; clientName: string }>>)
+          : Promise.resolve<Array<{ clientId: string; clientName: string }>>([]),
+      ]);
+
+      const adminById = new Map(admins.map((a) => [String(a.id), a]));
+      const clientById = new Map(clients.map((c) => [c.clientId, c]));
+
+      return rows.map((r) => ({
+        principalAdmin: r.principalId ? adminById.get(r.principalId) ?? null : null,
+        client: r.clientId ? clientById.get(r.clientId) ?? null : null,
+      }));
+    },
+
+    /** Test/diagnostic only. */
+    _peekQueue(): AuditEntry[] {
+      return [...queue];
+    },
+  };
+};
+
+export interface AdminUserRow {
+  id: number;
+  email?: string;
+  firstname?: string;
+  lastname?: string;
+  username?: string;
+}
+
+const TRUNCATE_AT = 2048;
+
+export function redact(value: unknown, patterns: string[]): unknown {
+  const regex = new RegExp(`(${patterns.join('|')})`, 'i');
+  return walk(value, regex, 0);
+}
+
+function walk(value: unknown, regex: RegExp, depth: number): unknown {
+  if (depth > 6) return '[truncated:depth]';
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'string' && value.length > TRUNCATE_AT) {
+      return value.slice(0, TRUNCATE_AT) + '…';
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.slice(0, 50).map((v) => walk(v, regex, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (regex.test(k)) {
+      out[k] = '[redacted]';
+    } else {
+      out[k] = walk(v, regex, depth + 1);
+    }
+  }
+  return out;
+}

package/server/src/services/heartbeat.ts

@@ -0,0 +1,76 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+
+let timer: NodeJS.Timeout | null = null;
+
+/**
+ * Instance liveness via Redis. Every active instance refreshes
+ * `mcp:inst:{INSTANCE_ID}` on a short interval (default 10s) with a slightly
+ * longer TTL (default 30s) — peers consider an instance dead if its key has
+ * disappeared.
+ *
+ * Used by the session directory to:
+ *  - Skip proxying to a known-dead owner (return 404 instead of 502).
+ *  - Garbage-collect stale `mcp:sess:{id}` entries pointing at dead instances.
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  function key(instanceId: string): string {
+    return strapi.plugin('mcp-server').service('redis').key('inst', instanceId);
+  }
+
+  async function refresh(): Promise<void> {
+    const cfg = getConfig(strapi);
+    if (!cfg.redis?.enabled || !cfg.redis.internalAddress) return;
+    const r = await strapi.plugin('mcp-server').service('redis').get();
+    if (!r) return;
+    const id = strapi.plugin('mcp-server').service('instance-id').get();
+    const ttlSec = Math.max(2, Math.ceil((cfg.redis.heartbeatTtlMs ?? 30_000) / 1000));
+    try {
+      await r.set(key(id), String(Date.now()), 'EX', ttlSec);
+    } catch (err) {
+      strapi.log.warn(`[mcp-server] heartbeat refresh failed: ${(err as Error).message}`);
+    }
+  }
+
+  return {
+    /** Start the periodic refresh. Safe to call multiple times. */
+    async start(): Promise<void> {
+      const cfg = getConfig(strapi);
+      if (!cfg.redis?.enabled || !cfg.redis.internalAddress) return;
+      if (timer) return;
+      // Write one immediately so peers can see us right away.
+      await refresh();
+      const intervalMs = Math.max(1_000, cfg.redis.heartbeatIntervalMs ?? 10_000);
+      timer = setInterval(() => {
+        void refresh();
+      }, intervalMs);
+    },
+
+    stop(): void {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+
+    /**
+     * Truthy when the instance's heartbeat key still exists in Redis. Used by
+     * the directory to decide whether to attempt a proxy or treat the session
+     * as orphaned.
+     */
+    async isAlive(instanceId: string): Promise<boolean> {
+      const cfg = getConfig(strapi);
+      if (!cfg.redis?.enabled) return true; // single-instance mode — always alive
+      const r = await strapi.plugin('mcp-server').service('redis').get();
+      if (!r) return true;
+      try {
+        const v = await r.get(key(instanceId));
+        return v !== null;
+      } catch {
+        return true; // fail-open on transient Redis hiccup
+      }
+    },
+  };
+};

package/server/src/services/index.ts

@@ -0,0 +1,37 @@
+'use strict';
+
+import audit from './audit';
+import rateLimiter from './rate-limiter';
+import permissions from './permissions';
+import sessionStore from './session-store';
+import sessionDirectory from './session-directory';
+import mcpServerFactory from './mcp-server';
+import ssoCookie from './sso-cookie';
+import redis from './redis';
+import instanceId from './instance-id';
+import proxyClient from './proxy-client';
+import heartbeat from './heartbeat';
+import signingKeys from './oauth/signing-keys';
+import tokens from './oauth/tokens';
+import consent from './oauth/consent';
+import clients from './oauth/clients';
+import authCodes from './oauth/auth-codes';
+
+export default {
+  audit,
+  'rate-limiter': rateLimiter,
+  permissions,
+  'session-store': sessionStore,
+  'session-directory': sessionDirectory,
+  'mcp-server': mcpServerFactory,
+  'sso-cookie': ssoCookie,
+  redis,
+  'instance-id': instanceId,
+  'proxy-client': proxyClient,
+  heartbeat,
+  'signing-keys': signingKeys,
+  tokens,
+  consent,
+  clients,
+  'auth-codes': authCodes,
+};

package/server/src/services/instance-id.ts

@@ -0,0 +1,30 @@
+'use strict';
+
+import { hostname } from 'os';
+import { randomBytes } from 'crypto';
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+
+let cached: string | null = null;
+
+/**
+ * Stable per-process identifier. Used as the value of `sess:{id}.instance`
+ * in the Redis session directory so peers know who owns a session.
+ *
+ * Format: `<hostname>-<pid>-<8hex>` so operators can match it to a host
+ * when debugging. Override via `config.redis.instanceId` if you'd rather
+ * pin it (e.g. from a Kubernetes pod name).
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  get(): string {
+    if (cached) return cached;
+    const cfg = getConfig(strapi);
+    const override = cfg.redis?.instanceId?.trim();
+    if (override) {
+      cached = override;
+      return cached;
+    }
+    cached = `${hostname()}-${process.pid}-${randomBytes(4).toString('hex')}`;
+    return cached;
+  },
+});

package/server/src/services/mcp-server.ts

@@ -0,0 +1,100 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { randomUUID } from 'crypto';
+import type { Scope } from './oauth/scopes';
+import type { PrincipalContext } from './permissions';
+import { buildToolsForSession } from './tools';
+
+export default ({ strapi }: { strapi: Core.Strapi }) => ({
+  /**
+   * Construct a fresh McpServer + StreamableHTTPServerTransport for a new
+   * session. The transport's `sessionIdGenerator` returns a UUID the first
+   * time it's called (during `initialize`), then the same id forever — the
+   * SDK uses that to issue `Mcp-Session-Id` on the initial response.
+   */
+  async create(options: {
+    principal: PrincipalContext;
+    scopes: Scope[];
+    clientId: string;
+    jti: string;
+  }): Promise<{
+    sessionId: string;
+    transport: StreamableHTTPServerTransport;
+    mcpServer: McpServer;
+  }> {
+    const sessionId = randomUUID();
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => sessionId,
+      enableJsonResponse: false,
+    });
+
+    const mcpServer = new McpServer({
+      name: 'strapi-mcp-server',
+      version: '0.1.0',
+    });
+
+    const tools = buildToolsForSession({
+      strapi,
+      principal: options.principal,
+      scopes: options.scopes,
+    });
+
+    for (const tool of tools) {
+      mcpServer.registerTool(
+        tool.name,
+        {
+          description: tool.description,
+          // The SDK accepts a Zod schema object literal under `inputSchema`.
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          inputSchema: (tool.inputSchema as any).shape ?? tool.inputSchema,
+        },
+        async (raw: unknown) => {
+          const startedAt = Date.now();
+          const auditPayload = {
+            ts: new Date(),
+            principalType: 'admin' as const,
+            principalId: String(options.principal.user.id),
+            sessionId,
+            clientId: options.clientId,
+            tool: tool.name,
+            params: raw,
+            resultStatus: 'ok' as 'ok' | 'error',
+            errorCode: undefined as string | undefined,
+            durationMs: 0,
+          };
+          try {
+            const result = await tool.handler.call(tool, raw);
+            auditPayload.durationMs = Date.now() - startedAt;
+            strapi.plugin('mcp-server').service('audit').record(auditPayload);
+            return result;
+          } catch (err) {
+            const code = (err as Error & { code?: string }).code;
+            auditPayload.resultStatus = 'error';
+            auditPayload.errorCode = code ?? 'internal';
+            auditPayload.durationMs = Date.now() - startedAt;
+            strapi.plugin('mcp-server').service('audit').record(auditPayload);
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: JSON.stringify({
+                    error: code ?? 'internal_error',
+                    message: (err as Error).message,
+                  }),
+                },
+              ],
+              isError: true,
+            };
+          }
+        }
+      );
+    }
+
+    await mcpServer.connect(transport);
+    return { sessionId, transport, mcpServer };
+  },
+});