keycloak-model-context-protocol 0.0.2 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Christoph Englisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,42 +1,102 @@
 # Keycloak MCP Server
 
-A Model Context Protocol server for Keycloak administration, providing tools to manage users and realms.
+[![npm version](https://img.shields.io/npm/v/keycloak-model-context-protocol.svg)](https://www.npmjs.com/package/keycloak-model-context-protocol)
+[![CI](https://github.com/ChristophEnglisch/keycloak-model-context-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/ChristophEnglisch/keycloak-model-context-protocol/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Keycloak administration**. It lets an AI assistant such as Claude manage users, groups, roles and sessions, and inspect clients, events and the security posture of your realms, through the Keycloak Admin REST API, with least-privilege authentication and guardrails around every write.
+
+> [!WARNING]
+> This server acts with the permissions of the Keycloak account you give it. Use a **dedicated service-account client with only the roles you need**, never the bootstrap admin. Destructive tools ask for confirmation by default, and a read-only mode is available. See [Security](#security).
+
+## Highlights
+
+- **24 tools in 7 toolsets**, enabled per toolset. The default set (`core`, `groups`, `roles`) is small; everything else is opt-in.
+- **Least-privilege auth.** `client_credentials` with a service account is the recommended grant; the password grant stays available. No credential defaults, so a missing setting fails fast.
+- **Guardrails.** Read-only mode, realm allowlist, write protection for the `master` realm, and a preview-then-`confirm: true` flow for destructive operations.
+- **4 guided prompts** (onboarding, offboarding, security audit, failed-login investigation) and **MCP resources** for realms and users, with realm-name completion.
+- **Structured, paginated output** with output schemas; secrets and credentials are never returned or logged.
+- Works with Claude Desktop, Claude Code, VS Code, Cursor and any stdio MCP client. Requires Node.js 22 or newer.
+
+## How it works
+
+Your MCP client starts the server as a local child process and talks to it over stdio. Every tool call passes the guards, then goes through a single gateway that owns the Keycloak login and caches the access token.
+
+```mermaid
+flowchart LR
+    subgraph Host["Your machine"]
+        Client["MCP client<br/>(Claude Desktop, Claude Code,<br/>VS Code, Cursor, ...)"]
+        subgraph Server["keycloak-model-context-protocol (Node.js)"]
+            Guards["Guards<br/>read-only, realm allowlist,<br/>master protection, confirmation"]
+            Toolsets["Toolsets, prompts, resources<br/>core, groups, roles, clients,<br/>sessions, events, security"]
+            Gateway["Gateway<br/>login and token cache"]
+            Guards --> Toolsets --> Gateway
+        end
+        Client <-->|"JSON-RPC over stdio"| Guards
+    end
+
+    subgraph KC["Keycloak"]
+        Token["Token endpoint"]
+        Admin["Admin REST API<br/>/admin/realms/..."]
+    end
+
+    Gateway -->|"client_credentials or password grant"| Token
+    Gateway -->|"Bearer token"| Admin
+```
 
-## Features
+### What a destructive call looks like
+
+A destructive tool never acts on the first call. It returns a preview of what would happen and changes nothing. Only after you approve does the assistant repeat the call with `confirm: true`.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant LLM as MCP client / LLM
+    participant MCP as Keycloak MCP server
+    participant KC as Keycloak
+
+    User->>LLM: "Delete user bob from realm demo"
+    LLM->>MCP: user_delete (realm, userId)
+    MCP->>KC: GET user (for the preview)
+    KC-->>MCP: user data
+    MCP-->>LLM: isError, "Confirmation required. This would: permanently delete user bob ... Nothing was changed."
+    LLM->>User: "This will permanently delete bob. Proceed?"
+    User->>LLM: "Yes"
+    LLM->>MCP: user_delete (realm, userId, confirm: true)
+    MCP->>KC: DELETE user
+    KC-->>MCP: 204 No Content
+    MCP-->>LLM: deleted: true
+    LLM-->>User: "User bob was deleted."
+```
 
-- Create new users in specific realms
-- Delete users from realms
-- List available realms
-- List users in specific realms
+## Quick start
 
-## Installation
+**Requirements:** Node.js 22 or newer, a Keycloak server your machine can reach (tested with Keycloak 24.0 to 26.8), and an MCP client.
 
-### Via NPM (Recommended)
+### 1. Prepare Keycloak (3 steps)
 
-The server is available as an NPM package:
-```bash
-# Direct usage with npx
-npx -y keycloak-model-context-protocol
+In the realm you want to administer (here `demo`):
+1. **Create a client** `mcp-admin` with _Client authentication_ **on** and only _Service accounts roles_ enabled (turn off _Standard flow_ and _Direct access grants_).
+2. **Assign roles.** On the client's _Service accounts roles_ tab, assign client roles of `realm-management`. For a first read-only trial: `view-users`, `query-users`, `query-groups`, `view-realm`.
+3. **Copy the secret** from the client's _Credentials_ tab.
 
-# Or global installation
-npm install -g keycloak-model-context-protocol
-```
+Step-by-step instructions with Admin Console click paths, `kcadm.sh` commands and a local Docker Keycloak: [docs/getting-started.md](docs/getting-started.md).
 
-### Local Development Setup
+### 2. Configure your MCP client
 
-If you want to develop or modify the server:
+Example for Claude Code (other clients: [docs/clients.md](docs/clients.md)):
 
 ```bash
-git clone <repository-url>
-cd keycloak-model-context-protocol
-npm install
-npm run build
+claude mcp add --transport stdio \
+  --env KEYCLOAK_URL=https://keycloak.example.com \
+  --env KEYCLOAK_AUTH_REALM=demo \
+  --env KEYCLOAK_CLIENT_ID=mcp-admin \
+  --env KEYCLOAK_CLIENT_SECRET="$KEYCLOAK_CLIENT_SECRET" \
+  keycloak -- npx -y keycloak-model-context-protocol
 ```
 
-## Configuration
-
-### Using NPM Package (Recommended)
-Configure the server in your Claude Desktop configuration file:
+Or as JSON (Claude Desktop, `claude_desktop_config.json`):
 
 ```json
 {
@@ -45,89 +105,116 @@ Configure the server in your Claude Desktop configuration file:
       "command": "npx",
       "args": ["-y", "keycloak-model-context-protocol"],
       "env": {
-        "KEYCLOAK_URL": "http://localhost:8080",
-        "KEYCLOAK_ADMIN": "admin",
-        "KEYCLOAK_ADMIN_PASSWORD": "admin"
+        "KEYCLOAK_URL": "https://keycloak.example.com",
+        "KEYCLOAK_AUTH_REALM": "demo",
+        "KEYCLOAK_CLIENT_ID": "mcp-admin",
+        "KEYCLOAK_CLIENT_SECRET": "<client-secret>"
       }
     }
   }
 }
 ```
 
-### For Local Development
-```json
-{
-  "mcpServers": {
-    "keycloak": {
-      "command": "node",
-      "args": ["path/to/dist/index.js"],
-      "env": {
-        "KEYCLOAK_URL": "http://localhost:8080",
-        "KEYCLOAK_ADMIN": "admin",
-        "KEYCLOAK_ADMIN_PASSWORD": "admin"
-      }
-    }
-  }
-}
-```
-
-## Available Tools
-
-### create-user
-Creates a new user in a specified realm.
-
-**Inputs**:
-- `realm`: The realm name
-- `username`: Username for the new user
-- `email`: Email address for the user
-- `firstName`: User's first name
-- `lastName`: User's last name
+### 3. Ask your first question
 
-### delete-user
-Deletes a user from a specified realm.
+> _List the realms you can access, then show me the first 10 users of realm demo._
 
-**Inputs**:
-- `realm`: The realm name
-- `userId`: The ID of the user to delete
+If you get an answer, you are done. If not, see [docs/troubleshooting.md](docs/troubleshooting.md).
 
-### list-realms
-Lists all available realms.
-
-### list-users
-Lists all users in a specified realm.
-
-**Inputs**:
-- `realm`: The realm name
-
-## Development
-
-```bash
-npm run watch
-```
-
-## Testing
-
-To test the server using MCP Inspector:
-
-```bash
-npx -y @modelcontextprotocol/inspector npx -y keycloak-model-context-protocol
-```
-
-## Deployment
-
-### NPM Package
-
-This project is automatically published to [NPM](https://www.npmjs.com/package/keycloak-model-context-protocol) via GitHub Actions when a new release is published on GitHub.
-
-#### Setup Requirements for Deployment
-
-1. Create NPM account and get access token
-2. Add NPM_TOKEN secret to GitHub repository
-   - Go to repository Settings > Secrets
-   - Add new secret named `NPM_TOKEN`
-   - Paste your NPM access token as the value
-
-## Prerequisites
+## Configuration
 
-- Node.js 18 or higher
-- Running Keycloak instance
+All settings are environment variables. Only `KEYCLOAK_URL` and one set of credentials are required.
+
+| Variable                                        | Default             | Purpose                                                        |
+| ----------------------------------------------- | ------------------- | -------------------------------------------------------------- |
+| `KEYCLOAK_URL`                                  | (required)          | Base URL of the Keycloak server                                |
+| `KEYCLOAK_AUTH_REALM`                           | `master`            | Realm where the login account or client lives                  |
+| `KEYCLOAK_CLIENT_ID` / `KEYCLOAK_CLIENT_SECRET` | none                | `client_credentials` login (recommended)                       |
+| `KEYCLOAK_USERNAME` / `KEYCLOAK_PASSWORD`       | none                | Password grant login (client defaults to `admin-cli`)          |
+| `KEYCLOAK_GRANT_TYPE`                           | auto                | `client_credentials` or `password`; detected from what you set |
+| `KEYCLOAK_MCP_TOOLSETS`                         | `core,groups,roles` | Enabled toolsets, or `all`                                     |
+| `KEYCLOAK_MCP_READ_ONLY`                        | `false`             | Register read-only tools only                                  |
+| `KEYCLOAK_MCP_REALMS`                           | all                 | Comma-separated allowlist of target realms                     |
+| `KEYCLOAK_MCP_ALLOW_MASTER_WRITE`               | `false`             | Allow write tools in the `master` realm                        |
+| `KEYCLOAK_MCP_REQUIRE_CONFIRMATION`             | `true`              | Destructive tools need `confirm: true`                         |
+| `KEYCLOAK_MCP_TIMEOUT_MS`                       | `30000`             | HTTP timeout for Keycloak requests                             |
+| `KEYCLOAK_MCP_LOG_LEVEL`                        | `info`              | `debug`, `info`, `warn` or `error` (stderr)                    |
+
+Full reference with examples, validation rules and the tool-to-role matrix: [docs/configuration.md](docs/configuration.md).
+
+## Toolsets and tools
+
+Tools are named `<domain>_<verb>`. Only the **default** toolsets are enabled unless you set `KEYCLOAK_MCP_TOOLSETS`. In read-only mode only tools of kind _read_ are registered.
+
+| Toolset    | Default | Tools                                                                                                                                      |
+| ---------- | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `core`     |   yes   | `realm_list`, `realm_get`, `user_search`, `user_get`, `user_create`, `user_update`, `user_delete` (destructive), `user_send_actions_email` |
+| `groups`   |   yes   | `group_list`, `group_members_list`, `user_group_add`, `user_group_remove` (destructive)                                                    |
+| `roles`    |   yes   | `role_list`, `user_roles_list`, `user_role_assign` (confirmation for admin roles), `user_role_revoke` (destructive)                        |
+| `clients`  |   no    | `client_list`, `client_get`                                                                                                                |
+| `sessions` |   no    | `user_sessions_list`, `user_logout` (destructive)                                                                                          |
+| `events`   |   no    | `event_list`, `admin_event_list`                                                                                                           |
+| `security` |   no    | `user_brute_force_status`, `user_brute_force_unlock`                                                                                       |
+
+Details for every tool (parameters, outputs, required roles): [docs/tools-reference.md](docs/tools-reference.md).
+
+## Prompts and resources
+
+**Prompts** are guided workflows built on the tools. They appear in your client's prompt picker (in Claude Code as slash commands). The `realm` argument autocompletes.
+
+| Prompt                      | What it does                                                                      |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| `onboard_employee`          | Create a user, add groups and roles, send the welcome e-mail                      |
+| `offboard_employee`         | Review, end sessions and disable a departing employee's account (does not delete) |
+| `audit_realm_security`      | Read-only security review with prioritized findings                               |
+| `investigate_failed_logins` | Analyze failed logins and lockout status without changing anything                |
+
+**Resources** are read-only JSON documents, filtered by the same realm allowlist:
+
+| URI                                          | Content                                                                                  |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `keycloak://realms`                          | Names of accessible realms                                                               |
+| `keycloak://realms/{realm}`                  | Safe subset of the realm settings                                                        |
+| `keycloak://realms/{realm}/security-summary` | Brute-force, password policy, SSL, OTP, event flags, client exposure counts (no secrets) |
+| `keycloak://realms/{realm}/users/{userId}`   | One user's basic fields (no attributes, no credentials)                                  |
+
+## Security
+
+- **Least privilege first.** Use a service-account client scoped to one realm with only the `realm-management` roles you need. A role matrix is in [docs/configuration.md](docs/configuration.md#minimal-roles-per-tool).
+- **Destructive operations need confirmation** (`KEYCLOAK_MCP_REQUIRE_CONFIRMATION=true`), and granting administrative roles does too.
+- **Blast-radius limits:** `KEYCLOAK_MCP_READ_ONLY`, `KEYCLOAK_MCP_REALMS`, and write protection for `master` (off by default).
+- **No secrets in output or logs.** Credentials are masked on stderr; tools never return client secrets, user credentials or attributes.
+- **Prompt injection:** treat names and descriptions coming from Keycloak as data. The shipped prompts say so explicitly; keep write tools disabled when you do not need them.
+
+Threat model, hardening checklist and how to report a vulnerability: [docs/security.md](docs/security.md) and [SECURITY.md](SECURITY.md).
+
+## Example prompts
+
+- "Which realms can you see? Show me the settings of realm `demo`."
+- "Find all users in `demo` whose e-mail ends with `@example.com` and who are disabled."
+- "Create user `jdoe` (Jane Doe, jane@example.com) in `demo`, add her to group `engineering` and send her an e-mail to set a password."
+- "Who is in the group `ops`, and which roles does `alice` have, including composite roles?"
+- "Run the `audit_realm_security` prompt for `demo`." _(needs `clients` and `events` toolsets for the full audit)_
+- "There were many failed logins last night. Investigate realm `demo`."
+- "Offboard `bob` in `demo`: end his sessions and disable the account."
+
+## Documentation
+
+| Document                                           | Content                                                         |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| [docs/getting-started.md](docs/getting-started.md) | Local Keycloak, service-account setup, first run, MCP Inspector |
+| [docs/configuration.md](docs/configuration.md)     | Environment reference, role matrix, role profiles, TLS          |
+| [docs/clients.md](docs/clients.md)                 | Claude Desktop, Claude Code, VS Code, Cursor, generic clients   |
+| [docs/tools-reference.md](docs/tools-reference.md) | Every tool in detail                                            |
+| [docs/security.md](docs/security.md)               | Threat model and hardening                                      |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Symptoms, causes, fixes                                         |
+| [docs/architecture.md](docs/architecture.md)       | Components, flows, design decisions                             |
+| [CHANGELOG.md](CHANGELOG.md)                       | Release notes                                                   |
+
+## Upgrade from 0.x
+
+Version 1.0 changes the defaults: credentials are required (no `admin`/`admin` fallback), destructive tools ask for confirmation, and the tools were renamed to `<domain>_<verb>` (for example `create-user` became `user_create`, `delete-user` became `user_delete`). The old `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` variables still work but are deprecated. See the [migration guide](docs/migration-1.0.md).
+
+## Contributing and license
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Released under the [MIT License](LICENSE).

package/dist/config.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { LOG_LEVELS } from "./logging.js";
+export const TOOLSET_NAMES = [
+    "core",
+    "groups",
+    "roles",
+    "clients",
+    "sessions",
+    "events",
+    "security",
+];
+export const DEFAULT_TOOLSETS = ["core", "groups", "roles"];
+export class ConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid configuration:\n${issues.map((issue) => `  - ${issue}`).join("\n")}`);
+        this.name = "ConfigError";
+        this.issues = issues;
+    }
+}
+const blankToUndefined = (value) => {
+    if (typeof value !== "string")
+        return value;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+};
+const optionalString = z.preprocess(blankToUndefined, z.string().optional());
+const flag = (fallback) => z.preprocess(blankToUndefined, z.stringbool().default(fallback));
+const commaList = z.preprocess(blankToUndefined, z
+    .string()
+    .optional()
+    .transform((value) => (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)));
+const EnvSchema = z.object({
+    KEYCLOAK_URL: z.preprocess(blankToUndefined, z
+        .string({ error: "is required (base URL of the Keycloak server)" })
+        .pipe(z.url({ protocol: /^https?$/, error: "must be a valid http(s) URL" }))),
+    KEYCLOAK_AUTH_REALM: z.preprocess(blankToUndefined, z.string().default("master")),
+    KEYCLOAK_CLIENT_ID: optionalString,
+    KEYCLOAK_CLIENT_SECRET: optionalString,
+    KEYCLOAK_USERNAME: optionalString,
+    KEYCLOAK_PASSWORD: optionalString,
+    KEYCLOAK_ADMIN: optionalString,
+    KEYCLOAK_ADMIN_PASSWORD: optionalString,
+    KEYCLOAK_GRANT_TYPE: z.preprocess(blankToUndefined, z
+        .enum(["client_credentials", "password"], {
+        error: "must be 'client_credentials' or 'password'",
+    })
+        .optional()),
+    KEYCLOAK_MCP_READ_ONLY: flag(false),
+    KEYCLOAK_MCP_REALMS: commaList,
+    KEYCLOAK_MCP_ALLOW_MASTER_WRITE: flag(false),
+    KEYCLOAK_MCP_TOOLSETS: commaList,
+    KEYCLOAK_MCP_REQUIRE_CONFIRMATION: flag(true),
+    KEYCLOAK_MCP_TIMEOUT_MS: z.preprocess(blankToUndefined, z.coerce
+        .number({ error: "must be a number of milliseconds" })
+        .int({ error: "must be an integer" })
+        .min(1, { error: "must be at least 1" })
+        .default(30_000)),
+    KEYCLOAK_MCP_LOG_LEVEL: z.preprocess(blankToUndefined, z.enum(LOG_LEVELS, { error: `must be one of: ${LOG_LEVELS.join(", ")}` }).default("info")),
+});
+function resolveToolsets(names, issues) {
+    if (names.length === 0)
+        return new Set(DEFAULT_TOOLSETS);
+    if (names.includes("all"))
+        return new Set(TOOLSET_NAMES);
+    const result = new Set();
+    for (const name of names) {
+        if (TOOLSET_NAMES.includes(name)) {
+            result.add(name);
+        }
+        else {
+            issues.push(`KEYCLOAK_MCP_TOOLSETS: unknown toolset '${name}' (valid: ${TOOLSET_NAMES.join(", ")}, all)`);
+        }
+    }
+    return result;
+}
+/**
+ * Parses and validates the environment. There are deliberately no credential
+ * defaults: missing or contradictory settings fail fast with a ConfigError.
+ */
+export function loadConfig(env = process.env) {
+    const parsed = EnvSchema.safeParse(env);
+    if (!parsed.success) {
+        throw new ConfigError(parsed.error.issues.map((issue) => `${issue.path.join(".") || "env"}: ${issue.message}`));
+    }
+    const e = parsed.data;
+    const issues = [];
+    const warnings = [];
+    const username = e.KEYCLOAK_USERNAME ?? e.KEYCLOAK_ADMIN;
+    const password = e.KEYCLOAK_PASSWORD ?? e.KEYCLOAK_ADMIN_PASSWORD;
+    if (e.KEYCLOAK_ADMIN !== undefined && e.KEYCLOAK_USERNAME === undefined) {
+        warnings.push("KEYCLOAK_ADMIN is deprecated; use KEYCLOAK_USERNAME instead.");
+    }
+    if (e.KEYCLOAK_ADMIN_PASSWORD !== undefined && e.KEYCLOAK_PASSWORD === undefined) {
+        warnings.push("KEYCLOAK_ADMIN_PASSWORD is deprecated; use KEYCLOAK_PASSWORD instead.");
+    }
+    const grantType = e.KEYCLOAK_GRANT_TYPE ??
+        (e.KEYCLOAK_CLIENT_SECRET !== undefined
+            ? "client_credentials"
+            : username !== undefined
+                ? "password"
+                : undefined);
+    let credentials;
+    if (grantType === undefined) {
+        issues.push("No credentials configured: set KEYCLOAK_CLIENT_ID + KEYCLOAK_CLIENT_SECRET (client_credentials) or KEYCLOAK_USERNAME + KEYCLOAK_PASSWORD (password).");
+    }
+    else if (grantType === "client_credentials") {
+        if (e.KEYCLOAK_CLIENT_ID === undefined) {
+            issues.push("KEYCLOAK_CLIENT_ID: is required for the client_credentials grant");
+        }
+        if (e.KEYCLOAK_CLIENT_SECRET === undefined) {
+            issues.push("KEYCLOAK_CLIENT_SECRET: is required for the client_credentials grant");
+        }
+        if (e.KEYCLOAK_CLIENT_ID !== undefined && e.KEYCLOAK_CLIENT_SECRET !== undefined) {
+            credentials = {
+                grantType,
+                clientId: e.KEYCLOAK_CLIENT_ID,
+                clientSecret: e.KEYCLOAK_CLIENT_SECRET,
+            };
+        }
+    }
+    else {
+        if (username === undefined)
+            issues.push("KEYCLOAK_USERNAME: is required for the password grant");
+        if (password === undefined)
+            issues.push("KEYCLOAK_PASSWORD: is required for the password grant");
+        if (username !== undefined && password !== undefined) {
+            credentials = {
+                grantType,
+                clientId: e.KEYCLOAK_CLIENT_ID ?? "admin-cli",
+                ...(e.KEYCLOAK_CLIENT_SECRET !== undefined && { clientSecret: e.KEYCLOAK_CLIENT_SECRET }),
+                username,
+                password,
+            };
+        }
+    }
+    const toolsets = resolveToolsets(e.KEYCLOAK_MCP_TOOLSETS, issues);
+    if (issues.length > 0 || credentials === undefined) {
+        throw new ConfigError(issues);
+    }
+    const { protocol, hostname } = new URL(e.KEYCLOAK_URL);
+    if (protocol === "http:" && !isLoopbackHost(hostname)) {
+        warnings.push(`KEYCLOAK_URL uses plain http:// for the remote host '${hostname}'; tokens and credentials travel unencrypted. Use https://.`);
+    }
+    return {
+        url: e.KEYCLOAK_URL.replace(/\/+$/, ""),
+        authRealm: e.KEYCLOAK_AUTH_REALM,
+        credentials,
+        readOnly: e.KEYCLOAK_MCP_READ_ONLY,
+        allowedRealms: e.KEYCLOAK_MCP_REALMS,
+        allowMasterWrite: e.KEYCLOAK_MCP_ALLOW_MASTER_WRITE,
+        toolsets,
+        requireConfirmation: e.KEYCLOAK_MCP_REQUIRE_CONFIRMATION,
+        timeoutMs: e.KEYCLOAK_MCP_TIMEOUT_MS,
+        logLevel: e.KEYCLOAK_MCP_LOG_LEVEL,
+        warnings,
+    };
+}
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname === "[::1]" ||
+        hostname.startsWith("127."));
+}
+/** Values that must be masked in logs. */
+export function collectSecrets(config) {
+    const { credentials } = config;
+    const secrets = [];
+    if (credentials.clientSecret)
+        secrets.push(credentials.clientSecret);
+    if (credentials.grantType === "password")
+        secrets.push(credentials.password);
+    return secrets;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAiB,MAAM,cAAc,CAAC;AAEzD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM;IACN,QAAQ;IACR,OAAO;IACP,SAAS;IACT,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC;AAGX,MAAM,CAAC,MAAM,gBAAgB,GAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AA4BpF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAoB;IAEnC,YAAY,MAAyB;QACnC,KAAK,CAAC,2BAA2B,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAW,EAAE;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC7E,MAAM,IAAI,GAAG,CAAC,QAAiB,EAAE,EAAE,CACjC,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnE,MAAM,SAAS,GAAG,CAAC,CAAC,UAAU,CAC5B,gBAAgB,EAChB,CAAC;KACE,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,CAAC,KAAK,IAAI,EAAE,CAAC;KACV,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;KAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CACrC,CACJ,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,YAAY,EAAE,CAAC,CAAC,UAAU,CACxB,gBAAgB,EAChB,CAAC;SACE,MAAM,CAAC,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAC;SAClE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC,CAAC,CAC/E;IACD,mBAAmB,EAAE,CAAC,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjF,kBAAkB,EAAE,cAAc;IAClC,sBAAsB,EAAE,cAAc;IACtC,iBAAiB,EAAE,cAAc;IACjC,iBAAiB,EAAE,cAAc;IACjC,cAAc,EAAE,cAAc;IAC9B,uBAAuB,EAAE,cAAc;IACvC,mBAAmB,EAAE,CAAC,CAAC,UAAU,CAC/B,gBAAgB,EAChB,CAAC;SACE,IAAI,CAAC,CAAC,oBAAoB,EAAE,UAAU,CAAC,EAAE;QACxC,KAAK,EAAE,4CAA4C;KACpD,CAAC;SACD,QAAQ,EAAE,CACd;IACD,sBAAsB,EAAE,IAAI,CAAC,KAAK,CAAC;IACnC,mBAAmB,EAAE,SAAS;IAC9B,+BAA+B,EAAE,IAAI,CAAC,KAAK,CAAC;IAC5C,qBAAqB,EAAE,SAAS;IAChC,iCAAiC,EAAE,IAAI,CAAC,IAAI,CAAC;IAC7C,uBAAuB,EAAE,CAAC,CAAC,UAAU,CACnC,gBAAgB,EAChB,CAAC,CAAC,MAAM;SACL,MAAM,CAAC,EAAE,KAAK,EAAE,kCAAkC,EAAE,CAAC;SACrD,GAAG,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;SACpC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;SACvC,OAAO,CAAC,MAAM,CAAC,CACnB;IACD,sBAAsB,EAAE,CAAC,CAAC,UAAU,CAClC,gBAAgB,EAChB,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,mBAAmB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAC1F;CACF,CAAC,CAAC;AAEH,SAAS,eAAe,CAAC,KAAwB,EAAE,MAAgB;IACjE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAe,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAK,aAAmC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,GAAG,CAAC,IAAmB,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CACT,2CAA2C,IAAI,aAAa,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAC7F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,WAAW,CACnB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CACzF,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,QAAQ,GAAG,CAAC,CAAC,iBAAiB,IAAI,CAAC,CAAC,cAAc,CAAC;IACzD,MAAM,QAAQ,GAAG,CAAC,CAAC,iBAAiB,IAAI,CAAC,CAAC,uBAAuB,CAAC;IAClE,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACxE,QAAQ,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,CAAC,uBAAuB,KAAK,SAAS,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACjF,QAAQ,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,SAAS,GACb,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,CAAC,sBAAsB,KAAK,SAAS;YACrC,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,QAAQ,KAAK,SAAS;gBACtB,CAAC,CAAC,UAAU;gBACZ,CAAC,CAAC,SAAS,CAAC,CAAC;IAEnB,IAAI,WAAoC,CAAC;IACzC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CACT,sJAAsJ,CACvJ,CAAC;IACJ,CAAC;SAAM,IAAI,SAAS,KAAK,oBAAoB,EAAE,CAAC;QAC9C,IAAI,CAAC,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,CAAC,sBAAsB,KAAK,SAAS,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,CAAC,kBAAkB,KAAK,SAAS,IAAI,CAAC,CAAC,sBAAsB,KAAK,SAAS,EAAE,CAAC;YACjF,WAAW,GAAG;gBACZ,SAAS;gBACT,QAAQ,EAAE,CAAC,CAAC,kBAAkB;gBAC9B,YAAY,EAAE,CAAC,CAAC,sBAAsB;aACvC,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,QAAQ,KAAK,SAAS;YACxB,MAAM,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;QACvE,IAAI,QAAQ,KAAK,SAAS;YACxB,MAAM,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;QACvE,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACrD,WAAW,GAAG;gBACZ,SAAS;gBACT,QAAQ,EAAE,CAAC,CAAC,kBAAkB,IAAI,WAAW;gBAC7C,GAAG,CAAC,CAAC,CAAC,sBAAsB,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,sBAAsB,EAAE,CAAC;gBACzF,QAAQ;gBACR,QAAQ;aACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAElE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACvD,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,QAAQ,CAAC,IAAI,CACX,wDAAwD,QAAQ,6DAA6D,CAC9H,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,EAAE,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACvC,SAAS,EAAE,CAAC,CAAC,mBAAmB;QAChC,WAAW;QACX,QAAQ,EAAE,CAAC,CAAC,sBAAsB;QAClC,aAAa,EAAE,CAAC,CAAC,mBAAmB;QACpC,gBAAgB,EAAE,CAAC,CAAC,+BAA+B;QACnD,QAAQ;QACR,mBAAmB,EAAE,CAAC,CAAC,iCAAiC;QACxD,SAAS,EAAE,CAAC,CAAC,uBAAuB;QACpC,QAAQ,EAAE,CAAC,CAAC,sBAAsB;QAClC,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,QAAgB;IACtC,OAAO,CACL,QAAQ,KAAK,WAAW;QACxB,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC/B,QAAQ,KAAK,OAAO;QACpB,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAC5B,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,cAAc,CAAC,MAAmC;IAChE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAC/B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,WAAW,CAAC,YAAY;QAAE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IACrE,IAAI,WAAW,CAAC,SAAS,KAAK,UAAU;QAAE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/guards.js

@@ -0,0 +1,47 @@
+import { ToolError } from "./keycloak/errors.js";
+function hasControlChars(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Validates a value that ends up as a URL path segment (realm name, user id, ...).
+ * Rejects separators, dot segments and control characters.
+ */
+export function assertPathSegment(value, label = "value") {
+    if (value.length === 0 ||
+        value.length > 255 ||
+        value === "." ||
+        value === ".." ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        hasControlChars(value)) {
+        throw new ToolError("guard", `Invalid ${label}: must be non-empty and must not contain '/', '\\', '..' or control characters.`);
+    }
+}
+/** Checks the realm against the allowlist and the master write protection. */
+export function assertRealmAllowed(policy, realm, options) {
+    assertPathSegment(realm, "realm");
+    if (policy.allowedRealms.length > 0 && !policy.allowedRealms.includes(realm)) {
+        throw new ToolError("guard", `Realm '${realm}' is not permitted by KEYCLOAK_MCP_REALMS (allowed: ${policy.allowedRealms.join(", ")}).`);
+    }
+    if (options.write && realm.toLowerCase() === "master" && !policy.allowMasterWrite) {
+        throw new ToolError("guard", "Write operations in the 'master' realm are disabled. Set KEYCLOAK_MCP_ALLOW_MASTER_WRITE=true to allow them.");
+    }
+}
+export function isRealmAllowed(policy, realm) {
+    return policy.allowedRealms.length === 0 || policy.allowedRealms.includes(realm);
+}
+/**
+ * Destructive tools must be called with confirm=true when confirmation is required.
+ * Throws a ToolError carrying the preview so the model can ask the user and retry.
+ */
+export function requireConfirmation(policy, confirm, preview) {
+    if (!policy.requireConfirmation || confirm === true)
+        return;
+    throw new ToolError("confirmation_required", `Confirmation required. This would: ${preview} Nothing was changed. Ask the user for approval, then call this tool again with confirm: true.`);
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAIjD,SAAS,eAAe,CAAC,KAAa;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAK,GAAG,OAAO;IAC9D,IACE,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,KAAK,CAAC,MAAM,GAAG,GAAG;QAClB,KAAK,KAAK,GAAG;QACb,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QACpB,eAAe,CAAC,KAAK,CAAC,EACtB,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,OAAO,EACP,WAAW,KAAK,iFAAiF,CAClG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAChC,MAAmB,EACnB,KAAa,EACb,OAA2B;IAE3B,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,SAAS,CACjB,OAAO,EACP,UAAU,KAAK,uDAAuD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC1G,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAClF,MAAM,IAAI,SAAS,CACjB,OAAO,EACP,8GAA8G,CAC/G,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,KAAa;IAC/D,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA2C,EAC3C,OAA4B,EAC5B,OAAe;IAEf,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO;IAC5D,MAAM,IAAI,SAAS,CACjB,uBAAuB,EACvB,sCAAsC,OAAO,gGAAgG,CAC9I,CAAC;AACJ,CAAC"}