Find accounts in an Octopus Deploy space

Instructions

Implementation Reference

• src/tools/findAccounts.ts:14-113 (handler)

  The main handler function for the find_accounts tool. Registers the tool on the MCP server with logic to either fetch a single account by ID (lines 51-79) or list accounts with pagination/filtering (lines 82-110). Uses the Octopus Deploy API client to call ~/api/{spaceId}/accounts/{id} or ~/api/{spaceId}/accounts endpoints.

  export function registerFindAccountsTool(server: McpServer) {
    server.registerTool(
      "find_accounts",
      {
        title: "Find accounts in an Octopus Deploy space",
        description: `Find accounts in a space - can retrieve a single account by ID or list all accounts
  
  This unified tool can either:
  - Get detailed information about a specific account when accountId is provided
  - List all accounts in a space when accountId is omitted
  
  You can optionally filter by various parameters like name, account type, etc. when listing.`,
        inputSchema: {
          spaceName: z.string(),
          accountId: z.string().optional().describe("The ID of a specific account to retrieve. If omitted, lists all accounts."),
          skip: z.number().optional().describe("Number of accounts to skip for pagination (only used when listing)"),
          take: z.number().optional().describe("Number of accounts to take for pagination (only used when listing)"),
          ids: z.array(z.string()).optional().describe("Filter by specific account IDs (only used when listing)"),
          partialName: z.string().optional().describe("Filter by partial name match (only used when listing)"),
          accountType: z.nativeEnum(AccountType).optional().describe("Filter by account type (only used when listing)"),
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      async ({
        spaceName,
        accountId,
        skip,
        take,
        ids,
        partialName,
        accountType,
      }) => {
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
        const spaceId = await resolveSpaceId(client, spaceName);
  
        // If accountId is provided, get a single account
        if (accountId) {
          validateEntityId(accountId, 'account', ENTITY_PREFIXES.account);
  
          try {
            const response = await client.get<AccountResource>(
              "~/api/{spaceId}/accounts/{id}",
              {
                spaceId,
                id: accountId,
              }
            );
  
            const account = mapAccountResource(response);
  
            return {
              content: [
                {
                  type: "text",
                  text: JSON.stringify(account),
                },
              ],
            };
          } catch (error) {
            handleOctopusApiError(error, {
              entityType: 'account',
              entityId: accountId,
              spaceName
            });
          }
        }
  
        // Otherwise, list all accounts
        const response = await client.get<ResourceCollection<AccountResource>>(
          "~/api/{spaceId}/accounts{?skip,take,ids,partialName,accountType}",
          {
            spaceId,
            skip,
            take,
            ids,
            partialName,
            accountType,
          }
        );
  
        const accounts = response.Items.map((account: AccountResource) => mapAccountResource(account));
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                totalResults: response.TotalResults,
                itemsPerPage: response.ItemsPerPage,
                numberOfPages: response.NumberOfPages,
                lastPageNumber: response.LastPageNumber,
                items: accounts,
              }),
            },
          ],
        };
      }
    );
  }

• src/tools/findAccounts.ts:17-36 (schema)

  Input schema for the find_accounts tool. Defines spaceName (required), accountId (optional), skip, take, ids, partialName, and accountType filters using Zod validation with native enum for AccountType.

      {
        title: "Find accounts in an Octopus Deploy space",
        description: `Find accounts in a space - can retrieve a single account by ID or list all accounts
  
  This unified tool can either:
  - Get detailed information about a specific account when accountId is provided
  - List all accounts in a space when accountId is omitted
  
  You can optionally filter by various parameters like name, account type, etc. when listing.`,
        inputSchema: {
          spaceName: z.string(),
          accountId: z.string().optional().describe("The ID of a specific account to retrieve. If omitted, lists all accounts."),
          skip: z.number().optional().describe("Number of accounts to skip for pagination (only used when listing)"),
          take: z.number().optional().describe("Number of accounts to take for pagination (only used when listing)"),
          ids: z.array(z.string()).optional().describe("Filter by specific account IDs (only used when listing)"),
          partialName: z.string().optional().describe("Filter by partial name match (only used when listing)"),
          accountType: z.nativeEnum(AccountType).optional().describe("Filter by account type (only used when listing)"),
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },

• src/tools/findAccounts.ts:115-119 (registration)

  Self-registration of the find_accounts tool into the TOOL_REGISTRY with toolset 'accounts' and readOnly: true.

  registerToolDefinition({
    toolName: "find_accounts",
    config: { toolset: "accounts", readOnly: true },
    registerFn: registerFindAccountsTool,
  });

• src/tools/index.ts:30-31 (registration)

  Import line in index.ts that triggers self-registration of findAccounts.ts when the tools module is loaded.

  import "./findAccounts.js";
  import "./findInterruptions.js";