forta-mcp 1.1.0 → 1.3.0

package/AGENTS.md

@@ -37,7 +37,7 @@ from a manual database dig into one call.
 
 | Path | Role |
 |------|------|
-| `index.js` | `--setup` flow, config guard, `api()`/`text()`/`body()` helpers, all 25 tools, transport. |
+| `index.js` | `--setup` flow, config guard, `api()`/`text()`/`body()` helpers, all 38 tools, transport. |
 | `package.json` | `bin.forta-mcp` → `index.js`. |
 | `README.md` | User-facing setup + tool tables. |
 | `AGENTS.md` | This file. |
@@ -113,12 +113,29 @@ be a Forta **super-admin** — the token does not bypass that.
 | Group | Tools |
 |-------|-------|
 | Health & identity | `forta_health`, `forta_get_self` |
-| Users | list, get, update, delete |
-| Platforms | list, get, create, update, delete, rotate credentials |
-| Roles | list, get, create, update, delete |
-| Grants | list, create, revoke, check |
+| Users | list (`status`, `q` filters), get, **create**, update, delete, **revoke sessions**, **activity**, **platform usage** |
+| Platforms | list (`include_deleted`), get, create, update, delete (also revokes its grants), **restore**, rotate credentials. `create`/`update` carry **`backchannel_logout_uri`** — see the warning below — and **`requestable`** |
+| Roles | list, get, create, update, delete (refused while anyone holds the role) |
+| Grants | list, create (`role_id` optional → platform default), **update role**, revoke, check |
+| Access requests | **list**, **decide** (approve/deny + `role_id`/`note`) |
+| Bulk / audit / settings | **`forta_bulk`** (`POST /admin/bulk`, atomic by default — the op list is in the tool description and forta-api's AGENTS.md), **list activity**, **overview**, **get/update settings** (`signup_mode`) |
 | Tokens | introspect, list/create/revoke API tokens |
 
+### Setting `backchannel_logout_uri` — order matters
+
+Forta POSTs a signed `logout_token` to this URL the instant a grant is revoked, so the consumer
+ends the session immediately instead of waiting up to five minutes for its introspection poll.
+
+⚠️ **Only set it once the platform actually serves the endpoint.** Until then every notification
+404s, is retried six times on a backoff, and is marked `exhausted` — which looks in the logs like
+a broken receiver rather than one that was never built. Deploy first, register second.
+
+Pass `null` to clear it. Absent is the normal state for a platform that has not implemented the
+receiver, and it is never an error — such a platform is simply skipped by the sender.
+
+`https` only; the emitter refuses anything else at send time and logs
+`FORTA_BACKCHANNEL_BAD_ENDPOINT`.
+
 ### Two behaviours that are easy to get wrong
 
 **1. `/oauth/introspect` is a resource-server endpoint, not an admin one.** It requires the
@@ -148,6 +165,12 @@ description says so; do not "fix" it by sending both.
 
 - **Published to npm** as `forta-mcp` (public). `npx -y` resolves the latest, so **publishing
   is deployment**.
+- **Bump the version in TWO places before publishing** — `package.json` *and* the `McpServer({
+  version })` literal in `index.js`. npm refuses to republish an existing version, so forgetting
+  `package.json` fails loudly (`cannot publish over the previously published versions`), but
+  forgetting the one in `index.js` fails SILENTLY: the server then reports a version it is not,
+  and a client debugging "which build am I talking to" is misled by the only field that answers
+  that question.
 - **Publishing requires 2FA via passkey** and must run from an interactive terminal — npm's web
   auth flow needs a browser, and from a non-TTY subprocess it degrades to demanding an OTP a
   passkey-only account cannot produce.
@@ -172,7 +195,8 @@ description says so; do not "fix" it by sending both.
 - **`zod` is used but not declared** in `package.json`, resolving transitively through the MCP
   SDK. Declaring it explicitly is the right fix, as a standalone change.
 - Publishing is outward-facing and effectively irreversible (npm unpublish is restricted after
-  72 hours) — do not publish without explicit instruction.
+  72 hours) — publish **only after asking Aiden and getting an explicit yes** for that specific
+  version (see `~/CLAUDE.md` *Ask-first actions*).
 
 ## Verification — always before "done"
 
@@ -198,5 +222,7 @@ Update this AGENTS.md in the same change when you:
 - **Change `api()` or its `opts`** → update *How code is written here*.
 - **Discover a `forta-api` behaviour that contradicts a tool description** → fix both, and
   record it under *Two behaviours that are easy to get wrong* if it is non-obvious.
+- **Add/change a tool parameter** → bump the minor version in BOTH places (see *Operations*) in
+  the same change, so the commit that adds the capability is the commit that can be published.
 - **Publish** → note the version and what changed.
 - Also keep `README.md`'s tool tables in sync.

package/README.md

@@ -75,19 +75,24 @@ Set `FORTA_ALLOW_SECRET_VALUES=1` to turn masking off if you genuinely need a wo
 ### Users
 | Tool | Description |
 |------|-------------|
-| `forta_list_users` | List users with status and super-admin flag |
-| `forta_get_user` | Single user with metadata and linked identities |
-| `forta_update_user` | Update name, email, status, super-admin, password |
+| `forta_list_users` | List users with status and super-admin flag (`status`, `q` filters) |
+| `forta_get_user` | Single user with metadata and sign-in methods |
+| `forta_create_user` | Create an account (no grants) |
+| `forta_update_user` | Update name, email, status (`pending` = awaiting approval), super-admin, password |
+| `forta_revoke_user_sessions` | Sign a user out of every platform ⚠️ |
+| `forta_get_user_activity` | Their trail across every platform: sign-ins, apps opened, refusals, admin changes |
+| `forta_get_user_platform_usage` | When they last opened each platform |
 | `forta_delete_user` | Soft-delete a user ⚠️ |
 
 ### Platforms
 | Tool | Description |
 |------|-------------|
-| `forta_list_platforms` | All registered OAuth platforms |
+| `forta_list_platforms` | All registered OAuth platforms (`include_deleted` for soft-deleted ones) |
 | `forta_get_platform` | Full platform config |
 | `forta_create_platform` | Register a platform (returns `client_secret` once) |
 | `forta_update_platform` | Update platform config |
-| `forta_delete_platform` | Delete a platform ⚠️ |
+| `forta_delete_platform` | Soft-delete a platform and revoke its grants ⚠️ |
+| `forta_restore_platform` | Restore a deleted platform (grants stay revoked) |
 | `forta_rotate_platform_credentials` | Rotate `client_secret` ⚠️ |
 
 ### Roles
@@ -103,10 +108,25 @@ Set `FORTA_ALLOW_SECRET_VALUES=1` to turn masking off if you genuinely need a wo
 | Tool | Description |
 |------|-------------|
 | `forta_list_grants` | Who can access what, with which role — **start here for 403s** |
-| `forta_create_grant` | Grant a user access to a platform |
+| `forta_create_grant` | Grant a user access to a platform (role optional → default) |
+| `forta_update_grant_role` | Move a grant to another role |
 | `forta_revoke_grant` | Revoke a grant ⚠️ |
 | `forta_check_grant` | Check a grant by `client_id`, exactly as a service sees it |
 
+### Access requests
+| Tool | Description |
+|------|-------------|
+| `forta_list_access_requests` | People asking for platforms marked requestable |
+| `forta_decide_access_request` | Approve (creates the grant) or deny |
+
+### Bulk, audit & settings
+| Tool | Description |
+|------|-------------|
+| `forta_bulk` | Many admin changes in one request, all-or-nothing by default ⚠️ |
+| `forta_list_activity` | Audit trail across every user and platform |
+| `forta_get_overview` | Users by status, pending requests, sign-up mode, failed sign-ins |
+| `forta_get_settings` / `forta_update_settings` | `signup_mode`: open, approval or closed |
+
 ### Tokens
 | Tool | Description |
 |------|-------------|

package/index.js

@@ -158,7 +158,7 @@ function body(obj) {
 
 const server = new McpServer({
     name: "forta",
-    version: "1.1.0",
+    version: "1.3.0",
 });
 
 // --- Health & identity ---
@@ -175,11 +175,51 @@ server.tool("forta_get_self", "Get the user this API token authenticates as —
 
 // --- Users ---
 
-server.tool("forta_list_users", "List all Forta users (id, uuid, email, status, is_super_admin, last_login_at)", {
+server.tool("forta_list_users", "List Forta users (id, uuid, email, status, is_super_admin, last_login_at). Filter with status (e.g. 'pending' for accounts awaiting approval) and q (name/email substring)", {
     limit: z.number().optional().describe("Max users to return"),
     offset: z.number().optional().describe("Pagination offset"),
-}, async ({ limit, offset }) => {
-    const res = await api("GET", "/admin/users", { limit, offset });
+    status: z.enum(["active", "pending", "invited", "suspended", "disabled"]).optional().describe("Only users in this status"),
+    q: z.string().optional().describe("Substring of name, display name or email"),
+}, async ({ limit, offset, status, q }) => {
+    const res = await api("GET", "/admin/users", { limit, offset, status, q });
+    return { content: text(res) };
+});
+
+server.tool("forta_create_user", "Create an account directly. New accounts have no grants. Without a password the user can sign in only via Google/Apple with this (verified) address", {
+    name: z.string().describe("Full name"),
+    email: z.string().describe("Email address"),
+    password: z.string().optional().describe("Initial password, 8–72 characters"),
+    status: z.enum(["active", "pending", "invited", "suspended", "disabled"]).optional().describe("Default active"),
+    email_verified: z.boolean().optional().describe("Mark the email verified"),
+    is_super_admin: z.boolean().optional().describe("Make a Forta super admin"),
+}, async (args) => {
+    const res = await api("POST", "/admin/users", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("forta_revoke_user_sessions", "Sign a user out of every platform now (revokes refresh-token families, denylists their access tokens, queues back-channel logouts). The account and its grants are unchanged", {
+    id: z.number().describe("User ID"),
+}, async ({ id }) => {
+    const res = await api("POST", `/admin/users/${id}/revoke-sessions`);
+    return { content: text(res) };
+});
+
+server.tool("forta_get_user_activity", "A user's activity trail across every platform: sign-ins (and failures), apps opened (access.sign_in, by platform_id), refusals, admin changes to them, and events platforms reported. Newest first; page with before_id", {
+    id: z.number().describe("User ID"),
+    category: z.enum(["auth", "access", "admin", "platform"]).optional(),
+    outcome: z.enum(["success", "failure", "denied"]).optional(),
+    platform_id: z.number().optional(),
+    limit: z.number().optional().describe("Max events (default 50, max 500)"),
+    before_id: z.number().optional().describe("next_before_id from the previous page"),
+}, async ({ id, ...params }) => {
+    const res = await api("GET", `/admin/users/${id}/activity`, params);
+    return { content: text(res) };
+});
+
+server.tool("forta_get_user_platform_usage", "When a user last signed in to each platform, with a count — answers 'does this person still use X?' before revoking", {
+    id: z.number().describe("User ID"),
+}, async ({ id }) => {
+    const res = await api("GET", `/admin/users/${id}/platform-usage`);
     return { content: text(res) };
 });
 
@@ -197,8 +237,8 @@ server.tool("forta_update_user", "Update a user. Only the fields you pass are ch
     email: z.string().optional().describe("Email address (normalized to lowercase)"),
     email_verified: z.boolean().optional().describe("Mark the email verified"),
     profile_image_url: z.string().optional().describe("Profile image URL"),
-    status: z.enum(["active", "invited", "suspended", "disabled", "deleted"]).optional().describe("Account status"),
-    is_super_admin: z.boolean().optional().describe("Grant or revoke Forta super-admin"),
+    status: z.enum(["active", "pending", "invited", "suspended", "disabled"]).optional().describe("Account status. 'pending' = awaiting approval. Leaving 'active' ends the user's sessions. Use forta_delete_user to delete. An administrator cannot change their own status"),
+    is_super_admin: z.boolean().optional().describe("Grant or revoke Forta super-admin (you cannot revoke your own)"),
     password: z.string().optional().describe("Set a new password for the user's local identity"),
 }, async ({ id, ...fields }) => {
     const res = await api("PUT", `/admin/users/${id}`, null, body(fields));
@@ -214,8 +254,10 @@ server.tool("forta_delete_user", "Soft-delete a user (sets deleted_at). The user
 
 // --- Platforms ---
 
-server.tool("forta_list_platforms", "List all registered OAuth platforms (client_id, base_url, type, status)", {}, async () => {
-    const res = await api("GET", "/admin/platforms");
+server.tool("forta_list_platforms", "List registered OAuth platforms (client_id, base_url, type, status, requestable). include_deleted adds soft-deleted ones (deleted: true), which can be restored", {
+    include_deleted: z.boolean().optional().describe("Include soft-deleted platforms"),
+}, async ({ include_deleted }) => {
+    const res = await api("GET", "/admin/platforms", include_deleted ? { include_deleted: "true" } : null);
     return { content: text(res) };
 });
 
@@ -233,6 +275,7 @@ server.tool("forta_create_platform", "Register a new OAuth platform. Returns the
     description: z.string().optional().describe("Description"),
     redirect_uris: z.array(z.string()).optional().describe("Allowed OAuth redirect URIs"),
     logout_redirect_uris: z.array(z.string()).optional().describe("Allowed post-logout redirect URIs"),
+    backchannel_logout_uri: z.string().nullable().optional().describe("OIDC Back-Channel Logout 1.0 endpoint on the platform (https only). Forta POSTs a signed logout_token here the moment a grant is revoked, instead of the consumer waiting up to 5 minutes for its introspection poll. Pass null to clear. ⚠️ Only set this once the platform actually serves the endpoint — until then every notification 404s, retries 6 times and is marked exhausted"),
     allowed_origins: z.array(z.string()).optional().describe("Allowed CORS origins"),
     is_first_party: z.boolean().optional().describe("First-party app (skips the consent screen)"),
     internal_resource: z.boolean().optional().describe("Internal resource, hidden from the app launcher"),
@@ -241,6 +284,7 @@ server.tool("forta_create_platform", "Register a new OAuth platform. Returns the
     position: z.number().optional().describe("Sort position in the launcher"),
     category: z.string().optional().describe("Launcher category"),
     health_check: z.string().optional().describe("Health check URL"),
+    requestable: z.boolean().optional().describe("Let signed-in users without access see it and request access (default false)"),
 }, async (args) => {
     const res = await api("POST", "/admin/platforms", null, body(args));
     return { content: text(res) };
@@ -254,6 +298,7 @@ server.tool("forta_update_platform", "Update a platform's configuration. Only th
     platform_type: z.enum(["WEB", "SPA", "SERVICE", "MOBILE"]).optional(),
     redirect_uris: z.array(z.string()).optional(),
     logout_redirect_uris: z.array(z.string()).optional(),
+    backchannel_logout_uri: z.string().nullable().optional().describe("OIDC Back-Channel Logout 1.0 endpoint on the platform (https only). Forta POSTs a signed logout_token here the moment a grant is revoked, instead of the consumer waiting up to 5 minutes for its introspection poll. Pass null to clear. ⚠️ Only set this once the platform actually serves the endpoint — until then every notification 404s, retries 6 times and is marked exhausted"),
     allowed_origins: z.array(z.string()).optional(),
     is_first_party: z.boolean().optional(),
     internal_resource: z.boolean().optional(),
@@ -262,19 +307,27 @@ server.tool("forta_update_platform", "Update a platform's configuration. Only th
     position: z.number().optional(),
     category: z.string().optional(),
     health_check: z.string().optional(),
+    requestable: z.boolean().optional().describe("Let signed-in users without access request it"),
     status: z.enum(["active", "disabled"]).optional().describe("Disabling blocks all new logins to this platform"),
 }, async ({ id, ...fields }) => {
     const res = await api("PUT", `/admin/platforms/${id}`, null, body(fields));
     return { content: text(res) };
 });
 
-server.tool("forta_delete_platform", "Delete a platform. Every grant and role attached to it stops working and all its users lose access. Destructive — confirm with forta_get_platform first", {
+server.tool("forta_delete_platform", "Soft-delete a platform and revoke every grant on it, in one transaction. All its users lose access. Restorable with forta_restore_platform (grants stay revoked). Destructive — confirm with forta_get_platform first", {
     id: z.number().describe("Platform ID"),
 }, async ({ id }) => {
     const res = await api("DELETE", `/admin/platforms/${id}`);
     return { content: text(res) };
 });
 
+server.tool("forta_restore_platform", "Restore a soft-deleted platform (status back to active). Its grants stay revoked — re-grant deliberately", {
+    id: z.number().describe("Platform ID (from forta_list_platforms with include_deleted)"),
+}, async ({ id }) => {
+    const res = await api("POST", `/admin/platforms/${id}/restore`);
+    return { content: text(res) };
+});
+
 server.tool("forta_rotate_platform_credentials", "Rotate a platform's client_secret. The old secret stops working immediately — the platform is down until its deployed config is updated. Returns the new secret once", {
     id: z.number().describe("Platform ID"),
 }, async ({ id }) => {
@@ -318,7 +371,7 @@ server.tool("forta_update_role", "Update a role's name or permissions. Changes a
     return { content: text(res) };
 });
 
-server.tool("forta_delete_role", "Delete a role. Users holding it lose its permissions. Destructive", {
+server.tool("forta_delete_role", "Delete a role. Refused (409) while anyone actively holds it — move them first with forta_update_grant_role. Revoked grants pointing at it are moved to another of the platform's roles", {
     platform_id: z.number().describe("Platform ID"),
     role_id: z.number().describe("Role ID"),
 }, async ({ platform_id, role_id }) => {
@@ -336,12 +389,20 @@ server.tool("forta_list_grants", "List access grants — which users can access
     return { content: text(res) };
 });
 
-server.tool("forta_create_grant", "Grant a user access to a platform with a specific role", {
+server.tool("forta_create_grant", "Grant a user access to a platform. role_id omitted or 0 = the platform's default (lowest-id) role. Reactivates a previously revoked grant for the same pair", {
     user_id: z.number().describe("User ID"),
     platform_id: z.number().describe("Platform ID"),
-    role_id: z.number().describe("Role ID to assign"),
+    role_id: z.number().optional().describe("Role ID to assign (default: the platform's default role)"),
 }, async ({ user_id, platform_id, role_id }) => {
-    const res = await api("POST", "/admin/grants", null, { user_id, platform_id, role_id });
+    const res = await api("POST", "/admin/grants", null, { user_id, platform_id, role_id: role_id ?? 0 });
+    return { content: text(res) };
+});
+
+server.tool("forta_update_grant_role", "Move an active grant to another role on the same platform. Access tokens already issued keep the old role until they expire (10 min)", {
+    id: z.number().describe("Grant ID (from forta_list_grants)"),
+    role_id: z.number().describe("New role ID (from forta_list_roles)"),
+}, async ({ id, role_id }) => {
+    const res = await api("PUT", `/admin/grants/${id}`, null, { role_id });
     return { content: text(res) };
 });
 
@@ -359,6 +420,72 @@ server.tool("forta_check_grant", "Check whether the token's user holds an active
     return { content: text(res) };
 });
 
+// --- Access requests ---
+
+server.tool("forta_list_access_requests", "List access requests — users asking for a grant on a platform marked requestable. Pending first", {
+    status: z.enum(["pending", "approved", "denied", "cancelled"]).optional(),
+    user_id: z.number().optional(),
+    platform_id: z.number().optional(),
+}, async (params) => {
+    const res = await api("GET", "/admin/access-requests", params);
+    return { content: text(res) };
+});
+
+server.tool("forta_decide_access_request", "Approve (creates the grant) or deny a pending access request. The requester sees the decision and note on their dashboard", {
+    id: z.number().describe("Access request ID"),
+    decision: z.enum(["approve", "deny"]),
+    role_id: z.number().optional().describe("Approve only: role to grant (default: the requested role, else the platform default)"),
+    note: z.string().optional().describe("Shown to the requester"),
+}, async ({ id, decision, role_id, note }) => {
+    const res = await api("POST", `/admin/access-requests/${id}/${decision}`, null, body({ role_id, note }));
+    return { content: text(res) };
+});
+
+// --- Bulk, activity, settings ---
+
+server.tool("forta_bulk", "Run many admin changes in one request — the dashboard's action cart. atomic (default true) runs them in one transaction: the first failure rolls back everything. Each op goes through the same logic as its single endpoint (session revocation, back-channel logout, audit). Ops: grant.create {user_id, platform_id, role_id?} · grant.revoke {grant_id} · grant.update_role {grant_id, role_id} · user.update {user_id, ...fields} · user.delete {user_id} · user.revoke_sessions {user_id} · platform.update {platform_id, ...fields} · platform.delete {platform_id} · platform.restore {platform_id} · access_request.approve {request_id, role_id?, note?} · access_request.deny {request_id, note?}. Max 250 operations", {
+    operations: z.array(z.object({
+        op: z.enum(["grant.create", "grant.revoke", "grant.update_role", "user.update", "user.delete", "user.revoke_sessions", "platform.update", "platform.delete", "platform.restore", "access_request.approve", "access_request.deny"]),
+        args: z.record(z.any()),
+    })).min(1).max(250),
+    atomic: z.boolean().optional().describe("All or nothing (default true)"),
+}, async ({ operations, atomic }) => {
+    const res = await api("POST", "/admin/bulk", null, { operations, atomic: atomic ?? true });
+    return { content: text(res) };
+});
+
+server.tool("forta_list_activity", "The audit trail across every user and platform: sign-ins and failures, apps opened, refusals, admin changes, platform-reported events. Persisted in Forta (survives Monitor's 30-day retention). Newest first; page with before_id", {
+    user_id: z.number().optional().describe("Subject or actor"),
+    platform_id: z.number().optional(),
+    category: z.enum(["auth", "access", "admin", "platform"]).optional(),
+    action: z.string().optional().describe("Action prefix, e.g. 'grant.' or 'auth.login'"),
+    outcome: z.enum(["success", "failure", "denied"]).optional(),
+    from: z.string().optional().describe("RFC 3339"),
+    to: z.string().optional().describe("RFC 3339"),
+    limit: z.number().optional().describe("Default 50, max 500"),
+    before_id: z.number().optional(),
+}, async (params) => {
+    const res = await api("GET", "/admin/activity", params);
+    return { content: text(res) };
+});
+
+server.tool("forta_get_overview", "Admin headline counts: users by status, pending access requests, sign-up mode, failed sign-ins in the last 24h", {}, async () => {
+    const res = await api("GET", "/admin/overview");
+    return { content: text(res) };
+});
+
+server.tool("forta_get_settings", "Service-wide settings (signup_mode: open | approval | closed)", {}, async () => {
+    const res = await api("GET", "/admin/settings");
+    return { content: text(res) };
+});
+
+server.tool("forta_update_settings", "Change service-wide settings. signup_mode: open (new accounts active, no grants), approval (new accounts pending until approved), closed (no new accounts; first-time Google/Apple sign-ins refused)", {
+    signup_mode: z.enum(["open", "approval", "closed"]).optional(),
+}, async (args) => {
+    const res = await api("PUT", "/admin/settings", null, body(args));
+    return { content: text(res) };
+});
+
 // --- Token introspection ---
 
 server.tool("forta_introspect_token", "Introspect an access JWT (RFC 7662) — returns active, sub, exp, iat, token_type. Answers 'is the token this service rejected expired, malformed, or lacking a grant?'. Requires the calling platform's client credentials: introspection is scoped to that platform, and a token valid elsewhere returns active=false here. Only works for access JWTs — opaque frt_ API tokens always report active=false, so use forta_list_api_tokens to inspect those instead", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forta-mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP server for the Forta OAuth2 identity provider",
   "type": "module",
   "main": "index.js",