feat(api): expose /system/v1/whoami route

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 106
+configured_endpoints: 107
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/mux%2Fmux-323c1dc63b7a75cbabd3a79dcf80ca0afc9c0ae234f4323a39240a4a841583b9.yml
 openapi_spec_hash: e8fda4e033c6d0e7bc9ee4c629c232fa
-config_hash: 245adfa70ec6f84ba48ccaccc26a546c
+config_hash: 16b19b97f99dd7265b4619c5a999c751

api.md

@@ -356,6 +356,17 @@ Methods:
 - <code title="get /system/v1/signing-keys">client.system.signingKeys.<a href="./src/resources/system/signing-keys.ts">list</a>({ ...params }) -> SigningKeysBasePage</code>
 - <code title="delete /system/v1/signing-keys/{SIGNING_KEY_ID}">client.system.signingKeys.<a href="./src/resources/system/signing-keys.ts">delete</a>(signingKeyId) -> void</code>
 
+## Utilities
+
+Types:
+
+- <code><a href="./src/resources/system/utilities.ts">WhoamiResponse</a></code>
+- <code><a href="./src/resources/system/utilities.ts">UtilityWhoamiResponse</a></code>
+
+Methods:
+
+- <code title="get /system/v1/whoami">client.system.utilities.<a href="./src/resources/system/utilities.ts">whoami</a>() -> UtilityWhoamiResponse</code>
+
 # Webhooks
 
 Types:

packages/mcp-server/README.md

@@ -346,3 +346,7 @@ The following tools are available in this MCP server.
   **The private key is not returned in this response.**
 - `list_system_signing_keys` (`read`): Returns a list of signing keys.
 - `delete_system_signing_keys` (`write`): Deletes an existing signing key. Use with caution, as this will invalidate any existing signatures and no JWTs can be signed using the key again.
+
+### Resource `system.utilities`:
+
+- `whoami_system_utilities` (`read`): Retrieve information about your current access token, including organization, environment, and permissions. Note that this can only be access with an access token, and _all_ access tokens can access this route, regardless of what permissions they have assigned.

packages/mcp-server/src/tools/index.ts

@@ -100,6 +100,7 @@ import create_system_signing_keys from './system/signing-keys/create-system-sign
 import retrieve_system_signing_keys from './system/signing-keys/retrieve-system-signing-keys';
 import list_system_signing_keys from './system/signing-keys/list-system-signing-keys';
 import delete_system_signing_keys from './system/signing-keys/delete-system-signing-keys';
+import whoami_system_utilities from './system/utilities/whoami-system-utilities';
 
 export const endpoints: Endpoint[] = [];
 
@@ -203,6 +204,7 @@ addEndpoint(create_system_signing_keys);
 addEndpoint(retrieve_system_signing_keys);
 addEndpoint(list_system_signing_keys);
 addEndpoint(delete_system_signing_keys);
+addEndpoint(whoami_system_utilities);
 
 export type Filter = {
   type: 'resource' | 'operation' | 'tag' | 'tool';

packages/mcp-server/src/tools/system/utilities/whoami-system-utilities.ts

@@ -0,0 +1,43 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { maybeFilter } from '@mux/mcp/filtering';
+import { Metadata, asTextContentResult } from '@mux/mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import Mux from '@mux/mux-node';
+
+export const metadata: Metadata = {
+  resource: 'system.utilities',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+  httpPath: '/system/v1/whoami',
+  operationId: 'get-whoami',
+};
+
+export const tool: Tool = {
+  name: 'whoami_system_utilities',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRetrieve information about your current access token, including organization, environment, and permissions. Note that this can only be access with an access token, and _all_ access tokens can access this route, regardless of what permissions they have assigned.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/whoami_response',\n  $defs: {\n    whoami_response: {\n      type: 'object',\n      properties: {\n        data: {\n          type: 'object',\n          properties: {\n            access_token_name: {\n              type: 'string'\n            },\n            environment_id: {\n              type: 'string'\n            },\n            environment_name: {\n              type: 'string'\n            },\n            environment_type: {\n              type: 'string'\n            },\n            organization_id: {\n              type: 'string'\n            },\n            organization_name: {\n              type: 'string'\n            },\n            permissions: {\n              type: 'array',\n              items: {\n                type: 'string'\n              }\n            }\n          },\n          required: [            'access_token_name',\n            'environment_id',\n            'environment_name',\n            'environment_type',\n            'organization_id',\n            'organization_name',\n            'permissions'\n          ]\n        }\n      },\n      required: [        'data'\n      ]\n    }\n  }\n}\n```",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: Mux, args: Record<string, unknown> | undefined) => {
+  return asTextContentResult(await maybeFilter(args, await client.system.utilities.whoami()));
+};
+
+export default { metadata, tool, handler };

src/resources/system/index.ts

@@ -8,3 +8,4 @@ export {
   type SigningKeyListParams,
 } from './signing-keys';
 export { System } from './system';
+export { Utilities, type WhoamiResponse, type UtilityWhoamiResponse } from './utilities';

src/resources/system/system.ts

@@ -9,13 +9,17 @@ import {
   SigningKeys,
   SigningKeysBasePage,
 } from './signing-keys';
+import * as UtilitiesAPI from './utilities';
+import { Utilities, UtilityWhoamiResponse, WhoamiResponse } from './utilities';
 
 export class System extends APIResource {
   signingKeys: SigningKeysAPI.SigningKeys = new SigningKeysAPI.SigningKeys(this._client);
+  utilities: UtilitiesAPI.Utilities = new UtilitiesAPI.Utilities(this._client);
 }
 
 System.SigningKeys = SigningKeys;
 System.SigningKeysBasePage = SigningKeysBasePage;
+System.Utilities = Utilities;
 
 export declare namespace System {
   export {
@@ -25,4 +29,10 @@ export declare namespace System {
     SigningKeysBasePage as SigningKeysBasePage,
     type SigningKeyListParams as SigningKeyListParams,
   };
+
+  export {
+    Utilities as Utilities,
+    type WhoamiResponse as WhoamiResponse,
+    type UtilityWhoamiResponse as UtilityWhoamiResponse,
+  };
 }

src/resources/system/utilities.ts

@@ -0,0 +1,45 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../resource';
+import * as Core from '../../core';
+
+export class Utilities extends APIResource {
+  /**
+   * Retrieve information about your current access token, including organization,
+   * environment, and permissions. Note that this can only be access with an access
+   * token, and _all_ access tokens can access this route, regardless of what
+   * permissions they have assigned.
+   */
+  whoami(options?: Core.RequestOptions): Core.APIPromise<UtilityWhoamiResponse> {
+    return (
+      this._client.get('/system/v1/whoami', {
+        defaultBaseURL: 'https://api.mux.com',
+        ...options,
+      }) as Core.APIPromise<{ data: UtilityWhoamiResponse }>
+    )._thenUnwrap((obj) => obj.data);
+  }
+}
+
+export interface WhoamiResponse {
+  data: UtilityWhoamiResponse;
+}
+
+export interface UtilityWhoamiResponse {
+  access_token_name: string;
+
+  environment_id: string;
+
+  environment_name: string;
+
+  environment_type: string;
+
+  organization_id: string;
+
+  organization_name: string;
+
+  permissions: Array<string>;
+}
+
+export declare namespace Utilities {
+  export { type WhoamiResponse as WhoamiResponse, type UtilityWhoamiResponse as UtilityWhoamiResponse };
+}

tests/api-resources/system/utilities.test.ts

@@ -0,0 +1,30 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Mux from '@mux/mux-node';
+import { Response } from 'node-fetch';
+
+const client = new Mux({
+  tokenId: 'my token id',
+  tokenSecret: 'my secret',
+  baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
+});
+
+describe('resource utilities', () => {
+  test('whoami', async () => {
+    const responsePromise = client.system.utilities.whoami();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  test('whoami: request options instead of params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(client.system.utilities.whoami({ path: '/_stainless_unknown_path' })).rejects.toThrow(
+      Mux.NotFoundError,
+    );
+  });
+});