strapi-mcp-server 0.1.1

package/server/src/services/session-store.ts

@@ -0,0 +1,216 @@
+'use strict';
+
+import type { Core } from '@strapi/strapi';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { getConfig } from '../config';
+import type { Scope } from './oauth/scopes';
+
+export interface SessionPrincipal {
+  adminUserId: string;
+  clientId: string;
+  jti: string;
+}
+
+export interface Session {
+  id: string;
+  transport: StreamableHTTPServerTransport;
+  mcpServer: McpServer;
+  principal: SessionPrincipal;
+  scopes: Scope[];
+  createdAt: number;
+  lastSeenAt: number;
+}
+
+export type Location =
+  | { kind: 'local'; session: Session }
+  | { kind: 'remote'; instance: string; address: string; principal: SessionPrincipal }
+  | undefined;
+
+const sessions = new Map<string, Session>();
+const byPrincipal = new Map<string, Set<string>>();
+
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  function directory() {
+    return strapi.plugin('mcp-server').service('session-directory');
+  }
+  function instanceId(): string {
+    return strapi.plugin('mcp-server').service('instance-id').get();
+  }
+  function localPrincipalKey(p: SessionPrincipal): string {
+    return `${p.adminUserId}:${p.clientId}`;
+  }
+
+  return {
+    /**
+     * Resolve a session id to either the local in-memory session or a remote
+     * directory entry pointing at the owning instance. Returns undefined when
+     * the id is unknown both locally and in Redis.
+     */
+    async locate(id: string): Promise<Location> {
+      const local = sessions.get(id);
+      if (local) {
+        local.lastSeenAt = Date.now();
+        return { kind: 'local', session: local };
+      }
+      const remote = await directory().lookup(id);
+      if (!remote) return undefined;
+      if (remote.instance === instanceId()) {
+        // Stale directory entry — we are the owner but lost it (process
+        // restart, sweep, etc.). Drop the entry so clients re-initialize.
+        await directory().unregister(id, {
+          adminUserId: remote.adminUserId,
+          clientId: remote.clientId,
+          jti: '',
+        });
+        return undefined;
+      }
+      return {
+        kind: 'remote',
+        instance: remote.instance,
+        address: remote.address,
+        principal: {
+          adminUserId: remote.adminUserId,
+          clientId: remote.clientId,
+          jti: '',
+        },
+      };
+    },
+
+    /**
+     * Returns false when global or per-principal caps would be exceeded. In
+     * single-instance mode caps are local. With Redis routing enabled, the
+     * principal cap becomes cluster-wide (queried from the directory).
+     */
+    async canCreate(principal: SessionPrincipal): Promise<boolean> {
+      const cfg = getConfig(strapi);
+      if (sessions.size >= cfg.session.maxTotal) return false;
+      if (await directory().isActive()) {
+        const count = await directory().countForPrincipal(
+          principal.adminUserId,
+          principal.clientId
+        );
+        return count < cfg.session.maxPerPrincipal;
+      }
+      const owned = byPrincipal.get(localPrincipalKey(principal))?.size ?? 0;
+      return owned < cfg.session.maxPerPrincipal;
+    },
+
+    async put(session: Session): Promise<void> {
+      sessions.set(session.id, session);
+      const key = localPrincipalKey(session.principal);
+      let set = byPrincipal.get(key);
+      if (!set) {
+        set = new Set();
+        byPrincipal.set(key, set);
+      }
+      set.add(session.id);
+
+      if (await directory().isActive()) {
+        const cfg = getConfig(strapi);
+        const internalAddress = cfg.redis?.internalAddress;
+        if (!internalAddress) return; // Caller / config validator should have caught this.
+        await directory().register({
+          id: session.id,
+          instance: instanceId(),
+          address: internalAddress,
+          adminUserId: session.principal.adminUserId,
+          clientId: session.principal.clientId,
+          createdAt: session.createdAt,
+          expiresAt: session.createdAt + cfg.session.hardTtlMs,
+        });
+      }
+    },
+
+    async close(id: string): Promise<void> {
+      const s = sessions.get(id);
+      if (s) {
+        sessions.delete(id);
+        byPrincipal.get(localPrincipalKey(s.principal))?.delete(id);
+        try {
+          await s.transport.close();
+        } catch (err) {
+          strapi.log.warn(`[mcp-server] transport close failed for session=${id}`, err as Error);
+        }
+      }
+      if (await directory().isActive()) {
+        await directory().unregister(
+          id,
+          s
+            ? s.principal
+            : undefined
+        );
+      }
+    },
+
+    async closeAll(): Promise<void> {
+      const ids = [...sessions.keys()];
+      await Promise.all(ids.map((id) => this.close(id)));
+    },
+
+    /** Evict idle and hard-TTL-exceeded sessions; called periodically by bootstrap. */
+    sweep(): void {
+      const cfg = getConfig(strapi);
+      const now = Date.now();
+      const toClose: string[] = [];
+      for (const [id, s] of sessions.entries()) {
+        if (now - s.lastSeenAt > cfg.session.idleTtlMs) toClose.push(id);
+        else if (now - s.createdAt > cfg.session.hardTtlMs) toClose.push(id);
+      }
+      for (const id of toClose) {
+        void this.close(id);
+      }
+    },
+
+    /**
+     * Drop all sessions belonging to an admin user across the cluster.
+     *
+     * Closes local sessions immediately AND publishes on `mcp:revoke` so peer
+     * instances close any sessions they own for the same principal. The
+     * principal's tokens get revoked through a separate path (tokens service);
+     * this only affects session liveness.
+     */
+    async closeForPrincipal(adminUserId: string): Promise<void> {
+      await this.closeForPrincipalLocal(adminUserId);
+      // Broadcast to peers — best-effort, log on failure.
+      try {
+        const r = await strapi.plugin('mcp-server').service('redis').get();
+        if (r) {
+          const channel = strapi.plugin('mcp-server').service('redis').key('revoke');
+          await r.publish(channel, adminUserId);
+        }
+      } catch (err) {
+        strapi.log.warn(
+          `[mcp-server] failed to publish revocation for user=${adminUserId}: ${(err as Error).message}`
+        );
+      }
+    },
+
+    /**
+     * Local-only variant — closes sessions for the principal on THIS instance
+     * without re-publishing. The pub/sub subscriber in bootstrap calls this on
+     * incoming `mcp:revoke` messages so we don't loop.
+     */
+    async closeForPrincipalLocal(adminUserId: string): Promise<void> {
+      for (const [id, s] of sessions.entries()) {
+        if (s.principal.adminUserId === adminUserId) {
+          // eslint-disable-next-line no-await-in-loop
+          await this.close(id);
+        }
+      }
+    },
+
+    stats(): { total: number; byPrincipal: Record<string, number> } {
+      const byP: Record<string, number> = {};
+      for (const [k, set] of byPrincipal.entries()) byP[k] = set.size;
+      return { total: sessions.size, byPrincipal: byP };
+    },
+
+    /** Local-only lookup. Used by the proxy receive controller. */
+    getLocal(id: string): Session | undefined {
+      const s = sessions.get(id);
+      if (s) s.lastSeenAt = Date.now();
+      return s;
+    },
+  };
+};

package/server/src/services/sso-cookie.ts

@@ -0,0 +1,146 @@
+'use strict';
+
+import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
+import type { Core } from '@strapi/strapi';
+import { getConfig } from '../config';
+
+const COOKIE_NAME = 'mcp_admin_sso';
+const RESUME_COOKIE_NAME = 'mcp_resume';
+const RESUME_TTL_SEC = 600;
+
+interface CookiePayload {
+  adminId: string;
+  /**
+   * Strapi admin session id captured at handoff time. We re-check it against
+   * `strapi.sessionManager('admin').isSessionActive` on every verify so that
+   * logging out of Strapi admin immediately invalidates our SSO cookie too —
+   * otherwise our own TTL would let a logged-out user breeze past /authorize.
+   * Older cookies issued before this field was added omit it; we treat those
+   * as invalid to fail closed.
+   */
+  sid?: string;
+  exp: number;
+  nonce: string;
+}
+
+interface ResumePayload {
+  url: string;
+  exp: number;
+}
+
+/**
+ * The SSO cookie is HMAC'd with a key derived from the active OAuth signing key
+ * (kid + Strapi APP_KEYS). Never uses ADMIN_JWT_SECRET. The cookie body is
+ * base64url(JSON) and the signature is the second segment.
+ */
+export default ({ strapi }: { strapi: Core.Strapi }) => {
+  async function hmacKey(): Promise<string> {
+    const key = await strapi.plugin('mcp-server').service('signing-keys').getActiveKey();
+    const appKeys = strapi.config.get('app.keys') as string[] | undefined;
+    return `${key.kid}.${(appKeys ?? []).join('|')}`;
+  }
+
+  function sign(value: string, key: string): string {
+    return createHmac('sha256', key).update(value).digest('base64url');
+  }
+
+  return {
+    cookieName(): string {
+      return COOKIE_NAME;
+    },
+
+    resumeCookieName(): string {
+      return RESUME_COOKIE_NAME;
+    },
+
+    /**
+     * Sign a resume URL into a short-lived cookie. Used to survive Strapi's
+     * /auth/login redirectTo round-trip, which double-decodes the value and
+     * mangles nested OAuth query strings. The cookie is the source of truth;
+     * the URL `next` param is best-effort fallback.
+     */
+    async issueResume(url: string): Promise<{ value: string; maxAgeSec: number }> {
+      const payload: ResumePayload = {
+        url,
+        exp: Math.floor(Date.now() / 1000) + RESUME_TTL_SEC,
+      };
+      const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+      const sig = sign(body, await hmacKey());
+      return { value: `${body}.${sig}`, maxAgeSec: RESUME_TTL_SEC };
+    },
+
+    async verifyResume(cookieValue: string | undefined): Promise<string | null> {
+      if (!cookieValue) return null;
+      const [body, sig] = cookieValue.split('.');
+      if (!body || !sig) return null;
+      const expected = sign(body, await hmacKey());
+      if (expected.length !== sig.length) return null;
+      try {
+        if (!timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return null;
+      } catch {
+        return null;
+      }
+      try {
+        const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as ResumePayload;
+        if (typeof payload.exp !== 'number' || payload.exp < Math.floor(Date.now() / 1000)) return null;
+        if (typeof payload.url !== 'string' || !payload.url.startsWith('/')) return null;
+        return payload.url;
+      } catch {
+        return null;
+      }
+    },
+
+    async issue(
+      adminId: string,
+      sessionId: string
+    ): Promise<{ value: string; maxAgeSec: number }> {
+      const cfg = getConfig(strapi);
+      const exp = Math.floor(Date.now() / 1000) + cfg.oauth.ssoCookieTtlSec;
+      const payload: CookiePayload = {
+        adminId,
+        sid: sessionId,
+        exp,
+        nonce: randomBytes(12).toString('base64url'),
+      };
+      const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+      const sig = sign(body, await hmacKey());
+      return { value: `${body}.${sig}`, maxAgeSec: cfg.oauth.ssoCookieTtlSec };
+    },
+
+    async verify(cookieValue: string | undefined): Promise<string | null> {
+      if (!cookieValue) return null;
+      const [body, sig] = cookieValue.split('.');
+      if (!body || !sig) return null;
+      const expected = sign(body, await hmacKey());
+      if (expected.length !== sig.length) return null;
+      try {
+        if (!timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return null;
+      } catch {
+        return null;
+      }
+      let payload: CookiePayload;
+      try {
+        payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as CookiePayload;
+      } catch {
+        return null;
+      }
+      if (typeof payload.exp !== 'number' || payload.exp < Math.floor(Date.now() / 1000)) return null;
+      if (typeof payload.adminId !== 'string' || !payload.adminId) return null;
+      if (typeof payload.sid !== 'string' || !payload.sid) return null;
+      // Re-check the bound Strapi admin session is still active. When the
+      // admin logs out, Strapi calls invalidateRefreshToken which deletes the
+      // session row; this check then returns false and the cookie is
+      // effectively dead even though our own TTL hasn't expired yet.
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const sm = strapi.sessionManager('admin' as any);
+        const active: boolean = await sm.isSessionActive(payload.sid);
+        if (!active) return null;
+      } catch {
+        // Defensive: if the session manager isn't available, fail closed.
+        return null;
+      }
+      return payload.adminId;
+    },
+  };
+};

package/server/src/services/tools/content.ts

@@ -0,0 +1,284 @@
+'use strict';
+
+import { z } from 'zod';
+import type { Core } from '@strapi/strapi';
+import type { PrincipalContext } from '../permissions';
+import { hasScope, type Scope } from '../oauth/scopes';
+
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  scope: Scope;
+  inputSchema: z.ZodTypeAny;
+  handler: (args: unknown) => Promise<{ content: Array<{ type: 'text'; text: string }> }>;
+}
+
+export interface ToolFactoryArgs {
+  strapi: Core.Strapi;
+  principal: PrincipalContext;
+  scopes: Scope[];
+}
+
+const populateSchema = z
+  .union([z.literal('*'), z.array(z.string().regex(/^[A-Za-z0-9_.]{1,64}$/))])
+  .optional();
+
+const uidSchema = (strapi: Core.Strapi) =>
+  z.string().refine(
+    (uid) =>
+      uid in (strapi.contentTypes as unknown as Record<string, unknown>) &&
+      !strapi
+        .plugin('mcp-server')
+        .service('permissions')
+        .isInternalUid(uid),
+    { message: 'unknown or disallowed uid' }
+  );
+
+export function createContentTools(args: ToolFactoryArgs): ToolDef[] {
+  const { strapi, principal, scopes } = args;
+  const permSvc = strapi.plugin('mcp-server').service('permissions');
+
+  function requireScope(s: Scope): void {
+    if (!hasScope(scopes, s)) {
+      const err = new Error('You do not have permission to perform this action.');
+      (err as Error & { code?: string }).code = 'insufficient_scope';
+      throw err;
+    }
+  }
+
+  async function requirePerm(uid: string, action: 'read' | 'create' | 'update'): Promise<void> {
+    const ok = await permSvc.canActionOnUid(principal, uid, action);
+    if (!ok) {
+      const err = new Error('You do not have permission to access this content.');
+      (err as Error & { code?: string }).code = 'forbidden';
+      throw err;
+    }
+  }
+
+  const json = (value: unknown) => ({
+    content: [{ type: 'text' as const, text: JSON.stringify(value) }],
+  });
+
+  return [
+    {
+      name: 'strapi.content.list_types',
+      description: 'List all content-types the caller is allowed to see.',
+      scope: 'strapi:content:read',
+      inputSchema: z.object({}).strict(),
+      async handler() {
+        requireScope('strapi:content:read');
+        const allowed = permSvc.listAllowedUids() as string[];
+        const filtered: Array<Record<string, unknown>> = [];
+        for (const uid of allowed) {
+          // eslint-disable-next-line no-await-in-loop
+          if (!(await permSvc.canActionOnUid(principal, uid, 'read'))) continue;
+          const cts = strapi.contentTypes as unknown as Record<
+            string,
+            {
+              kind?: string;
+              info?: { displayName?: string; pluralName?: string };
+              options?: { draftAndPublish?: boolean };
+            }
+          >;
+          const ct = cts[uid];
+          filtered.push({
+            uid,
+            kind: ct.kind,
+            displayName: ct.info?.displayName,
+            pluralName: ct.info?.pluralName,
+            draftAndPublish: !!ct.options?.draftAndPublish,
+          });
+        }
+        return json({ contentTypes: filtered });
+      },
+    },
+
+    {
+      name: 'strapi.content.get_schema',
+      description: 'Return the attribute schema for a single content-type.',
+      scope: 'strapi:content:read',
+      inputSchema: z.object({ uid: uidSchema(strapi) }).strict(),
+      async handler(raw) {
+        requireScope('strapi:content:read');
+        const input = z.object({ uid: uidSchema(strapi) }).parse(raw) as { uid: string };
+        await requirePerm(input.uid, 'read');
+        const cts = strapi.contentTypes as unknown as Record<
+          string,
+          {
+            kind?: string;
+            info?: Record<string, unknown>;
+            attributes: Record<string, { type: string; component?: string; components?: string[] }>;
+          }
+        >;
+        const ct = cts[input.uid];
+        const components = strapi.components as unknown as Record<string, { attributes: unknown }>;
+        const referenced: Record<string, unknown> = {};
+        for (const attr of Object.values(ct.attributes)) {
+          if (attr.type === 'component' && attr.component && components[attr.component]) {
+            referenced[attr.component] = components[attr.component].attributes;
+          }
+          if (attr.type === 'dynamiczone' && Array.isArray(attr.components)) {
+            for (const c of attr.components) {
+              if (components[c]) referenced[c] = components[c].attributes;
+            }
+          }
+        }
+        return json({
+          uid: input.uid,
+          kind: ct.kind,
+          info: ct.info,
+          attributes: ct.attributes,
+          components: referenced,
+        });
+      },
+    },
+
+    {
+      name: 'strapi.content.list_entries',
+      description: 'Paginated list of entries for a content-type. pageSize <= 100.',
+      scope: 'strapi:content:read',
+      inputSchema: z
+        .object({
+          uid: uidSchema(strapi),
+          filters: z.record(z.any()).optional(),
+          pagination: z
+            .object({
+              page: z.number().int().min(1).max(10000).default(1),
+              pageSize: z.number().int().min(1).max(100).default(25),
+            })
+            .optional(),
+          locale: z.string().regex(LOCALE_RE).optional(),
+          status: z.enum(['draft', 'published']).default('draft'),
+          populate: populateSchema,
+        })
+        .strict(),
+      async handler(raw) {
+        requireScope('strapi:content:read');
+        const schema = this.inputSchema as z.ZodTypeAny;
+        const input = schema.parse(raw) as {
+          uid: string;
+          filters?: Record<string, unknown>;
+          pagination?: { page: number; pageSize: number };
+          locale?: string;
+          status: 'draft' | 'published';
+          populate?: '*' | string[];
+        };
+        await requirePerm(input.uid, 'read');
+
+        const page = input.pagination?.page ?? 1;
+        const pageSize = Math.min(100, input.pagination?.pageSize ?? 25);
+
+        const result = await strapi.documents(input.uid as never).findMany({
+          filters: (input.filters ?? {}) as never,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          locale: input.locale as any,
+          status: input.status,
+          populate: input.populate as never,
+          start: (page - 1) * pageSize,
+          limit: pageSize,
+        });
+        return json({ page, pageSize, count: result.length, results: result });
+      },
+    },
+
+    {
+      name: 'strapi.content.get_entry',
+      description: 'Fetch a single entry by documentId.',
+      scope: 'strapi:content:read',
+      inputSchema: z
+        .object({
+          uid: uidSchema(strapi),
+          documentId: z.string().min(1).max(128),
+          locale: z.string().regex(LOCALE_RE).optional(),
+          status: z.enum(['draft', 'published']).default('draft'),
+          populate: populateSchema,
+        })
+        .strict(),
+      async handler(raw) {
+        requireScope('strapi:content:read');
+        const schema = this.inputSchema as z.ZodTypeAny;
+        const input = schema.parse(raw) as {
+          uid: string;
+          documentId: string;
+          locale?: string;
+          status: 'draft' | 'published';
+          populate?: '*' | string[];
+        };
+        await requirePerm(input.uid, 'read');
+        const result = await strapi.documents(input.uid as never).findOne({
+          documentId: input.documentId,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          locale: input.locale as any,
+          status: input.status,
+          populate: input.populate as never,
+        });
+        return json(result ?? null);
+      },
+    },
+
+    {
+      name: 'strapi.content.create_entry',
+      description: 'Create a draft entry. Publish/unpublish is not exposed.',
+      scope: 'strapi:content:write',
+      inputSchema: z
+        .object({
+          uid: uidSchema(strapi),
+          data: z.record(z.any()),
+          locale: z.string().regex(LOCALE_RE).optional(),
+        })
+        .strict(),
+      async handler(raw) {
+        requireScope('strapi:content:write');
+        const schema = this.inputSchema as z.ZodTypeAny;
+        const input = schema.parse(raw) as {
+          uid: string;
+          data: Record<string, unknown>;
+          locale?: string;
+        };
+        await requirePerm(input.uid, 'create');
+        const result = await strapi.documents(input.uid as never).create({
+          data: input.data as never,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          locale: input.locale as any,
+          status: 'draft',
+        });
+        return json(result);
+      },
+    },
+
+    {
+      name: 'strapi.content.update_entry',
+      description: 'Partial update of an existing draft entry. Publish/unpublish not exposed.',
+      scope: 'strapi:content:write',
+      inputSchema: z
+        .object({
+          uid: uidSchema(strapi),
+          documentId: z.string().min(1).max(128),
+          data: z.record(z.any()),
+          locale: z.string().regex(LOCALE_RE).optional(),
+        })
+        .strict(),
+      async handler(raw) {
+        requireScope('strapi:content:write');
+        const schema = this.inputSchema as z.ZodTypeAny;
+        const input = schema.parse(raw) as {
+          uid: string;
+          documentId: string;
+          data: Record<string, unknown>;
+          locale?: string;
+        };
+        await requirePerm(input.uid, 'update');
+        const result = await strapi.documents(input.uid as never).update({
+          documentId: input.documentId,
+          data: input.data as never,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          locale: input.locale as any,
+          status: 'draft',
+        });
+        return json(result);
+      },
+    },
+  ];
+}

package/server/src/services/tools/index.ts

@@ -0,0 +1,23 @@
+'use strict';
+
+import type { ToolDef, ToolFactoryArgs } from './content';
+import { createContentTools } from './content';
+import { createMediaTools } from './media';
+import { getConfig } from '../../config';
+
+export type { ToolDef, ToolFactoryArgs };
+
+/**
+ * Build the per-session tool list. Filters by:
+ *  - granted scopes (a tool whose scope isn't granted is not registered at all)
+ *  - master-toggle in config.tools.enabled[name] (default: true)
+ */
+export function buildToolsForSession(args: ToolFactoryArgs): ToolDef[] {
+  const cfg = getConfig(args.strapi);
+  const all = [...createContentTools(args), ...createMediaTools(args)];
+  return all.filter((t) => {
+    if (!args.scopes.includes(t.scope)) return false;
+    const toggle = cfg.tools.enabled[t.name];
+    return toggle === undefined ? true : toggle;
+  });
+}