list_projects

Instructions

Implementation Reference

• src/tools/listProjects.ts:22-56 (handler)

  The handler function for the 'list_projects' tool. It creates an Octopus Deploy client, queries the project repository for the given space with optional filters, and returns a JSON-formatted response containing project details.

  async ({ spaceName, partialName, skip, take }) => {
    const configuration = getClientConfigurationFromEnvironment();
    const client = await Client.create(configuration);
    const projectRepository = new ProjectRepository(client, spaceName);
  
    const projectsResponse = await projectRepository.list({ partialName, skip, take });
  
    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,
            })),
          }),
        },
      ],
    };
  }

• src/tools/listProjects.ts:12-17 (schema)

  Input schema for the 'list_projects' tool using Zod, defining required 'spaceName' and optional 'partialName', 'skip', 'take' parameters.

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

• src/tools/listProjects.ts:8-58 (registration)

  The registerListProjectsTool function that registers the 'list_projects' tool on the MCP server, including name, description, input schema, metadata, and handler.

  export function registerListProjectsTool(server: McpServer) {
    server.tool(
      "list_projects",
      `This tool lists all projects in a given space. ${projectsDescription} The space name is required, if you can't find the space name, ask the user directly for the name of the space. Optionally filter by partial name match using partialName parameter.`,
      {
        spaceName: z.string(), 
        partialName: z.string().optional(),
        skip: z.number().optional(),
        take: z.number().optional()
      },
      {
        title: "List all projects in an Octopus Deploy space",
        readOnlyHint: true,
      },
      async ({ spaceName, partialName, skip, take }) => {
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
        const projectRepository = new ProjectRepository(client, spaceName);
  
        const projectsResponse = await projectRepository.list({ partialName, skip, take });
  
        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,
                })),
              }),
            },
          ],
        };
      }
    );
  }

• src/tools/listProjects.ts:60-64 (registration)

  Registers the tool definition in the TOOL_REGISTRY, specifying toolset 'projects' and read-only, linking to the register function for conditional registration.

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

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

  The top-level registerTools function that iterates over all tool definitions and calls their registerFn if enabled by config.

  export function registerTools(server: McpServer, config: ToolsetConfig = {}) {
    // Iterate through all registered tools and register those that are enabled
    for (const [, toolRegistration] of TOOL_REGISTRY) {
      if (isToolEnabled(toolRegistration, config)) {
        toolRegistration.registerFn(server);
      }
    }
  }