Find tenants in an Octopus Deploy space

Instructions

Implementation Reference

• src/tools/findTenants.ts:31-127 (handler)

  Main handler function for find_tenants tool. Retrieves a single tenant by ID (if tenantId provided) or lists all tenants with optional filtering/pagination.

  export async function findTenantsHandler(params: FindTenantsParams) {
    const { spaceName, tenantId, skip, take, projectId, tags, ids, partialName } = params;
    const configuration = getClientConfigurationFromEnvironment();
    const client = await Client.create(configuration);
    const spaceId = await resolveSpaceId(client, spaceName);
  
    // If tenantId is provided, get a single tenant
    if (tenantId) {
      validateEntityId(tenantId, "tenant", ENTITY_PREFIXES.tenant);
  
      try {
        const tenant = await client.get<TenantResource>(
          "~/api/{spaceId}/tenant/{tenantId}",
          { spaceId, tenantId },
        );
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                id: tenant.Id,
                name: tenant.Name,
                slug: tenant.Slug,
                description: tenant.Description,
                isDisabled: tenant.IsDisabled,
                projectEnvironments: tenant.ProjectEnvironments,
                tenantTags: tenant.TenantTags,
                clonedFromTenantId: tenant.ClonedFromTenantId,
                spaceId: tenant.SpaceId,
                publicUrl: getPublicUrl(
                  `${configuration.instanceURL}/app#/{spaceId}/tenants/{tenantId}/overview`,
                  {
                    spaceId: tenant.SpaceId,
                    tenantId: tenant.Id,
                  },
                ),
                publicUrlInstruction: `You can view more details about this tenant in the Octopus Deploy web portal at the provided publicUrl.`,
              }),
            },
          ],
        };
      } catch (error) {
        handleOctopusApiError(error, {
          entityType: "tenant",
          entityId: tenantId,
          spaceName,
        });
      }
    }
  
    // Otherwise, list tenants
    const tenantsResponse = await client.get<ResourceCollection<TenantResource>>(
      "~/api/{spaceId}/tenants{?skip,take,projectId,tags,ids,partialName}",
      {
        spaceId,
        skip,
        take,
        projectId,
        tags,
        ids,
        partialName,
      },
    );
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            totalResults: tenantsResponse.TotalResults,
            itemsPerPage: tenantsResponse.ItemsPerPage,
            numberOfPages: tenantsResponse.NumberOfPages,
            lastPageNumber: tenantsResponse.LastPageNumber,
            items: tenantsResponse.Items.map((tenant) => ({
              id: tenant.Id,
              name: tenant.Name,
              slug: tenant.Slug,
              description: tenant.Description,
              isDisabled: tenant.IsDisabled ?? false,
              tenantTags: tenant.TenantTags,
              clonedFromTenantId: tenant.ClonedFromTenantId,
              spaceId: tenant.SpaceId,
              publicUrl: getPublicUrl(
                `${configuration.instanceURL}/app#/{spaceId}/tenants/{tenantId}/overview`,
                {
                  spaceId: tenant.SpaceId,
                  tenantId: tenant.Id,
                },
              ),
              publicUrlInstruction: `You can view more details about this tenant in the Octopus Deploy web portal at the provided publicUrl.`,
            })),
          }),
        },
      ],
    };
  }

• src/tools/findTenants.ts:20-29 (schema)

  TypeScript interface defining input parameters for findTenantsHandler.

  export interface FindTenantsParams {
    spaceName: string;
    tenantId?: string;
    skip?: number;
    take?: number;
    projectId?: string;
    tags?: string;
    ids?: string[];
    partialName?: string;
  }

• src/tools/findTenants.ts:129-168 (registration)

  Registration function that registers the find_tenants tool with the MCP server, including description, Zod input schema, and read-only annotations.

  export function registerFindTenantsTool(server: McpServer) {
    server.registerTool(
      "find_tenants",
      {
        title: "Find tenants in an Octopus Deploy space",
        description: `Find tenants in a space - can retrieve a single tenant by ID or list all tenants
  
    This unified tool can either:
    - Get details for a specific tenant when tenantId is provided, including the projects and environments the tenant is associated with
    - List all tenants in a space when tenantId is omitted
  
    ${tenantsDescription}
  
    Optionally provide filtering and pagination parameters when listing.`,
        inputSchema: {
          spaceName: z.string().describe("The space name"),
          tenantId: z.string().optional().describe("The ID of a specific tenant to retrieve. If omitted, lists all tenants."),
          skip: z.number().optional().describe("Number of tenants to skip for pagination (only used when listing)"),
          take: z.number().optional().describe("Number of tenants to take for pagination (only used when listing)"),
          projectId: z
            .string()
            .optional()
            .describe("Filter by specific project ID (only used when listing)"),
          tags: z
            .string()
            .optional()
            .describe("Filter by tenant tags (comma-separated list, only used when listing)"),
          ids: z
            .array(z.string())
            .optional()
            .describe("Filter by specific tenant IDs (only used when listing)"),
          partialName: z
            .string()
            .optional()
            .describe("Filter by partial tenant name match (only used when listing)"),
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      findTenantsHandler,
    );

• src/tools/findTenants.ts:171-175 (registration)

  Self-registration of the find_tenants tool into the global TOOL_REGISTRY, marking it as part of the 'tenants' toolset and read-only.

  registerToolDefinition({
    toolName: "find_tenants",
    config: { toolset: "tenants", readOnly: true },
    registerFn: registerFindTenantsTool,
  });

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

  Import in src/tools/index.ts that triggers the self-registration of findTenants.ts when the module is loaded.

  import "./findTenants.js";
  import "./findDeploymentTargets.js";
  import "./findCertificates.js";
  import "./findAccounts.js";