Find tenants in an Octopus Deploy space

Instructions

Implementation Reference

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

  The main handler function for the 'find_tenants' tool. It either fetches a single tenant by ID (with validation via validateEntityId) or lists all tenants in a space with optional filtering and pagination (skip, take, projectId, tags, ids, partialName). Uses the Octopus Deploy API client to make requests and returns standardized content with public URLs.

  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)

  FindTenantsParams interface defining input parameters: spaceName (required), tenantId, skip, take, projectId, tags, ids, partialName (all optional). The Zod inputSchema in the registration (lines 143-164) mirrors these with descriptions for the MCP tool.

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

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

  Registration of the 'find_tenants' tool. registerFindTenantsTool (line 129) calls server.registerTool with name 'find_tenants', title, description, Zod inputSchema, READ_ONLY_TOOL_ANNOTATIONS, and the handler. registerToolDefinition (line 171) adds it to the global TOOL_REGISTRY under toolset 'tenants' with readOnly: true.

  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,
    );
  }
  
  registerToolDefinition({
    toolName: "find_tenants",
    config: { toolset: "tenants", readOnly: true },
    registerFn: registerFindTenantsTool,
  });

• src/types/tenantsTypes.ts:1-14 (helper)

  TenantResource type definition and tenantsDescription. TenantResource extends SpaceScopedResource and NamedResource with fields: IsDisabled, Slug, Description, ClonedFromTenantId, TenantTags, and ProjectEnvironments (a map of project IDs to environment ID arrays).

  import { type NamedResource, type SpaceScopedResource } from "./baseResource.js";
  
  export const tenantsDescription = "Tenants represent customers or clients in Octopus Deploy, allowing you to manage deployments and configurations specific to each tenant. Tenants can be grouped into tenant tags for easier management and deployment targeting. Tenants can also represent geographical locations, organizational units, or any other logical grouping.";
  
  export interface TenantResource extends SpaceScopedResource, NamedResource {
      IsDisabled: boolean | undefined;
      Slug: string;
      Description: string | null;
      ClonedFromTenantId: string | null;
      TenantTags: string[];
      ProjectEnvironments: {
          [projectId: string]: string[];
      };
  }

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

  Import of findTenants.ts in the central tool index file (src/tools/index.ts), which triggers self-registration when the module is loaded.

  import "./findTenants.js";