@clavex/mcp-server 1.0.0

package/dist/tools/users.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleError, mdTable } from "../helpers.js";
+export function registerUserTools(server) {
+    // ── List users ─────────────────────────────────────────────────────────────
+    server.registerTool("clavex_list_users", {
+        title: "List Users",
+        description: `List all users in an organization.
+
+Returns a table with: id, email, first_name, last_name, is_active, created_at.
+
+Use when: "show users in org <id>", "list all accounts for acme", "who are the members?".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ org_id }) => handleError(async () => {
+        const users = await getClient().get(getClient().orgPath(org_id, "/users"));
+        return mdTable(users, ["id", "email", "first_name", "last_name", "is_active", "created_at"]);
+    }));
+    // ── Get user ───────────────────────────────────────────────────────────────
+    server.registerTool("clavex_get_user", {
+        title: "Get User",
+        description: `Get detailed information about a specific user.
+
+Returns full user JSON including roles, groups, and metadata.
+
+Use when: "get user <id>", "show me alice's account details".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            user_id: z.string().uuid().describe("User UUID"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ org_id, user_id }) => handleError(async () => {
+        const user = await getClient().get(getClient().orgPath(org_id, `/users/${user_id}`));
+        return JSON.stringify(user, null, 2);
+    }));
+    // ── Create user ────────────────────────────────────────────────────────────
+    server.registerTool("clavex_create_user", {
+        title: "Create User",
+        description: `Create a new user in an organization.
+
+Args:
+  - org_id: Organization UUID
+  - email: User's email address (must be unique within the org)
+  - first_name: Given name
+  - last_name: Family name
+  - password (optional): Initial password. If omitted, a welcome/reset email is sent.
+  - send_welcome_email (optional): Send a welcome email (default true)
+
+Returns: Created user JSON with the new user_id.
+
+Use when: "add user alice@example.com to org <id>", "create account for John Doe".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            email: z.string().email().describe("User email address"),
+            first_name: z.string().describe("Given name"),
+            last_name: z.string().describe("Family name"),
+            password: z.string().optional().describe("Initial password (omit to trigger welcome email)"),
+            send_welcome_email: z.boolean().default(true).describe("Send welcome/activation email"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }, async ({ org_id, email, first_name, last_name, password, send_welcome_email }) => handleError(async () => {
+        const user = await getClient().post(getClient().orgPath(org_id, "/users"), { email, first_name, last_name, password, send_welcome_email });
+        return `User created:\n\n${JSON.stringify(user, null, 2)}`;
+    }));
+    // ── Update user ────────────────────────────────────────────────────────────
+    server.registerTool("clavex_update_user", {
+        title: "Update User",
+        description: `Update a user's profile or status (PATCH semantics — only provided fields change).
+
+Args:
+  - org_id, user_id: identifiers
+  - first_name, last_name, email (optional): new values
+  - is_active (optional): set to false to suspend the account
+  - password (optional): force-set a new password
+
+Returns: Updated user JSON.
+
+Use when: "disable Alice's account", "change Bob's email", "rename user".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            user_id: z.string().uuid().describe("User UUID"),
+            email: z.string().email().optional().describe("New email address"),
+            first_name: z.string().optional().describe("New given name"),
+            last_name: z.string().optional().describe("New family name"),
+            is_active: z.boolean().optional().describe("Set to false to suspend the account"),
+            password: z.string().optional().describe("Force-set a new password"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, async ({ org_id, user_id, ...updates }) => handleError(async () => {
+        const body = Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined));
+        const user = await getClient().patch(getClient().orgPath(org_id, `/users/${user_id}`), body);
+        return `User updated:\n\n${JSON.stringify(user, null, 2)}`;
+    }));
+    // ── Delete user ────────────────────────────────────────────────────────────
+    server.registerTool("clavex_delete_user", {
+        title: "Delete User",
+        description: `Permanently delete a user from an organization. This action is irreversible.
+
+Consider using clavex_update_user with is_active=false to suspend without deleting.
+
+Use when: "delete user <id>", "remove Alice's account permanently".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            user_id: z.string().uuid().describe("User UUID to delete"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async ({ org_id, user_id }) => handleError(async () => {
+        await getClient().del(getClient().orgPath(org_id, `/users/${user_id}`));
+        return `User ${user_id} deleted from org ${org_id}.`;
+    }));
+    // ── Password reset ─────────────────────────────────────────────────────────
+    server.registerTool("clavex_send_password_reset", {
+        title: "Send Password Reset Email",
+        description: `Send a password reset email to a user.
+
+Use when: "send password reset to alice", "user locked out — send reset email".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            user_id: z.string().uuid().describe("User UUID"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }, async ({ org_id, user_id }) => handleError(async () => {
+        await getClient().post(getClient().orgPath(org_id, `/users/${user_id}/send-password-reset`));
+        return `Password reset email sent to user ${user_id}.`;
+    }));
+    // ── List user roles ────────────────────────────────────────────────────────
+    server.registerTool("clavex_list_user_roles", {
+        title: "List User Roles",
+        description: `List all roles assigned to a specific user.
+
+Use when: "what roles does Alice have?", "list permissions for user <id>".`,
+        inputSchema: {
+            org_id: z.string().uuid().describe("Organization UUID"),
+            user_id: z.string().uuid().describe("User UUID"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async ({ org_id, user_id }) => handleError(async () => {
+        const roles = await getClient().get(getClient().orgPath(org_id, `/users/${user_id}/roles`));
+        return mdTable(roles, ["id", "name", "description"]);
+    }));
+}
+//# sourceMappingURL=users.js.map

package/dist/tools/users.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@clavex/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Clavex Identity Platform — manage orgs, users, IdPs and OIDC clients via natural language",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "clavex-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "clavex",
+    "mcp",
+    "identity",
+    "iam",
+    "oidc",
+    "claude"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "@types/node": "^20.12.7"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clavex-eu/clavex-sdk",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/clavex-eu/clavex-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/clavex-eu/clavex-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,148 @@
+/**
+ * Clavex API client used by all MCP tools.
+ * Reads credentials from environment variables:
+ *
+ *   CLAVEX_BASE_URL   — required, e.g. https://auth.example.com
+ *   CLAVEX_TOKEN      — pre-acquired JWT bearer token (preferred)
+ *
+ *   — or —
+ *
+ *   CLAVEX_EMAIL      — admin email (auto-login on first call)
+ *   CLAVEX_PASSWORD   — admin password
+ *   CLAVEX_ORG_SLUG   — org slug (omit for superadmin)
+ */
+
+export class ClavexAPIError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ClavexAPIError";
+  }
+}
+
+interface LoginResponse {
+  token: string;
+}
+
+export class ClavexClient {
+  private readonly baseURL: string;
+  private token: string | undefined;
+  private loginPromise: Promise<void> | null = null;
+
+  // Credential fields for auto-login
+  private readonly email: string | undefined;
+  private readonly password: string | undefined;
+  private readonly orgSlug: string | undefined;
+
+  constructor() {
+    const base = process.env.CLAVEX_BASE_URL;
+    if (!base) throw new Error("CLAVEX_BASE_URL environment variable is required");
+    this.baseURL = base.replace(/\/+$/, "");
+    this.token = process.env.CLAVEX_TOKEN;
+    this.email = process.env.CLAVEX_EMAIL;
+    this.password = process.env.CLAVEX_PASSWORD;
+    this.orgSlug = process.env.CLAVEX_ORG_SLUG;
+  }
+
+  private async ensureToken(): Promise<void> {
+    if (this.token) return;
+    if (!this.email || !this.password) {
+      throw new Error(
+        "Authentication required: set CLAVEX_TOKEN or CLAVEX_EMAIL + CLAVEX_PASSWORD",
+      );
+    }
+    if (!this.loginPromise) {
+      this.loginPromise = this.doLogin().then(() => {
+        this.loginPromise = null;
+      }).catch((e) => {
+        this.loginPromise = null;
+        throw e;
+      });
+    }
+    await this.loginPromise;
+  }
+
+  private async doLogin(): Promise<void> {
+    const resp = await this.request<LoginResponse>(
+      "POST",
+      "/api/v1/auth/login",
+      { org_slug: this.orgSlug, email: this.email, password: this.password },
+      false,
+    );
+    this.token = resp.token;
+  }
+
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    auth = true,
+  ): Promise<T> {
+    if (auth) await this.ensureToken();
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+    if (auth && this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+
+    const res = await fetch(this.baseURL + path, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    if (res.status === 204) return undefined as unknown as T;
+
+    let resBody: unknown;
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      resBody = await res.json();
+    } else {
+      resBody = await res.text();
+    }
+
+    if (!res.ok) {
+      const msg =
+        typeof resBody === "object" && resBody !== null && "error" in resBody
+          ? String((resBody as Record<string, unknown>).error)
+          : String(resBody);
+      throw new ClavexAPIError(res.status, resBody, `${method} ${path} → ${res.status}: ${msg}`);
+    }
+
+    return resBody as T;
+  }
+
+  get<T>(path: string): Promise<T> {
+    return this.request<T>("GET", path);
+  }
+  post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>("POST", path, body);
+  }
+  patch<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>("PATCH", path, body);
+  }
+  put<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>("PUT", path, body);
+  }
+  del<T>(path: string): Promise<T> {
+    return this.request<T>("DELETE", path);
+  }
+
+  orgPath(orgID: string, suffix: string): string {
+    return `/api/v1/organizations/${orgID}${suffix}`;
+  }
+}
+
+// Singleton — created lazily on first tool call
+let _client: ClavexClient | null = null;
+
+export function getClient(): ClavexClient {
+  if (!_client) _client = new ClavexClient();
+  return _client;
+}

package/src/helpers.ts

@@ -0,0 +1,45 @@
+import { ClavexAPIError } from "./client.js";
+
+/**
+ * Wraps a tool handler so API errors become user-facing error messages
+ * instead of crashing the MCP server.
+ */
+export async function handleError<T>(
+  fn: () => Promise<T>,
+): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+  try {
+    const result = await fn();
+    return {
+      content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    if (err instanceof ClavexAPIError) {
+      return {
+        content: [{ type: "text", text: `Error ${err.status}: ${err.message}` }],
+        isError: true,
+      };
+    }
+    if (err instanceof Error) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Unknown error: ${String(err)}` }],
+      isError: true,
+    };
+  }
+}
+
+/** Format an array of objects as a readable Markdown table. */
+export function mdTable(rows: Record<string, unknown>[], cols?: string[]): string {
+  if (!rows.length) return "_No results._";
+  const keys = cols ?? Object.keys(rows[0]);
+  const header = `| ${keys.join(" | ")} |`;
+  const sep    = `| ${keys.map(() => "---").join(" | ")} |`;
+  const body   = rows
+    .map((r) => `| ${keys.map((k) => String(r[k] ?? "—")).join(" | ")} |`)
+    .join("\n");
+  return [header, sep, body].join("\n");
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Clavex MCP Server — entry point
+ *
+ * Exposes ~30 tools for managing Clavex via natural language through Claude.
+ * Uses stdio transport (compatible with Claude Desktop, Claude API, MCP Inspector).
+ *
+ * Configuration via environment variables:
+ *
+ *   CLAVEX_BASE_URL   — required, e.g. https://auth.example.com
+ *   CLAVEX_TOKEN      — pre-acquired JWT bearer token  (preferred)
+ *
+ *   — or —
+ *
+ *   CLAVEX_EMAIL      — admin email (auto-login on first call)
+ *   CLAVEX_PASSWORD   — admin password
+ *   CLAVEX_ORG_SLUG   — org slug (omit for superadmin login)
+ *
+ * Usage:
+ *   node dist/index.js
+ *   npx @clavex/mcp-server
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { registerOrgTools }          from "./tools/orgs.js";
+import { registerUserTools }         from "./tools/users.js";
+import { registerGroupTools }        from "./tools/groups.js";
+import { registerClientTools }       from "./tools/clients.js";
+import { registerIDPTools }          from "./tools/idps.js";
+import { registerPolicyTools }       from "./tools/policies.js";
+import { registerCIBATools }         from "./tools/ciba.js";
+import { registerFGATools }          from "./tools/fga.js";
+import { registerAccessReviewTools } from "./tools/access_reviews.js";
+import { registerSSFTools }          from "./tools/ssf.js";
+import { registerAITools }           from "./tools/ai.js";
+import { registerPAMTools }          from "./tools/pam.js";
+import { registerDeveloperTools }    from "./tools/developer.js";
+
+const server = new McpServer({
+  name: "clavex-mcp-server",
+  version: "1.2.0",
+});
+
+// Register all tool domains
+registerOrgTools(server);
+registerUserTools(server);
+registerGroupTools(server);
+registerClientTools(server);
+registerIDPTools(server);
+registerPolicyTools(server);
+registerCIBATools(server);
+registerFGATools(server);
+registerAccessReviewTools(server);
+registerSSFTools(server);
+registerAITools(server);
+registerPAMTools(server);
+registerDeveloperTools(server);
+
+// Connect via stdio (Claude Desktop / Claude API compatible)
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/access_reviews.ts

@@ -0,0 +1,163 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleError, mdTable } from "../helpers.js";
+
+export function registerAccessReviewTools(server: McpServer): void {
+  // ── List access review campaigns ───────────────────────────────────────────
+  server.registerTool(
+    "clavex_list_access_reviews",
+    {
+      title: "List Access Review Campaigns",
+      description: `List access review (access certification) campaigns for an organization.
+
+Access reviews are periodic or triggered campaigns where managers certify whether
+users should retain their roles and permissions (JML — Joiner/Mover/Leaver compliance).
+
+Returns: id, name, status (pending/active/completed/cancelled), starts_at, ends_at, item counts.
+
+Status values:
+  "pending"   — scheduled, not yet started
+  "active"    — in progress, items are awaiting reviewer decisions
+  "completed" — all items decided
+  "cancelled" — cancelled before completion
+
+Use when:
+  "show access review campaigns for org <id>"
+  "what reviews are currently active?"
+  "mostrami le campagne di access review"`,
+      inputSchema: {
+        org_id: z.string().uuid().describe("Organization UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id }) =>
+      handleError(async () => {
+        const campaigns = await getClient().get<Array<Record<string, unknown>>>(
+          getClient().orgPath(org_id, "/access-reviews"),
+        );
+        if (!Array.isArray(campaigns) || campaigns.length === 0) {
+          return "_No access review campaigns found._";
+        }
+        return mdTable(campaigns, ["id", "name", "status", "starts_at", "ends_at"]);
+      }),
+  );
+
+  // ── Create access review campaign ──────────────────────────────────────────
+  server.registerTool(
+    "clavex_create_access_review",
+    {
+      title: "Create Access Review Campaign",
+      description: `Create a new access review (certification) campaign for an organization.
+
+A campaign generates one review item per (user, role) assignment in the org.
+Items are sent to reviewers who decide keep/revoke for each assignment.
+
+Args:
+  - org_id: Organization UUID
+  - name: Campaign name — e.g. "Q2 2026 Quarterly Access Review" or "Annual HR Certification"
+  - starts_at: ISO 8601 datetime when the campaign begins (e.g. "2026-06-01T00:00:00Z")
+  - ends_at: ISO 8601 datetime when the campaign expires — unreviewed items auto-revoke
+  - description (optional): Human-readable purpose of this campaign
+
+Returns: Created campaign JSON including the campaign_id.
+
+Use when:
+  "create a quarterly access review for org <id> starting June 1"
+  "lancia la campagna di access review trimestrale"
+  "schedule annual certification"`,
+      inputSchema: {
+        org_id:      z.string().uuid().describe("Organization UUID"),
+        name:        z.string().describe("Campaign name, e.g. 'Q2 2026 Quarterly Review'"),
+        starts_at:   z.string().describe("ISO 8601 start datetime, e.g. '2026-06-01T00:00:00Z'"),
+        ends_at:     z.string().describe("ISO 8601 end/deadline datetime"),
+        description: z.string().optional().describe("Optional description of this review's scope"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, name, starts_at, ends_at, description }) =>
+      handleError(async () => {
+        const campaign = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, "/access-reviews"),
+          { name, starts_at, ends_at, description },
+        );
+        return `Access review campaign created:\n\n${JSON.stringify(campaign, null, 2)}`;
+      }),
+  );
+
+  // ── Launch access review campaign ─────────────────────────────────────────
+  server.registerTool(
+    "clavex_launch_review",
+    {
+      title: "Launch Access Review Campaign",
+      description: `Immediately launch (activate) an access review campaign, generating review items and sending notifications to reviewers.
+
+This moves the campaign from "pending" to "active" without waiting for the scheduled starts_at.
+Use this to trigger an unscheduled or emergency review.
+
+After launching:
+  - One review item is created per (user, role) assignment in the org
+  - Reviewer notification emails are sent
+  - The worker processes items on a 15-minute tick
+
+Args:
+  - org_id: Organization UUID
+  - campaign_id: UUID of the campaign to launch (use clavex_list_access_reviews to find it)
+
+Returns: Launched campaign JSON.
+
+Use when:
+  "lancia la campagna di access review trimestrale"
+  "launch access review <campaign_id> now"
+  "activate the pending access certification"`,
+      inputSchema: {
+        org_id:      z.string().uuid().describe("Organization UUID"),
+        campaign_id: z.string().uuid().describe("Campaign UUID to launch"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ org_id, campaign_id }) =>
+      handleError(async () => {
+        const campaign = await getClient().post<Record<string, unknown>>(
+          getClient().orgPath(org_id, `/access-reviews/${campaign_id}/launch`),
+        );
+        return `Campaign launched successfully:\n\n${JSON.stringify(campaign, null, 2)}`;
+      }),
+  );
+
+  // ── Get campaign items ────────────────────────────────────────────────────
+  server.registerTool(
+    "clavex_get_review_items",
+    {
+      title: "Get Access Review Items",
+      description: `Get all items (user-role pairs) in an access review campaign along with their status.
+
+Each item represents one (user, role) assignment awaiting a keep/revoke decision.
+
+Returns: user_id, user_email, role_id, role_name, reviewer_email, decision, decided_at.
+
+Decision values:
+  null      — not yet reviewed
+  "keep"    — reviewer confirmed access should be retained
+  "revoke"  — reviewer decided access should be removed (processed by the worker)
+
+Use when:
+  "show items for campaign <id>"
+  "how many reviews are still pending?"
+  "quali utenti sono in attesa di revisione?"`,
+      inputSchema: {
+        org_id:      z.string().uuid().describe("Organization UUID"),
+        campaign_id: z.string().uuid().describe("Campaign UUID"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    },
+    async ({ org_id, campaign_id }) =>
+      handleError(async () => {
+        const items = await getClient().get<Array<Record<string, unknown>>>(
+          getClient().orgPath(org_id, `/access-reviews/${campaign_id}/items`),
+        );
+        if (!Array.isArray(items) || items.length === 0) return "_No items found for this campaign._";
+        return mdTable(items, ["id", "user_email", "role_name", "reviewer_email", "decision", "decided_at"]);
+      }),
+  );
+}