mcp-keycloak-admin 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,10 @@
 # mcp-keycloak-admin
 
+[![npm version](https://img.shields.io/npm/v/mcp-keycloak-admin.svg)](https://www.npmjs.com/package/mcp-keycloak-admin)
+[![CI](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml/badge.svg)](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml/badge.svg)](https://github.com/mrz1880/mcp-keycloak-admin/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server to
 administer a [Keycloak](https://www.keycloak.org) instance through its Admin
 REST API. Safe by default, configurable, and built with a clean, test-driven
@@ -7,9 +12,18 @@ architecture.
 
 Compatible with **Keycloak 26.x** (validated against 26.0.5).
 
-> **Project status:** early. The architecture, tooling and safety model are in
-> place and exercised by unit and integration tests. The exposed tool surface is
-> being grown incrementally — see [Tools](#tools) and [Roadmap](#roadmap).
+## Install
+
+No install needed — run it straight from npm with `npx`:
+
+```bash
+npx -y mcp-keycloak-admin
+```
+
+The server speaks MCP over stdio, so you normally wire it into an MCP client
+rather than running it by hand — see [Usage with an MCP client](#usage-with-an-mcp-client).
+New to it? The [Quickstart](docs/quickstart.md) spins up a local Keycloak and a
+client config in a couple of minutes.
 
 ## Why
 
@@ -64,6 +78,49 @@ Add the server to your MCP client configuration:
 See [docs/setup-keycloak.md](docs/setup-keycloak.md) to create the `mcp-admin`
 client and grant it the least-privilege roles it needs.
 
+### Multiple Keycloak instances
+
+Each server entry targets **one** Keycloak (one base URL + realm + auth). To
+manage several environments, add **one entry per instance** — each fully
+isolated, with its own credentials and guardrails:
+
+```json
+{
+  "mcpServers": {
+    "kc-preprod": {
+      "command": "npx",
+      "args": ["-y", "mcp-keycloak-admin"],
+      "env": {
+        "KEYCLOAK_BASE_URL": "https://preprod.example.com",
+        "KEYCLOAK_REALM": "Pandi-Panda-Preprod",
+        "AUTH_MODE": "service_account",
+        "KC_CLIENT_ID": "mcp-admin",
+        "KC_CLIENT_SECRET": "…",
+        "ALLOWED_REALMS": "Pandi-Panda-Preprod"
+      }
+    },
+    "kc-prod": {
+      "command": "npx",
+      "args": ["-y", "mcp-keycloak-admin"],
+      "env": {
+        "KEYCLOAK_BASE_URL": "https://auth.example.com",
+        "KEYCLOAK_REALM": "Pandi-Panda",
+        "AUTH_MODE": "service_account",
+        "KC_CLIENT_ID": "mcp-admin",
+        "KC_CLIENT_SECRET": "…",
+        "READ_ONLY": "true",
+        "ALLOWED_REALMS": "Pandi-Panda"
+      }
+    }
+  }
+}
+```
+
+The client namespaces the tools per server (e.g. `kc-prod:keycloak_user_delete`),
+so there's no risk of running an operation against the wrong environment. This
+is the recommended pattern: you can, for example, keep production `READ_ONLY`
+while preprod stays writable.
+
 ## Configuration
 
 | Variable            | Required              | Description                                              |
@@ -89,6 +146,11 @@ confirmation). Every tool carries the matching MCP annotations
 
 Currently implemented:
 
+> **Note:** this table tracks the `main` branch, which can run ahead of the
+> latest npm release shown by the version badge above. To confirm what's
+> available in your install, check `npm view mcp-keycloak-admin version` and pin
+> `mcp-keycloak-admin@latest`.
+
 | Tool                                        | Level | Description                                           |
 | ------------------------------------------- | ----- | ----------------------------------------------------- |
 | `keycloak_user_search`                      | R     | Search realm users by email, username or free text.   |
@@ -105,7 +167,14 @@ Currently implemented:
 | `keycloak_user_roles_get`                   | R     | List a user's realm roles.                            |
 | `keycloak_user_role_assign`                 | W     | Grant a realm role to a user.                         |
 | `keycloak_user_role_unassign`               | D     | Revoke a realm role from a user.                      |
+| `keycloak_client_roles_list`                | R     | List the roles defined on a client.                   |
+| `keycloak_user_client_roles_get`            | R     | List a user's client roles.                           |
+| `keycloak_user_client_role_assign`          | W     | Grant a client role to a user.                        |
+| `keycloak_user_client_role_unassign`        | D     | Revoke a client role from a user.                     |
 | `keycloak_client_list`                      | R     | List the realm clients.                               |
+| `keycloak_client_create`                    | W     | Create a realm client.                                |
+| `keycloak_client_update`                    | W     | Update a client (enabled, public, redirect URIs).     |
+| `keycloak_client_delete`                    | D     | Delete a client.                                      |
 | `keycloak_client_get`                       | R     | Fetch a client by its clientId.                       |
 | `keycloak_client_get_secret`                | R     | Read a client secret (masked unless `reveal`).        |
 | `keycloak_client_scopes_list`               | R     | List the realm's client scopes.                       |
@@ -164,6 +233,8 @@ npm run check         # typecheck + lint + format check + unit tests
 npm run build         # bundle to dist/
 ```
 
+Releases are automated — see [docs/releasing.md](docs/releasing.md).
+
 ## Contributing
 
 Contributions are welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/index.js

@@ -451,7 +451,7 @@ var KeycloakClientRepository = class {
   }
   client;
   async list() {
-    const raw = await this.client.getJson("/clients");
+    const raw = await this.client.list("/clients");
     return raw.map(toSummary);
   }
   async findByClientId(clientId) {
@@ -473,6 +473,30 @@ var KeycloakClientRepository = class {
     );
     return ClientSecret.fromString(raw.value);
   }
+  create(client) {
+    return this.client.post("/clients", {
+      clientId: client.clientId.toString(),
+      enabled: client.enabled,
+      publicClient: client.publicClient,
+      redirectUris: client.redirectUris
+    });
+  }
+  update(uuid, changes) {
+    const body = {};
+    if (changes.enabled !== void 0) {
+      body.enabled = changes.enabled;
+    }
+    if (changes.publicClient !== void 0) {
+      body.publicClient = changes.publicClient;
+    }
+    if (changes.redirectUris !== void 0) {
+      body.redirectUris = changes.redirectUris;
+    }
+    return this.client.put(`/clients/${uuid.toString()}`, body);
+  }
+  delete(uuid) {
+    return this.client.delete(`/clients/${uuid.toString()}`);
+  }
 };
 
 // src/infrastructure/keycloak/authentication-repository.ts
@@ -963,7 +987,7 @@ var KeycloakGroupRepository = class {
   }
   client;
   async list() {
-    const raw = await this.client.getJson("/groups");
+    const raw = await this.client.list("/groups");
     return raw.map(toGroup);
   }
   create(name) {
@@ -1121,7 +1145,7 @@ var KeycloakRoleRepository = class {
   }
   client;
   async listRealmRoles() {
-    const raw = await this.client.getJson("/roles");
+    const raw = await this.client.list("/roles");
     return raw.map(toRole);
   }
   async findRealmRole(name) {
@@ -1154,6 +1178,43 @@ var KeycloakRoleRepository = class {
       [toRepresentation(role)]
     );
   }
+  async listClientRoles(clientUuid) {
+    const raw = await this.client.list(
+      `/clients/${clientUuid.toString()}/roles`
+    );
+    return raw.map(toRole);
+  }
+  async findClientRole(clientUuid, name) {
+    try {
+      const raw = await this.client.getJson(
+        `/clients/${clientUuid.toString()}/roles/${encodeURIComponent(name.toString())}`
+      );
+      return toRole(raw);
+    } catch (error) {
+      if (error instanceof KeycloakError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async listUserClientRoles(userId, clientUuid) {
+    const raw = await this.client.getJson(
+      `/users/${userId.toString()}/role-mappings/clients/${clientUuid.toString()}`
+    );
+    return raw.map(toRole);
+  }
+  assignClientRole(userId, clientUuid, role) {
+    return this.client.post(
+      `/users/${userId.toString()}/role-mappings/clients/${clientUuid.toString()}`,
+      [toRepresentation(role)]
+    );
+  }
+  removeClientRole(userId, clientUuid, role) {
+    return this.client.delete(
+      `/users/${userId.toString()}/role-mappings/clients/${clientUuid.toString()}`,
+      [toRepresentation(role)]
+    );
+  }
 };
 
 // src/infrastructure/mcp/auth-tools.ts
@@ -1646,6 +1707,42 @@ function buildClientScopeTools(deps) {
 // src/infrastructure/mcp/client-tools.ts
 import { z as z5 } from "zod";
 
+// src/application/clients/create-client.use-case.ts
+var CreateClientUseCase = class {
+  constructor(clients) {
+    this.clients = clients;
+  }
+  clients;
+  execute(client) {
+    return this.clients.create(client);
+  }
+};
+
+// src/application/clients/delete-client.use-case.ts
+var DeleteClientUseCase = class {
+  constructor(clients, confirmer) {
+    this.clients = clients;
+    this.confirmer = confirmer;
+  }
+  clients;
+  confirmer;
+  async execute(clientId) {
+    const client = await this.clients.findByClientId(clientId);
+    if (client === null) {
+      return { deleted: false, reason: "Client not found" };
+    }
+    const operation = DestructiveOperation.of(
+      `Delete client ${clientId.toString()}`,
+      "Removes the client and everything attached to it (roles, scopes, service account). Applications using it stop working. Irreversible."
+    );
+    if (!await this.confirmer.confirm(operation)) {
+      return { deleted: false, reason: "Operation not confirmed" };
+    }
+    await this.clients.delete(client.uuid);
+    return { deleted: true };
+  }
+};
+
 // src/application/clients/get-client-secret.use-case.ts
 var GetClientSecretUseCase = class {
   constructor(clients) {
@@ -1708,6 +1805,22 @@ var RegenerateClientSecretUseCase = class {
   }
 };
 
+// src/application/clients/update-client.use-case.ts
+var UpdateClientUseCase = class {
+  constructor(clients) {
+    this.clients = clients;
+  }
+  clients;
+  async execute(input) {
+    const client = await this.clients.findByClientId(input.clientId);
+    if (client === null) {
+      return { updated: false, reason: "Client not found" };
+    }
+    await this.clients.update(client.uuid, input.changes);
+    return { updated: true };
+  }
+};
+
 // src/infrastructure/mcp/client-tools.ts
 function serializeClient(client) {
   return {
@@ -1811,12 +1924,110 @@ function regenerateClientSecretTool(deps) {
     }
   };
 }
+function readStringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function createClientTool(deps) {
+  return {
+    name: "keycloak_client_create",
+    title: "Create client",
+    description: "Create a realm client.",
+    level: "write" /* Write */,
+    inputSchema: {
+      clientId: z5.string(),
+      enabled: z5.boolean().optional(),
+      publicClient: z5.boolean().optional(),
+      redirectUris: z5.array(z5.string()).optional()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false
+    },
+    async handler(args) {
+      await new CreateClientUseCase(deps.clientRepository).execute({
+        clientId: ClientId.fromString(String(args.clientId)),
+        enabled: args.enabled !== false,
+        publicClient: args.publicClient === true,
+        redirectUris: readStringArray(args.redirectUris)
+      });
+      return textResult(`Client "${String(args.clientId)}" created.`);
+    }
+  };
+}
+function updateClientTool(deps) {
+  return {
+    name: "keycloak_client_update",
+    title: "Update client",
+    description: "Update a client's enabled, public flag or redirect URIs.",
+    level: "write" /* Write */,
+    inputSchema: {
+      clientId: z5.string(),
+      enabled: z5.boolean().optional(),
+      publicClient: z5.boolean().optional(),
+      redirectUris: z5.array(z5.string()).optional()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true
+    },
+    async handler(args) {
+      const changes = {};
+      if (typeof args.enabled === "boolean") {
+        changes.enabled = args.enabled;
+      }
+      if (typeof args.publicClient === "boolean") {
+        changes.publicClient = args.publicClient;
+      }
+      if (Array.isArray(args.redirectUris)) {
+        changes.redirectUris = readStringArray(args.redirectUris);
+      }
+      const result = await new UpdateClientUseCase(
+        deps.clientRepository
+      ).execute({
+        clientId: ClientId.fromString(String(args.clientId)),
+        changes
+      });
+      return textResult(
+        result.updated ? `Client "${String(args.clientId)}" updated.` : `Not updated: ${result.reason ?? "unknown reason"}`
+      );
+    }
+  };
+}
+function deleteClientTool(deps) {
+  return {
+    name: "keycloak_client_delete",
+    title: "Delete client",
+    description: "Delete a client. Requires confirmation.",
+    level: "destructive" /* Destructive */,
+    inputSchema: { clientId: z5.string(), confirm: z5.boolean().optional() },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false
+    },
+    async handler(args) {
+      const confirmer = deps.confirmers.create(args.confirm === true);
+      const result = await new DeleteClientUseCase(
+        deps.clientRepository,
+        confirmer
+      ).execute(ClientId.fromString(String(args.clientId)));
+      return textResult(
+        result.deleted ? `Client "${String(args.clientId)}" deleted.` : `Not deleted: ${result.reason ?? "unknown reason"}`
+      );
+    }
+  };
+}
 function buildClientTools(deps) {
   return [
     listClientsTool(deps),
     getClientTool(deps),
     getClientSecretTool(deps),
-    regenerateClientSecretTool(deps)
+    createClientTool(deps),
+    updateClientTool(deps),
+    regenerateClientSecretTool(deps),
+    deleteClientTool(deps)
   ];
 }
 
@@ -2708,6 +2919,28 @@ function buildIdpTools(deps) {
 // src/infrastructure/mcp/role-tools.ts
 import { z as z10 } from "zod";
 
+// src/application/roles/assign-client-role.use-case.ts
+var AssignClientRoleUseCase = class {
+  constructor(clients, roles) {
+    this.clients = clients;
+    this.roles = roles;
+  }
+  clients;
+  roles;
+  async execute(input) {
+    const client = await this.clients.findByClientId(input.clientId);
+    if (client === null) {
+      return { assigned: false, reason: "Client not found" };
+    }
+    const role = await this.roles.findClientRole(client.uuid, input.role);
+    if (role === null) {
+      return { assigned: false, reason: "Role not found" };
+    }
+    await this.roles.assignClientRole(input.userId, client.uuid, role);
+    return { assigned: true };
+  }
+};
+
 // src/application/roles/assign-user-role.use-case.ts
 var AssignUserRoleUseCase = class {
   constructor(roles) {
@@ -2724,6 +2957,23 @@ var AssignUserRoleUseCase = class {
   }
 };
 
+// src/application/roles/get-user-client-roles.use-case.ts
+var GetUserClientRolesUseCase = class {
+  constructor(clients, roles) {
+    this.clients = clients;
+    this.roles = roles;
+  }
+  clients;
+  roles;
+  async execute(input) {
+    const client = await this.clients.findByClientId(input.clientId);
+    if (client === null) {
+      return null;
+    }
+    return this.roles.listUserClientRoles(input.userId, client.uuid);
+  }
+};
+
 // src/application/roles/get-user-roles.use-case.ts
 var GetUserRolesUseCase = class {
   constructor(roles) {
@@ -2735,6 +2985,23 @@ var GetUserRolesUseCase = class {
   }
 };
 
+// src/application/roles/list-client-roles.use-case.ts
+var ListClientRolesUseCase = class {
+  constructor(clients, roles) {
+    this.clients = clients;
+    this.roles = roles;
+  }
+  clients;
+  roles;
+  async execute(clientId) {
+    const client = await this.clients.findByClientId(clientId);
+    if (client === null) {
+      return null;
+    }
+    return this.roles.listClientRoles(client.uuid);
+  }
+};
+
 // src/application/roles/list-realm-roles.use-case.ts
 var ListRealmRolesUseCase = class {
   constructor(roles) {
@@ -2746,6 +3013,37 @@ var ListRealmRolesUseCase = class {
   }
 };
 
+// src/application/roles/unassign-client-role.use-case.ts
+var UnassignClientRoleUseCase = class {
+  constructor(clients, roles, confirmer) {
+    this.clients = clients;
+    this.roles = roles;
+    this.confirmer = confirmer;
+  }
+  clients;
+  roles;
+  confirmer;
+  async execute(input) {
+    const client = await this.clients.findByClientId(input.clientId);
+    if (client === null) {
+      return { removed: false, reason: "Client not found" };
+    }
+    const role = await this.roles.findClientRole(client.uuid, input.role);
+    if (role === null) {
+      return { removed: false, reason: "Role not found" };
+    }
+    const operation = DestructiveOperation.of(
+      `Remove client role ${input.role.toString()} (client ${input.clientId.toString()}) from user ${input.userId.toString()}`,
+      "The user immediately loses the permissions granted by this client role."
+    );
+    if (!await this.confirmer.confirm(operation)) {
+      return { removed: false, reason: "Operation not confirmed" };
+    }
+    await this.roles.removeClientRole(input.userId, client.uuid, role);
+    return { removed: true };
+  }
+};
+
 // src/application/roles/unassign-user-role.use-case.ts
 var UnassignUserRoleUseCase = class {
   constructor(roles, confirmer) {
@@ -2875,12 +3173,130 @@ function unassignUserRoleTool(deps) {
     }
   };
 }
+function listClientRolesTool(deps) {
+  return {
+    name: "keycloak_client_roles_list",
+    title: "List client roles",
+    description: "List the roles defined on a client.",
+    level: "read" /* Read */,
+    inputSchema: { clientId: z10.string() },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    },
+    async handler(args) {
+      const roles = await new ListClientRolesUseCase(
+        deps.clientRepository,
+        deps.roleRepository
+      ).execute(ClientId.fromString(String(args.clientId)));
+      return textResult(
+        roles === null ? "Client not found." : JSON.stringify(roles.map(serializeRole), null, 2)
+      );
+    }
+  };
+}
+function getUserClientRolesTool(deps) {
+  return {
+    name: "keycloak_user_client_roles_get",
+    title: "Get a user's client roles",
+    description: "List the client roles assigned to a user for a client.",
+    level: "read" /* Read */,
+    inputSchema: { userId: z10.string(), clientId: z10.string() },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    },
+    async handler(args) {
+      const roles = await new GetUserClientRolesUseCase(
+        deps.clientRepository,
+        deps.roleRepository
+      ).execute({
+        userId: UserId.fromString(String(args.userId)),
+        clientId: ClientId.fromString(String(args.clientId))
+      });
+      return textResult(
+        roles === null ? "Client not found." : JSON.stringify(roles.map(serializeRole), null, 2)
+      );
+    }
+  };
+}
+function assignClientRoleTool(deps) {
+  return {
+    name: "keycloak_user_client_role_assign",
+    title: "Assign a client role to a user",
+    description: "Grant a client role to a user.",
+    level: "write" /* Write */,
+    inputSchema: {
+      userId: z10.string(),
+      clientId: z10.string(),
+      role: z10.string()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true
+    },
+    async handler(args) {
+      const result = await new AssignClientRoleUseCase(
+        deps.clientRepository,
+        deps.roleRepository
+      ).execute({
+        userId: UserId.fromString(String(args.userId)),
+        clientId: ClientId.fromString(String(args.clientId)),
+        role: RoleName.fromString(String(args.role))
+      });
+      return textResult(
+        result.assigned ? `Client role "${String(args.role)}" assigned.` : `Not assigned: ${result.reason ?? "unknown reason"}`
+      );
+    }
+  };
+}
+function unassignClientRoleTool(deps) {
+  return {
+    name: "keycloak_user_client_role_unassign",
+    title: "Remove a client role from a user",
+    description: "Revoke a client role from a user. Requires confirmation.",
+    level: "destructive" /* Destructive */,
+    inputSchema: {
+      userId: z10.string(),
+      clientId: z10.string(),
+      role: z10.string(),
+      confirm: z10.boolean().optional()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false
+    },
+    async handler(args) {
+      const confirmer = deps.confirmers.create(args.confirm === true);
+      const result = await new UnassignClientRoleUseCase(
+        deps.clientRepository,
+        deps.roleRepository,
+        confirmer
+      ).execute({
+        userId: UserId.fromString(String(args.userId)),
+        clientId: ClientId.fromString(String(args.clientId)),
+        role: RoleName.fromString(String(args.role))
+      });
+      return textResult(
+        result.removed ? `Client role "${String(args.role)}" removed.` : `Not removed: ${result.reason ?? "unknown reason"}`
+      );
+    }
+  };
+}
 function buildRoleTools(deps) {
   return [
     listRealmRolesTool(deps),
     getUserRolesTool(deps),
+    listClientRolesTool(deps),
+    getUserClientRolesTool(deps),
     assignUserRoleTool(deps),
-    unassignUserRoleTool(deps)
+    assignClientRoleTool(deps),
+    unassignUserRoleTool(deps),
+    unassignClientRoleTool(deps)
   ];
 }
 
@@ -3486,7 +3902,7 @@ function createServer(config) {
   const tools = filterTools(
     [
       ...buildUserTools({ userRepository, confirmers }),
-      ...buildRoleTools({ roleRepository, confirmers }),
+      ...buildRoleTools({ roleRepository, clientRepository, confirmers }),
       ...buildClientTools({ clientRepository, confirmers }),
       ...buildClientScopeTools({
         clientRepository,