keycloak-model-context-protocol 0.0.2 → 1.0.0

package/dist/tools/events.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { defineTool, pageOf, paginationShape, realmField, toPage } from "./shared.js";
+const dateField = (label) => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Use YYYY-MM-DD")
+    .optional()
+    .describe(`${label} (YYYY-MM-DD, inclusive).`);
+const SENSITIVE_KEY = /token|secret|password|credential|^code$/i;
+/** Keeps string-valued detail entries, dropping anything that looks like a token or secret. */
+function safeDetails(details) {
+    const out = {};
+    for (const [key, value] of Object.entries(details ?? {})) {
+        if (SENSITIVE_KEY.test(key))
+            continue;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            out[key] = String(value);
+        }
+    }
+    return out;
+}
+const iso = (ms) => (ms === undefined ? undefined : new Date(ms).toISOString());
+const DISABLED_HINT = " The list is empty; events may be disabled for this realm (check the realm's event settings).";
+const loginEvent = z.object({
+    time: z.string().optional().describe("Event time (ISO 8601)."),
+    type: z.string().optional().describe("Event type, e.g. LOGIN or LOGIN_ERROR."),
+    userId: z.string().optional().describe("User ID, if known."),
+    clientId: z.string().optional().describe("Client involved, if known."),
+    ipAddress: z.string().optional().describe("Source IP address."),
+    error: z.string().optional().describe("Error code for failed events."),
+    details: z.record(z.string(), z.string()).describe("Event details; tokens are removed."),
+});
+const eventList = defineTool({
+    name: "event_list",
+    title: "List login events",
+    description: "List user/login events of a realm (logins, failed logins, logouts, password changes) with filters and pagination. Requires event storage to be enabled in the realm.",
+    kind: "read",
+    input: z.object({
+        realm: realmField,
+        type: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Event types to include, e.g. ['LOGIN', 'LOGIN_ERROR']."),
+        user: z.string().optional().describe("Filter by user ID."),
+        client: z.string().optional().describe("Filter by clientId."),
+        ipAddress: z.string().optional().describe("Filter by source IP address."),
+        dateFrom: dateField("Earliest event date"),
+        dateTo: dateField("Latest event date"),
+        ...paginationShape,
+    }),
+    output: pageOf(loginEvent).extend({ realm: z.string().describe("Realm that was queried.") }),
+    async handler({ realm, type, user, client, ipAddress, dateFrom, dateTo, first, max }, { gateway }) {
+        const rows = await gateway.run((kc) => kc.realms.findEvents({
+            realm,
+            first,
+            max: max + 1,
+            // Event types are validated by Keycloak; the client's union type is too narrow for free input.
+            ...(type !== undefined && { type: type }),
+            ...(user !== undefined && { user }),
+            ...(client !== undefined && { client }),
+            ...(ipAddress !== undefined && { ipAddress }),
+            ...(dateFrom !== undefined && { dateFrom }),
+            ...(dateTo !== undefined && { dateTo }),
+        }));
+        const mapped = rows.map((e) => ({
+            ...(e.time !== undefined && { time: iso(e.time) }),
+            ...(e.type !== undefined && { type: e.type }),
+            ...(e.userId !== undefined && { userId: e.userId }),
+            ...(e.clientId !== undefined && { clientId: e.clientId }),
+            ...(e.ipAddress !== undefined && { ipAddress: e.ipAddress }),
+            ...(e.error !== undefined && { error: e.error }),
+            details: safeDetails(e.details),
+        }));
+        const page = toPage(mapped, first, max);
+        const empty = page.items.length === 0 && first === 0;
+        return {
+            data: { ...page, realm },
+            summary: `Found ${page.items.length} event(s) in realm '${realm}'${page.hasMore ? " (more available)" : ""}.${empty ? DISABLED_HINT : ""}`,
+        };
+    },
+});
+const adminEvent = z.object({
+    time: z.string().optional().describe("Event time (ISO 8601)."),
+    operationType: z.string().optional().describe("CREATE, UPDATE, DELETE or ACTION."),
+    resourceType: z.string().optional().describe("Type of the changed resource, e.g. USER."),
+    resourcePath: z.string().optional().describe("Path of the changed resource."),
+    authDetails: z
+        .object({
+        userId: z.string().optional().describe("Admin user who made the change."),
+        realmId: z.string().optional().describe("Realm of the admin user."),
+        clientId: z.string().optional().describe("Client used for the change."),
+        ipAddress: z.string().optional().describe("Source IP address."),
+    })
+        .optional()
+        .describe("Who performed the operation."),
+    error: z.string().optional().describe("Error code if the operation failed."),
+});
+const adminEventList = defineTool({
+    name: "admin_event_list",
+    title: "List admin events",
+    description: "List admin (audit) events of a realm: who changed which resource and when. The change payload is deliberately omitted. Requires admin events to be enabled in the realm.",
+    kind: "read",
+    input: z.object({
+        realm: realmField,
+        operationTypes: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Operation types to include: CREATE, UPDATE, DELETE, ACTION."),
+        resourceTypes: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Resource types to include, e.g. ['USER', 'CLIENT']."),
+        resourcePath: z.string().optional().describe("Resource path filter; '*' wildcards allowed."),
+        authUser: z.string().optional().describe("Filter by ID of the acting admin user."),
+        dateFrom: dateField("Earliest event date"),
+        dateTo: dateField("Latest event date"),
+        ...paginationShape,
+    }),
+    output: pageOf(adminEvent).extend({ realm: z.string().describe("Realm that was queried.") }),
+    async handler({ realm, operationTypes, resourceTypes, resourcePath, authUser, dateFrom, dateTo, first, max }, { gateway }) {
+        const rows = await gateway.run((kc) => kc.realms.findAdminEvents({
+            realm,
+            first,
+            max: max + 1,
+            // The client serializes arrays as repeated params and Dates via toString(); the typings
+            // say string/Date, but Keycloak wants repeated params and YYYY-MM-DD strings.
+            ...(operationTypes !== undefined && {
+                operationTypes: operationTypes,
+            }),
+            ...(resourceTypes !== undefined && { resourceTypes: resourceTypes }),
+            ...(resourcePath !== undefined && { resourcePath }),
+            ...(authUser !== undefined && { authUser }),
+            ...(dateFrom !== undefined && { dateFrom: dateFrom }),
+            ...(dateTo !== undefined && { dateTo: dateTo }),
+        }));
+        const mapped = rows.map((e) => {
+            const a = e.authDetails;
+            const authDetails = a && {
+                ...(a.userId !== undefined && { userId: a.userId }),
+                ...(a.realmId !== undefined && { realmId: a.realmId }),
+                ...(a.clientId !== undefined && { clientId: a.clientId }),
+                ...(a.ipAddress !== undefined && { ipAddress: a.ipAddress }),
+            };
+            return {
+                ...(e.time !== undefined && { time: iso(e.time) }),
+                ...(e.operationType !== undefined && { operationType: e.operationType }),
+                ...(e.resourceType !== undefined && { resourceType: e.resourceType }),
+                ...(e.resourcePath !== undefined && { resourcePath: e.resourcePath }),
+                ...(authDetails && { authDetails }),
+                ...(e.error !== undefined && { error: e.error }),
+            };
+        });
+        const page = toPage(mapped, first, max);
+        const empty = page.items.length === 0 && first === 0;
+        return {
+            data: { ...page, realm },
+            summary: `Found ${page.items.length} admin event(s) in realm '${realm}'${page.hasMore ? " (more available)" : ""}.${empty ? DISABLED_HINT : ""}`,
+        };
+    },
+});
+export const eventTools = [eventList, adminEventList];
+//# sourceMappingURL=events.js.map

package/dist/tools/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tools/events.ts"],"names":[],"mappings":"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"}

package/dist/tools/groups.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { ToolError } from "../keycloak/errors.js";
+import { defineTool, pageOf, paginationShape, realmField, toPage } from "./shared.js";
+import { toUserSummary } from "./users.js";
+const groupSummary = z.object({
+    id: z.string().describe("Group ID (UUID); use it as `groupId` in other tools."),
+    name: z.string().describe("Group name."),
+    path: z.string().optional().describe("Full group path, e.g. /parent/child."),
+    subGroupCount: z.number().optional().describe("Number of direct subgroups."),
+});
+const groupList = defineTool({
+    name: "group_list",
+    title: "List groups",
+    description: "List groups of a realm, optionally filtered by a search string, with pagination. Returns id, name, path and number of subgroups.",
+    kind: "read",
+    input: z.object({
+        realm: realmField,
+        search: z.string().optional().describe("Only groups whose name contains this text."),
+        ...paginationShape,
+    }),
+    output: pageOf(groupSummary).extend({ realm: z.string().describe("Realm that was queried.") }),
+    async handler({ realm, search, first, max }, { gateway }) {
+        const rows = await gateway.run((kc) => kc.groups.find({
+            realm,
+            first,
+            max: max + 1,
+            briefRepresentation: true,
+            ...(search !== undefined && { search }),
+        }));
+        const items = rows.map((g) => ({
+            id: g.id ?? "",
+            name: g.name ?? "",
+            ...(g.path !== undefined && { path: g.path }),
+            ...(g.subGroupCount !== undefined && { subGroupCount: g.subGroupCount }),
+        }));
+        const page = toPage(items, first, max);
+        return {
+            data: { ...page, realm },
+            summary: `Found ${page.items.length} group(s) in realm '${realm}' (first=${first}, max=${max}${page.hasMore ? ", more available" : ""}).`,
+        };
+    },
+});
+const groupMembersList = defineTool({
+    name: "group_members_list",
+    title: "List group members",
+    description: "List the members of a group with a safe subset of user fields, with pagination.",
+    kind: "read",
+    input: z.object({
+        realm: realmField,
+        groupId: z.string().min(1).describe("ID (UUID) of the group, e.g. from group_list."),
+        ...paginationShape,
+    }),
+    output: pageOf(z.object({
+        id: z.string().describe("User ID (UUID)."),
+        username: z.string().describe("Login name."),
+        email: z.string().optional().describe("E-mail address, if set."),
+        firstName: z.string().optional().describe("First name, if set."),
+        lastName: z.string().optional().describe("Last name, if set."),
+        enabled: z.boolean().optional().describe("Whether the user can log in."),
+        emailVerified: z.boolean().optional().describe("Whether the e-mail is verified."),
+    })).extend({
+        realm: z.string().describe("Realm that was queried."),
+        groupId: z.string().describe("Group that was queried."),
+    }),
+    async handler({ realm, groupId, first, max }, { gateway }) {
+        const rows = await gateway.run((kc) => kc.groups.listMembers({ realm, id: groupId, first, max: max + 1, briefRepresentation: true }));
+        const page = toPage(rows.map(toUserSummary), first, max);
+        return {
+            data: { ...page, realm, groupId },
+            summary: `Found ${page.items.length} member(s) in group ${groupId} (first=${first}, max=${max}${page.hasMore ? ", more available" : ""}).`,
+        };
+    },
+});
+const membershipOutput = z.object({
+    userId: z.string().describe("ID of the user."),
+    groupId: z.string().describe("ID of the group."),
+    realm: z.string().describe("Realm of the user and group."),
+});
+const userGroupAdd = defineTool({
+    name: "user_group_add",
+    title: "Add user to group",
+    description: "Add a user to a group. Adding a user who is already a member has no further effect.",
+    kind: "write",
+    idempotent: true,
+    input: z.object({
+        realm: realmField,
+        userId: z.string().min(1).describe("ID (UUID) of the user."),
+        groupId: z.string().min(1).describe("ID (UUID) of the group."),
+    }),
+    output: membershipOutput.extend({
+        added: z.boolean().describe("True once the user is a member."),
+    }),
+    async handler({ realm, userId, groupId }, { gateway }) {
+        await gateway.run((kc) => kc.users.addToGroup({ realm, id: userId, groupId }));
+        return {
+            data: { userId, groupId, realm, added: true },
+            summary: `User ${userId} is now a member of group ${groupId} in realm '${realm}'.`,
+        };
+    },
+});
+const userGroupRemove = defineTool({
+    name: "user_group_remove",
+    title: "Remove user from group",
+    description: "Remove a user from a group. This may revoke the roles the user inherits from the group. Requires confirm: true (ask the user first).",
+    kind: "destructive",
+    idempotent: true,
+    input: z.object({
+        realm: realmField,
+        userId: z.string().min(1).describe("ID (UUID) of the user."),
+        groupId: z.string().min(1).describe("ID (UUID) of the group."),
+    }),
+    output: membershipOutput.extend({
+        removed: z.boolean().describe("True once the user is no member."),
+    }),
+    async preview({ realm, userId, groupId }, { gateway }) {
+        const [user, group] = await gateway.run((kc) => Promise.all([
+            kc.users.findOne({ realm, id: userId }),
+            kc.groups.findOne({ realm, id: groupId }),
+        ]));
+        if (!user)
+            throw new ToolError("not_found", `User ${userId} does not exist in realm '${realm}'.`);
+        if (!group)
+            throw new ToolError("not_found", `Group ${groupId} does not exist in realm '${realm}'.`);
+        return `remove user '${user.username ?? userId}' from group '${group.path ?? group.name ?? groupId}' in realm '${realm}'.`;
+    },
+    async handler({ realm, userId, groupId }, { gateway }) {
+        await gateway.run((kc) => kc.users.delFromGroup({ realm, id: userId, groupId }));
+        return {
+            data: { userId, groupId, realm, removed: true },
+            summary: `User ${userId} is no longer a member of group ${groupId} in realm '${realm}'.`,
+        };
+    },
+});
+export const groupTools = [groupList, groupMembersList, userGroupAdd, userGroupRemove];
+//# sourceMappingURL=groups.js.map

package/dist/tools/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../src/tools/groups.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.js

@@ -0,0 +1,31 @@
+import { clientTools } from "./clients.js";
+import { eventTools } from "./events.js";
+import { groupTools } from "./groups.js";
+import { realmTools } from "./realms.js";
+import { roleTools } from "./roles.js";
+import { securityTools } from "./security.js";
+import { sessionTools } from "./sessions.js";
+import { userTools } from "./users.js";
+/** Every toolset and its tools. A new tool only needs to be added to its domain file. */
+export const TOOLSETS = {
+    core: [...realmTools, ...userTools],
+    groups: groupTools,
+    roles: roleTools,
+    clients: clientTools,
+    sessions: sessionTools,
+    events: eventTools,
+    security: securityTools,
+};
+/** Tools enabled by config: selected toolsets, minus write tools in read-only mode. */
+export function selectTools(config) {
+    return Object.entries(TOOLSETS)
+        .filter(([name]) => config.toolsets.has(name))
+        .flatMap(([, tools]) => tools)
+        .filter((tool) => !config.readOnly || tool.kind === "read");
+}
+export function registerTools(server, ctx) {
+    for (const tool of selectTools(ctx.config)) {
+        tool.register(server, ctx);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,yFAAyF;AACzF,MAAM,CAAC,MAAM,QAAQ,GAAmD;IACtE,IAAI,EAAE,CAAC,GAAG,UAAU,EAAE,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;IAClB,QAAQ,EAAE,aAAa;CACxB,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,MAA6C;IACvE,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;SAC5B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAmB,CAAC,CAAC;SAC5D,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;SAC7B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,GAAgB;IAC/D,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC"}

package/dist/tools/realms.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { isRealmAllowed } from "../guards.js";
+import { ToolError } from "../keycloak/errors.js";
+import { defineTool, pageOf, paginationShape, realmField, toPage } from "./shared.js";
+const realmSummary = z.object({
+    realm: z.string().describe("Realm name (use this as the `realm` argument of other tools)."),
+    displayName: z.string().optional().describe("Human-readable realm name."),
+    enabled: z.boolean().optional().describe("Whether the realm is enabled."),
+});
+const realmList = defineTool({
+    name: "realm_list",
+    title: "List realms",
+    description: "List the Keycloak realms visible to the configured admin account (restricted to KEYCLOAK_MCP_REALMS if set). Returns names only, not realm settings.",
+    kind: "read",
+    input: z.object(paginationShape),
+    output: pageOf(realmSummary),
+    async handler({ first, max }, { gateway, config }) {
+        const realms = await gateway.run((kc) => kc.realms.find({ briefRepresentation: true }));
+        const visible = realms
+            .filter((r) => r.realm !== undefined && isRealmAllowed(config, r.realm))
+            .sort((a, b) => (a.realm ?? "").localeCompare(b.realm ?? ""))
+            .map((r) => ({
+            realm: r.realm,
+            ...(r.displayName ? { displayName: r.displayName } : {}),
+            ...(r.enabled !== undefined ? { enabled: r.enabled } : {}),
+        }));
+        const page = toPage(visible.slice(first, first + max + 1), first, max);
+        return { data: page, summary: `Returned ${page.items.length} of ${visible.length} realm(s).` };
+    },
+});
+const realmGet = defineTool({
+    name: "realm_get",
+    title: "Get realm settings",
+    description: "Get a safe subset of a realm's settings (login, session, brute-force, password policy and event flags). SMTP credentials, keys and other secrets are never returned.",
+    kind: "read",
+    input: z.object({ realm: realmField }),
+    output: z.object({
+        realm: z.string().describe("Realm name."),
+        displayName: z.string().optional().describe("Human-readable realm name."),
+        enabled: z.boolean().optional().describe("Whether the realm is enabled."),
+        sslRequired: z.string().optional().describe("SSL requirement: all, external or none."),
+        registrationAllowed: z.boolean().optional().describe("Whether self-registration is allowed."),
+        loginWithEmailAllowed: z.boolean().optional().describe("Whether users may log in with e-mail."),
+        duplicateEmailsAllowed: z
+            .boolean()
+            .optional()
+            .describe("Whether duplicate e-mails are allowed."),
+        resetPasswordAllowed: z.boolean().optional().describe("Whether 'forgot password' is enabled."),
+        verifyEmail: z.boolean().optional().describe("Whether e-mail verification is required."),
+        bruteForceProtected: z.boolean().optional().describe("Whether brute-force detection is on."),
+        passwordPolicy: z.string().optional().describe("Password policy expression."),
+        otpPolicyType: z.string().optional().describe("OTP type: totp or hotp."),
+        accessTokenLifespan: z.number().optional().describe("Access token lifespan in seconds."),
+        ssoSessionIdleTimeout: z.number().optional().describe("SSO session idle timeout in seconds."),
+        ssoSessionMaxLifespan: z.number().optional().describe("SSO session max lifespan in seconds."),
+        eventsEnabled: z.boolean().optional().describe("Whether login events are stored."),
+        adminEventsEnabled: z.boolean().optional().describe("Whether admin events are stored."),
+    }),
+    async handler({ realm }, { gateway }) {
+        const rep = await gateway.run((kc) => kc.realms.findOne({ realm }));
+        if (!rep)
+            throw new ToolError("not_found", `Realm '${realm}' does not exist.`);
+        const data = toRealmSettings(rep, realm);
+        return { data, summary: `Returned settings of realm '${realm}'.` };
+    },
+});
+/** Field allowlist for realm settings; SMTP credentials, keys and secrets never pass. */
+export const REALM_SETTING_FIELDS = [
+    "displayName",
+    "enabled",
+    "sslRequired",
+    "registrationAllowed",
+    "loginWithEmailAllowed",
+    "duplicateEmailsAllowed",
+    "resetPasswordAllowed",
+    "verifyEmail",
+    "bruteForceProtected",
+    "passwordPolicy",
+    "otpPolicyType",
+    "accessTokenLifespan",
+    "ssoSessionIdleTimeout",
+    "ssoSessionMaxLifespan",
+    "eventsEnabled",
+    "adminEventsEnabled",
+];
+/** Safe subset of a realm representation, shared by realm_get and the realm resource. */
+export function toRealmSettings(rep, realm) {
+    const data = {
+        realm: rep.realm ?? realm,
+    };
+    for (const key of REALM_SETTING_FIELDS) {
+        const value = rep[key];
+        if (value !== undefined && value !== null)
+            Object.assign(data, { [key]: value });
+    }
+    return data;
+}
+export const realmTools = [realmList, realmGet];
+//# sourceMappingURL=realms.js.map

package/dist/tools/realms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realms.js","sourceRoot":"","sources":["../../src/tools/realms.ts"],"names":[],"mappings":"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"}