Get task details from an Octopus Deploy URL

Instructions

Implementation Reference

• src/tools/getTaskFromUrl.ts:16-58 (handler)

  Core handler function that extracts a task ID from an Octopus Deploy URL, resolves the space name, fetches full task details via SpaceServerTaskRepository.getDetails(), and returns the task along with URL info.

  export async function getTaskFromUrl(client: Client, params: GetTaskFromUrlParams) {
    const { url } = params;
  
    if (!url) {
      throw new Error("URL is required");
    }
  
    const urlParts = parseOctopusUrl(url);
  
    if (!urlParts.spaceId) {
      throw new Error("Could not extract space ID from URL. URL must contain a space identifier like 'Spaces-1234'");
    }
  
    const spaceName = await resolveSpaceNameFromId(client, urlParts.spaceId);
  
    const taskId = extractTaskId(url);
  
    if (!taskId) {
      throw new Error(
        `Could not extract task ID from URL. ` +
        `URL must contain a task identifier (ServerTasks-XXXXX). ` +
        `If you have a deployment URL, use get_deployment_from_url first to resolve the task ID, ` +
        `then fetch octopus://spaces/{spaceName}/tasks/{taskId}/details for the structured activity tree, or call grep_task_log to search the raw log.`
      );
    }
  
    validateEntityId(taskId, 'task', ENTITY_PREFIXES.task);
  
    const serverTaskRepository = new SpaceServerTaskRepository(client, spaceName);
    const response = await serverTaskRepository.getDetails(taskId);
  
    return {
      task: response,
      resolvedSpaceName: spaceName,
      resolvedTaskId: taskId,
      urlInfo: {
        originalUrl: url,
        extractedSpaceId: urlParts.spaceId,
        extractedTaskId: taskId,
        resourceType: urlParts.resourceType,
      }
    };
  }

• src/tools/getTaskFromUrl.ts:60-111 (handler)

  MCP tool registration with input schema (url: string), description, and the async handler that creates a client, calls getTaskFromUrl(), and returns the JSON result.

  export function registerGetTaskFromUrlTool(server: McpServer) {
    server.registerTool(
      'get_task_from_url',
      {
        title: 'Get task details from an Octopus Deploy URL',
        description: `Get task details from an Octopus Deploy task URL. Returns full task details including execution logs and state.
  
  This tool is a URL-to-ID resolver that returns the **same body** as the \`octopus://spaces/{spaceName}/tasks/{taskId}/details\` resource — no need to dereference the URI afterward. If you only need lightweight metadata for polling (state, timing, completion flags) use the smaller \`octopus://spaces/{spaceName}/tasks/{taskId}\` resource instead.
  
  Accepts task URLs like:
  https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456
  
  Key features:
  - Returns full task details including execution logs
  - Handles space ID to space name resolution automatically
  - Validates task ID format
  
  For deployment URLs:
  If you have a deployment URL, use this workflow:
  1. Call get_deployment_from_url with the deployment URL
  2. Use the returned taskResourceUri (structured tree) or call grep_task_log with the returned taskId to search the raw log
  
  ${tasksDescription}`,
        inputSchema: {
          url: z.string()
            .describe("Full Octopus Deploy task URL containing a task ID (e.g., https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456)")
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      async (args) => {
        const { url } = args as GetTaskFromUrlParams;
  
        if (!url) {
          throw new Error("URL is required");
        }
  
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
  
        const result = await getTaskFromUrl(client, { url });
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    );
  }

• src/tools/getTaskFromUrl.ts:12-14 (schema)

  TypeScript interface defining the input parameter: a single 'url' string.

  export interface GetTaskFromUrlParams {
    url: string;
  }

• src/tools/getTaskFromUrl.ts:113-117 (registration)

  Self-registration via registerToolDefinition, marking the tool as part of the 'tasks' toolset and read-only.

  registerToolDefinition({
    toolName: "get_task_from_url",
    config: { toolset: "tasks", readOnly: true },
    registerFn: registerGetTaskFromUrlTool,
  });

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

  Side-effect import that triggers the self-registration of the get_task_from_url tool when the tools module is loaded.

  import "./getTaskFromUrl.js";