List all projects in an Octopus Deploy space

Instructions

Implementation Reference

• src/tools/listProjects.ts:28-87 (handler)

  The main handler function for the list_projects tool. Creates an Octopus API client, calls projectRepository.list() with optional partialName/skip/take filters, maps response items to a concise JSON structure, and handles errors via handleOctopusApiError.

      async ({ spaceName, partialName, skip, take }) => {
        try {
          const configuration = getClientConfigurationFromEnvironment();
          const client = await Client.create(configuration);
          const projectRepository = new ProjectRepository(client, spaceName);
  
          const projectsResponse = await projectRepository.list({
            partialName,
            skip,
            take,
          });
  
          if (projectsResponse.Items.length === 0) {
            const message = partialName
              ? `No projects found matching '${partialName}' in space '${spaceName}'. Project names are case-sensitive.`
              : `No projects found in space '${spaceName}'. This space may be empty or you may not have permission to view projects.`;
  
            return {
              content: [
                {
                  type: "text",
                  text: message,
                },
              ],
            };
          }
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  totalResults: projectsResponse.TotalResults,
                  itemsPerPage: projectsResponse.ItemsPerPage,
                  numberOfPages: projectsResponse.NumberOfPages,
                  lastPageNumber: projectsResponse.LastPageNumber,
                  items: projectsResponse.Items.map((project: Project) => ({
                    spaceId: project.SpaceId,
                    id: project.Id,
                    name: project.Name,
                    description: project.Description,
                    slug: project.Slug,
                    deploymentProcessId: project.DeploymentProcessId,
                    lifecycleId: project.LifecycleId,
                    isDisabled: project.IsDisabled,
                    repositoryUrl:
                      project.PersistenceSettings.Type === "VersionControlled"
                        ? project.PersistenceSettings.Url
                        : null,
                  })),
                }),
              },
            ],
          };
        } catch (error) {
          handleOctopusApiError(error, { spaceName });
        }
      },
    );
  }

• src/tools/listProjects.ts:20-25 (schema)

  Input schema (Zod) for list_projects: requires spaceName (string), optional partialName (string), skip (number), take (number).

  inputSchema: {
    spaceName: z.string(),
    partialName: z.string().optional(),
    skip: z.number().optional(),
    take: z.number().optional(),
  },

• src/tools/listProjects.ts:14-16 (registration)

  registerListProjectsTool function that registers the tool with MCP server via server.registerTool('list_projects', ...).

  export function registerListProjectsTool(server: McpServer) {
    server.registerTool(
      "list_projects",

• src/tools/listProjects.ts:89-93 (registration)

  Self-registration call to registerToolDefinition, adding list_projects to the global TOOL_REGISTRY map with toolset 'projects' and readOnly: true.

  registerToolDefinition({
    toolName: "list_projects",
    config: { toolset: "projects", readOnly: true },
    registerFn: registerListProjectsTool,
  });

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

  Import of './listProjects.js' in src/tools/index.ts triggers the self-registration side-effect when the module is loaded.

  import "./listProjects.js";
  import "./listEnvironments.js";