Merge pull request #96 from mailtrap/add-missing-general-tools

Add missing general tools

Author: IgorDobryn

CLAUDE.md

@@ -163,4 +163,19 @@ Schema files define a JSON Schema–shaped object for MCP; optional Zod schemas
 - **create-contact-export**: Export contacts matching AND-combined filters (`name`/`operator`/`value`). Returns an export job; poll for download URL.
 - **get-contact-export**: Get the status of a contact export job. `url` is populated when `status: finished`.
 
+
+#### General / Account-admin
+
+- **list-accounts**: List Mailtrap accounts the API token can access (with each account's `access_levels`).
+- **get-billing-usage**: Current billing cycle usage (plans, limits, current counts) for the account.
+- **list-account-accesses**: List users/invites/tokens with access to the account, optional filters by domain/inbox/project. Requires admin.
+- **remove-account-access**: Revoke permissions (User) or delete the specifier (Invite/ApiToken). Requires admin.
+- **get-permission-resources**: Hierarchical list of inboxes/projects/domains/billing/account the token has admin access to.
+- **bulk-update-permissions**: Create/update/destroy multiple permissions on an account access in one call.
+- **list-api-tokens**: List all API tokens for the account.
+- **create-api-token**: Create an API token. Response includes the secret `token` value (returned only on creation — must be stored).
+- **get-api-token**: Get an API token by ID (metadata only — secret is not returned).
+- **reset-api-token**: Rotate an API token. Response includes the new secret `token` value; previous one is invalidated.
+- **delete-api-token**: Permanently delete an API token by ID.
+
 Tools use input schemas (JSON Schema format) for MCP; handlers may validate input with Zod. Response format follows the MCP protocol.

README.md

@@ -827,6 +827,105 @@ Get the status of a contact export job. Once `status` is `finished`, the `url` f
 
 - `export_id` (required): ID of the contact export job
 
+### list-accounts
+
+List Mailtrap accounts the current API token can access, with each account's access levels.
+
+**Parameters:**
+
+- No parameters required
+
+### get-billing-usage
+
+Get the current billing cycle usage for the account: sending and testing plans, limits, and current counts.
+
+**Parameters:**
+
+- No parameters required
+
+### list-account-accesses
+
+List account accesses (users, invites, API tokens) for the account. Optional filters narrow the result to specific resources. Requires account admin/owner permissions.
+
+**Parameters:**
+
+- `domain_uuids` (optional): Filter by sending domain UUIDs (array of strings)
+- `inbox_ids` (optional): Filter by sandbox inbox IDs (array of strings)
+- `project_ids` (optional): Filter by sandbox project IDs (array of strings)
+
+### remove-account-access
+
+Remove an account access by ID. For `User` specifiers this revokes their permissions; for `Invite` or `ApiToken` specifiers it removes the specifier entirely. Requires admin/owner.
+
+**Parameters:**
+
+- `account_access_id` (required): ID of the access record to remove
+
+### get-permission-resources
+
+Get all resources (inboxes, projects, domains, billing, account) to which the API token has admin access, nested by hierarchy.
+
+**Parameters:**
+
+- No parameters required
+
+### bulk-update-permissions
+
+Bulk create, update, or destroy permissions for a single account access. Existing `(resource_type, resource_id)` pairs are updated; new ones are created. Set `destroy: true` on an entry to remove it.
+
+**Parameters:**
+
+- `account_access_id` (required): Target account access ID
+- `permissions` (required): Array of permission entries. Each has:
+  - `resource_id` (required): Resource ID (number or string)
+  - `resource_type` (required): One of `account`, `project`, `inbox`, `domain`, `billing`
+  - `access_level` (optional): `admin`/`100` or `viewer`/`10`
+  - `destroy` (optional, boolean): When true, removes this permission instead of creating/updating it
+
+### list-api-tokens
+
+List all API tokens for the account.
+
+**Parameters:**
+
+- No parameters required
+
+### create-api-token
+
+Create a new API token. The response includes the secret `token` value — this is the **only time** the full token is returned, so store it immediately. If you lose it, recreate the token.
+
+**Parameters:**
+
+- `name` (required): Display name for the token
+- `resources` (optional): Array of resource permissions to scope the token to. Each entry has:
+  - `resource_type` (required): One of `account`, `project`, `inbox`, `domain`, `billing`
+  - `resource_id` (required): ID of the resource
+  - `access_level` (required): `100` (admin) or `10` (viewer)
+
+### get-api-token
+
+Get an API token by ID. Returns metadata only — the secret token value is **not** returned here (only from `create-api-token` / `reset-api-token`).
+
+**Parameters:**
+
+- `api_token_id` (required): ID of the API token
+
+### reset-api-token
+
+Reset (rotate) an API token by ID. The response includes the **new** secret `token` value — returned only on this call, so store it immediately. The previous token is invalidated.
+
+**Parameters:**
+
+- `api_token_id` (required): ID of the API token to reset
+
+### delete-api-token
+
+Permanently delete an API token by ID. The token can no longer authenticate after deletion.
+
+**Parameters:**
+
+- `api_token_id` (required): ID of the API token to delete
+
 ## Development
 
 1. Clone the repository:

src/server.ts

@@ -164,6 +164,30 @@ import {
   getContactExport,
   getContactExportSchema,
 } from "./tools/contactExports";
+import { listAccounts, listAccountsSchema } from "./tools/accounts";
+import { getBillingUsage, getBillingUsageSchema } from "./tools/billing";
+import {
+  listAccountAccesses,
+  listAccountAccessesSchema,
+  removeAccountAccess,
+  removeAccountAccessSchema,
+} from "./tools/accountAccesses";
+import {
+  getPermissionResources,
+  getPermissionResourcesSchema,
+  bulkUpdatePermissions,
+  bulkUpdatePermissionsSchema,
+} from "./tools/permissions";
+import {
+  listApiTokens,
+  listApiTokensSchema,
+  createApiToken,
+  createApiTokenSchema,
+  apiTokenSchema,
+  getApiToken,
+  resetApiToken,
+  deleteApiToken,
+} from "./tools/apiTokens";
 
 // Define the tools registry
 const tools = [
@@ -841,6 +865,115 @@ const tools = [
       readOnlyHint: true,
     },
   },
+  {
+    name: "list-accounts",
+    description:
+      "List Mailtrap accounts accessible to the API token, with each account's access levels.",
+    inputSchema: listAccountsSchema,
+    handler: listAccounts,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "get-billing-usage",
+    description:
+      "Get the current billing cycle usage for the account (sending and testing plans, limits, and current counts).",
+    inputSchema: getBillingUsageSchema,
+    handler: getBillingUsage,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "list-account-accesses",
+    description:
+      "List account accesses (users, invites, API tokens) for the account. Optionally scope by domain UUIDs, inbox IDs, or project IDs. Requires account admin/owner permissions.",
+    inputSchema: listAccountAccessesSchema,
+    handler: listAccountAccesses,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "remove-account-access",
+    description:
+      "Remove an account access by ID. For User specifiers this revokes permissions; for Invite or ApiToken specifiers it removes the specifier itself. Requires admin/owner.",
+    inputSchema: removeAccountAccessSchema,
+    handler: removeAccountAccess,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "get-permission-resources",
+    description:
+      "Get all resources (inboxes, projects, domains, billing, account) to which the API token has admin access, nested by hierarchy.",
+    inputSchema: getPermissionResourcesSchema,
+    handler: getPermissionResources,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "bulk-update-permissions",
+    description:
+      "Bulk create, update, or destroy permissions for an account access. Existing (resource_type, resource_id) pairs are updated; new ones are created. Set `destroy: true` to remove.",
+    inputSchema: bulkUpdatePermissionsSchema,
+    handler: bulkUpdatePermissions,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "list-api-tokens",
+    description: "List all API tokens for the account.",
+    inputSchema: listApiTokensSchema,
+    handler: listApiTokens,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "create-api-token",
+    description:
+      "Create a new API token. The response includes the secret `token` value — this is the **only time** the full token is returned, so store it immediately.",
+    inputSchema: createApiTokenSchema,
+    handler: createApiToken,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "get-api-token",
+    description:
+      "Get an API token by ID. The secret token value is NOT returned here — only the metadata (name, last 4 digits, resources).",
+    inputSchema: apiTokenSchema,
+    handler: getApiToken,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "reset-api-token",
+    description:
+      "Reset (rotate) an API token by ID. The response includes the **new** secret `token` value — returned only on this call, so store it immediately. The previous token is invalidated.",
+    inputSchema: apiTokenSchema,
+    handler: resetApiToken,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "delete-api-token",
+    description:
+      "Permanently delete an API token by ID. The token can no longer authenticate after deletion.",
+    inputSchema: apiTokenSchema,
+    handler: deleteApiToken,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
 ];
 
 export function createServer(): Server {

src/tools/accountAccesses/__tests__/listAccountAccesses.test.ts

@@ -0,0 +1,82 @@
+import listAccountAccesses from "../listAccountAccesses";
+import { requireClient } from "../../../client";
+
+const mockClient = {
+  general: {
+    accountAccesses: {
+      listAccountAccesses: jest.fn(),
+    },
+  },
+};
+
+jest.mock("../../../client", () => ({
+  requireClient: jest.fn(() => mockClient),
+}));
+
+describe("listAccountAccesses", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (requireClient as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it("calls the SDK without filters when none provided", async () => {
+    mockClient.general.accountAccesses.listAccountAccesses.mockResolvedValue([
+      { id: 1, name: "alice@example.com" },
+    ]);
+
+    const result = await listAccountAccesses();
+
+    expect(requireClient).toHaveBeenCalledWith("account accesses");
+    expect(
+      mockClient.general.accountAccesses.listAccountAccesses
+    ).toHaveBeenCalledWith(undefined);
+    expect(result.content[0].text).toContain('"id": 1');
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("translates snake_case filters to SDK camelCase", async () => {
+    mockClient.general.accountAccesses.listAccountAccesses.mockResolvedValue(
+      []
+    );
+
+    await listAccountAccesses({
+      domain_uuids: ["d-1"],
+      inbox_ids: ["i-2"],
+      project_ids: ["p-3"],
+    });
+
+    expect(
+      mockClient.general.accountAccesses.listAccountAccesses
+    ).toHaveBeenCalledWith({
+      domainUuids: ["d-1"],
+      inboxIds: ["i-2"],
+      projectIds: ["p-3"],
+    });
+  });
+
+  it("rejects invalid input before calling the SDK", async () => {
+    const result = await listAccountAccesses({ domain_uuids: "not-an-array" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain(
+      "Failed to list account accesses: Invalid input:"
+    );
+    expect(result.content[0].text).toContain("domain_uuids");
+    expect(
+      mockClient.general.accountAccesses.listAccountAccesses
+    ).not.toHaveBeenCalled();
+  });
+
+  it("surfaces API errors", async () => {
+    mockClient.general.accountAccesses.listAccountAccesses.mockRejectedValue(
+      new Error("forbidden")
+    );
+
+    const result = await listAccountAccesses();
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe(
+      "Failed to list account accesses: forbidden"
+    );
+  });
+});