forta-mcp 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# forta-mcp
+
+MCP server for the [Forta](https://github.com/aidenappl/forta-api) OAuth2 identity provider. Gives Claude Code direct access to users, platforms, roles, grants, and token introspection.
+
+> **appleby.cloud platform** · MCP server · `auth.appleby.cloud`
+
+---
+
+## Overview
+
+Forta is the identity provider for the whole `appleby.cloud` ecosystem, so almost every auth bug starts here. This server turns "why is this user getting a 403 from Keyring" into one `forta_list_grants` call instead of a manual database dig.
+
+## Quick Start
+
+```bash
+npx forta-mcp --setup
+```
+
+Prompts for your Forta API URL and token, writes the config to `~/.mcp.json`. Restart Claude Code afterwards.
+
+## Manual Setup
+
+```json
+{
+  "mcpServers": {
+    "forta": {
+      "command": "npx",
+      "args": ["-y", "forta-mcp"],
+      "env": {
+        "FORTA_API_URL": "https://auth.appleby.cloud",
+        "FORTA_API_TOKEN": "frt_..."
+      }
+    }
+  }
+}
+```
+
+Generate a token from the Forta dashboard under **Settings > API Tokens**, or:
+
+```bash
+curl -X POST https://auth.appleby.cloud/admin/api-tokens \
+  -H "Authorization: Bearer <access-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"claude-code","expires_in":"365d"}'
+```
+
+Tokens are `frt_`-prefixed, owned by the creating user, and require that user to be a Forta super-admin for the `/admin` tools. The plaintext is returned once and stored only as a SHA-256 hash.
+
+## Tools
+
+### Health & identity
+| Tool | Description |
+|------|-------------|
+| `forta_health` | API health and database connectivity |
+| `forta_get_self` | Which user this token authenticates as |
+
+### 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_delete_user` | Soft-delete a user ⚠️ |
+
+### Platforms
+| Tool | Description |
+|------|-------------|
+| `forta_list_platforms` | All registered OAuth platforms |
+| `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_rotate_platform_credentials` | Rotate `client_secret` ⚠️ |
+
+### Roles
+| Tool | Description |
+|------|-------------|
+| `forta_list_roles` | Roles on a platform, with permissions |
+| `forta_get_role` | Single role |
+| `forta_create_role` | Create a role |
+| `forta_update_role` | Update name or permission set |
+| `forta_delete_role` | Delete a role ⚠️ |
+
+### Grants
+| 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_revoke_grant` | Revoke a grant ⚠️ |
+| `forta_check_grant` | Check a grant by `client_id`, exactly as a service sees it |
+
+### Tokens
+| Tool | Description |
+|------|-------------|
+| `forta_introspect_token` | RFC 7662 introspection — is this token expired, or bound elsewhere? |
+| `forta_list_api_tokens` | Active API tokens with expiry and last use |
+| `forta_create_api_token` | Mint a token (plaintext returned once) |
+| `forta_revoke_api_token` | Revoke a token ⚠️ |
+
+⚠️ = destructive. Tool descriptions state the blast radius; `rotate_platform_credentials` in particular takes the platform down until its deployed config is updated.
+
+## Contributing & further reading
+
+- [forta-api](https://github.com/aidenappl/forta-api) — the API this wraps
+- [go-forta](https://github.com/aidenappl/go-forta) — Go SDK; v1.3.0+ accepts these tokens
+- [keyring-mcp](https://github.com/aidenappl/keyring-mcp) — uses the same `frt_` token

package/index.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createInterface } from "readline";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// --- Interactive setup ---
+
+if (process.argv.includes("--setup")) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+    console.log("\n  Forta MCP Setup\n");
+
+    const apiUrl = (await ask("  Forta API URL (https://auth.appleby.cloud): ")).trim() || "https://auth.appleby.cloud";
+    const apiToken = (await ask("  Forta API Token (frt_…): ")).trim();
+    rl.close();
+
+    if (!apiToken) {
+        console.error("\n  Error: API token is required.\n");
+        process.exit(1);
+    }
+    if (!apiToken.startsWith("frt_")) {
+        console.error("\n  Error: Forta API tokens start with 'frt_'. Generate one from the Forta");
+        console.error("  dashboard under Settings > API Tokens, or POST /admin/api-tokens.\n");
+        process.exit(1);
+    }
+
+    const mcpPath = join(homedir(), ".mcp.json");
+    let config = { mcpServers: {} };
+    if (existsSync(mcpPath)) {
+        try { config = JSON.parse(readFileSync(mcpPath, "utf-8")); } catch {}
+        if (!config.mcpServers) config.mcpServers = {};
+    }
+
+    config.mcpServers.forta = {
+        command: "npx",
+        args: ["-y", "forta-mcp"],
+        env: {
+            FORTA_API_URL: apiUrl,
+            FORTA_API_TOKEN: apiToken,
+        },
+    };
+
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`\n  Written to ${mcpPath}`);
+    console.log("  Restart Claude Code to load the Forta MCP server.\n");
+    process.exit(0);
+}
+
+// --- MCP Server ---
+
+const API_URL = process.env.FORTA_API_URL;
+const API_TOKEN = process.env.FORTA_API_TOKEN;
+
+if (!API_URL || !API_TOKEN) {
+    console.error("FORTA_API_URL and FORTA_API_TOKEN are required.");
+    console.error("Run `npx forta-mcp --setup` to configure.");
+    process.exit(1);
+}
+
+// --- HTTP helper ---
+
+async function api(method, path, params, body) {
+    const url = new URL(path, API_URL);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+        }
+    }
+    const opts = {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_TOKEN}`,
+        },
+        signal: AbortSignal.timeout(30000),
+    };
+    if (body) {
+        opts.headers["Content-Type"] = "application/json";
+        opts.body = JSON.stringify(body);
+    }
+    try {
+        const res = await fetch(url.toString(), opts);
+        const text = await res.text();
+        if (!text) return { success: res.ok, status: res.status };
+        try {
+            return JSON.parse(text);
+        } catch {
+            // /healthcheck and the OAuth endpoints return bare text, not the envelope.
+            return { success: res.ok, status: res.status, body: text };
+        }
+    } catch (err) {
+        return { success: false, error: err.message, error_message: `API request failed: ${err.message}` };
+    }
+}
+
+function text(data) {
+    return [{ type: "text", text: JSON.stringify(data, null, 2) }];
+}
+
+// Strips undefined keys so a PUT only sends the fields the caller supplied —
+// the API treats a present-but-null field as an explicit clear.
+function body(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+const server = new McpServer({
+    name: "forta",
+    version: "1.0.0",
+});
+
+// --- Health & identity ---
+
+server.tool("forta_health", "Check Forta API health and database connectivity", {}, async () => {
+    const res = await api("GET", "/healthcheck");
+    return { content: text(res) };
+});
+
+server.tool("forta_get_self", "Get the user this API token authenticates as — useful for confirming the token works and which account it belongs to", {}, async () => {
+    const res = await api("GET", "/auth/self");
+    return { content: text(res) };
+});
+
+// --- Users ---
+
+server.tool("forta_list_users", "List all Forta users (id, uuid, email, status, is_super_admin, last_login_at)", {
+    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 });
+    return { content: text(res) };
+});
+
+server.tool("forta_get_user", "Get a single user by ID, including metadata and linked identities", {
+    id: z.number().describe("User ID"),
+}, async ({ id }) => {
+    const res = await api("GET", `/admin/users/${id}`);
+    return { content: text(res) };
+});
+
+server.tool("forta_update_user", "Update a user. Only the fields you pass are changed. Setting status to 'suspended' or 'disabled' immediately blocks new logins across every platform", {
+    id: z.number().describe("User ID"),
+    name: z.string().optional().describe("Full name"),
+    display_name: z.string().optional().describe("Display name"),
+    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"),
+    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));
+    return { content: text(res) };
+});
+
+server.tool("forta_delete_user", "Soft-delete a user (sets deleted_at). The user can no longer authenticate to any platform. Destructive — confirm the user ID first with forta_get_user", {
+    id: z.number().describe("User ID"),
+}, async ({ id }) => {
+    const res = await api("DELETE", `/admin/users/${id}`);
+    return { content: text(res) };
+});
+
+// --- 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");
+    return { content: text(res) };
+});
+
+server.tool("forta_get_platform", "Get a platform's full config: redirect URIs, allowed origins, category, health check", {
+    id: z.number().describe("Platform ID"),
+}, async ({ id }) => {
+    const res = await api("GET", `/admin/platforms/${id}`);
+    return { content: text(res) };
+});
+
+server.tool("forta_create_platform", "Register a new OAuth platform. Returns the client_secret exactly once — it is not retrievable afterwards", {
+    name: z.string().describe("Platform name (must be unique)"),
+    base_url: z.string().describe("Base URL of the application"),
+    platform_type: z.enum(["WEB", "SPA", "SERVICE", "MOBILE"]).describe("Platform type"),
+    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"),
+    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"),
+    platform_icon_url: z.string().optional().describe("Icon URL"),
+    host: z.string().optional().describe("Host"),
+    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"),
+}, async (args) => {
+    const res = await api("POST", "/admin/platforms", null, body(args));
+    return { content: text(res) };
+});
+
+server.tool("forta_update_platform", "Update a platform's configuration. Only the fields you pass are changed", {
+    id: z.number().describe("Platform ID"),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    base_url: z.string().optional(),
+    platform_type: z.enum(["WEB", "SPA", "SERVICE", "MOBILE"]).optional(),
+    redirect_uris: z.array(z.string()).optional(),
+    logout_redirect_uris: z.array(z.string()).optional(),
+    allowed_origins: z.array(z.string()).optional(),
+    is_first_party: z.boolean().optional(),
+    internal_resource: z.boolean().optional(),
+    platform_icon_url: z.string().optional(),
+    host: z.string().optional(),
+    position: z.number().optional(),
+    category: z.string().optional(),
+    health_check: z.string().optional(),
+    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", {
+    id: z.number().describe("Platform ID"),
+}, async ({ id }) => {
+    const res = await api("DELETE", `/admin/platforms/${id}`);
+    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 }) => {
+    const res = await api("POST", `/admin/platforms/${id}/rotate-credentials`);
+    return { content: text(res) };
+});
+
+// --- Roles ---
+
+server.tool("forta_list_roles", "List the roles defined for a platform, with their permission sets", {
+    platform_id: z.number().describe("Platform ID"),
+}, async ({ platform_id }) => {
+    const res = await api("GET", `/admin/platforms/${platform_id}/roles`);
+    return { content: text(res) };
+});
+
+server.tool("forta_get_role", "Get a single role by ID", {
+    platform_id: z.number().describe("Platform ID"),
+    role_id: z.number().describe("Role ID"),
+}, async ({ platform_id, role_id }) => {
+    const res = await api("GET", `/admin/platforms/${platform_id}/roles/${role_id}`);
+    return { content: text(res) };
+});
+
+server.tool("forta_create_role", "Create a role on a platform", {
+    platform_id: z.number().describe("Platform ID"),
+    name: z.string().describe("Role name"),
+    permissions: z.array(z.string()).optional().describe("Permission strings granted by this role"),
+}, async ({ platform_id, name, permissions }) => {
+    const res = await api("POST", `/admin/platforms/${platform_id}/roles`, null, body({ name, permissions }));
+    return { content: text(res) };
+});
+
+server.tool("forta_update_role", "Update a role's name or permissions. Changes apply to every user holding the role", {
+    platform_id: z.number().describe("Platform ID"),
+    role_id: z.number().describe("Role ID"),
+    name: z.string().optional().describe("New role name"),
+    permissions: z.array(z.string()).optional().describe("Replacement permission set"),
+}, async ({ platform_id, role_id, name, permissions }) => {
+    const res = await api("PUT", `/admin/platforms/${platform_id}/roles/${role_id}`, null, body({ name, permissions }));
+    return { content: text(res) };
+});
+
+server.tool("forta_delete_role", "Delete a role. Users holding it lose its permissions. Destructive", {
+    platform_id: z.number().describe("Platform ID"),
+    role_id: z.number().describe("Role ID"),
+}, async ({ platform_id, role_id }) => {
+    const res = await api("DELETE", `/admin/platforms/${platform_id}/roles/${role_id}`);
+    return { content: text(res) };
+});
+
+// --- Grants ---
+
+server.tool("forta_list_grants", "List access grants — which users can access which platforms, and with what role. Filter by platform_id or user_id; omit both to list all. This is the first place to look when a user gets a 403 from an appleby.cloud service", {
+    platform_id: z.number().optional().describe("Filter to one platform"),
+    user_id: z.number().optional().describe("Filter to one user"),
+}, async ({ platform_id, user_id }) => {
+    const res = await api("GET", "/admin/grants", { platform_id, user_id });
+    return { content: text(res) };
+});
+
+server.tool("forta_create_grant", "Grant a user access to a platform with a specific role", {
+    user_id: z.number().describe("User ID"),
+    platform_id: z.number().describe("Platform ID"),
+    role_id: z.number().describe("Role ID to assign"),
+}, async ({ user_id, platform_id, role_id }) => {
+    const res = await api("POST", "/admin/grants", null, { user_id, platform_id, role_id });
+    return { content: text(res) };
+});
+
+server.tool("forta_revoke_grant", "Revoke a grant, removing a user's access to a platform. Takes effect within the platform's grant cache TTL (typically 30s)", {
+    id: z.number().describe("Grant ID (from forta_list_grants)"),
+}, async ({ id }) => {
+    const res = await api("DELETE", `/admin/grants/${id}`);
+    return { content: text(res) };
+});
+
+server.tool("forta_check_grant", "Check whether the token's user holds an active grant for a platform, by client_id. Mirrors exactly what a service's grant enforcement sees", {
+    client_id: z.string().describe("Platform client_id"),
+}, async ({ client_id }) => {
+    const res = await api("GET", "/internal/grants/check", { client_id });
+    return { content: text(res) };
+});
+
+// --- Token introspection ---
+
+server.tool("forta_introspect_token", "Introspect an access token (RFC 7662) — returns active, sub, exp, iat, client_id, token_type. Use this to diagnose whether a token a service rejected is expired, malformed, or bound to a different platform", {
+    token: z.string().describe("The access token to introspect"),
+}, async ({ token }) => {
+    const res = await api("POST", "/oauth/introspect", null, { token });
+    return { content: text(res) };
+});
+
+// --- API tokens ---
+
+server.tool("forta_list_api_tokens", "List active Forta API tokens with their names, expiry and last_used_at. Token values are never returned", {
+    user_id: z.number().optional().describe("Filter to one user's tokens"),
+    limit: z.number().optional().describe("Max tokens to return"),
+    offset: z.number().optional().describe("Pagination offset"),
+}, async ({ user_id, limit, offset }) => {
+    const res = await api("GET", "/admin/api-tokens", { user_id, limit, offset });
+    return { content: text(res) };
+});
+
+server.tool("forta_create_api_token", "Create a Forta API token owned by the calling user. The plaintext token is returned exactly once and cannot be retrieved again", {
+    name: z.string().describe("Human-readable label, e.g. 'ci-pipeline'"),
+    expires_in: z.enum(["30d", "90d", "365d", "never"]).optional().describe("Lifetime (default 90d)"),
+    scopes: z.string().optional().describe("Optional scope string"),
+}, async ({ name, expires_in, scopes }) => {
+    const res = await api("POST", "/admin/api-tokens", null, body({ name, expires_in, scopes }));
+    return { content: text(res) };
+});
+
+server.tool("forta_revoke_api_token", "Revoke an API token. It stops working within the consuming service's token cache TTL (default 60s). Revoking the token this MCP is using will break this connection", {
+    id: z.number().describe("API token ID"),
+}, async ({ id }) => {
+    const res = await api("DELETE", `/admin/api-tokens/${id}`);
+    return { content: text(res) };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "forta-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Forta OAuth2 identity provider",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "forta-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "forta",
+    "auth", "oauth", "identity", "sso",
+    "model-context-protocol"
+  ],
+  "author": "Aiden Appleby",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidenappl/forta-mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}