proofhub_parse_url

Instructions

Implementation Reference

• index.js:194-204 (handler)

  Handler for proofhub_parse_url tool. Calls parseProofHubUrl() to extract project/list/task IDs from a ProofHub URL, then returns them as JSON. Throws if no task ID is found.

  // ── proofhub_parse_url ───────────────────────────────────────────────
  if (name === 'proofhub_parse_url') {
    const ids = parseProofHubUrl(args.url);
    if (!ids.taskId) throw new Error('Could not find a task ID in the URL.');
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(ids, null, 2),
      }],
    };
  }

• index.js:104-116 (schema)

  Tool schema registration for proofhub_parse_url, defining its name, description, and inputSchema (requires a 'url' string property).

  {
    name: 'proofhub_parse_url',
    description:
      'Parse a ProofHub task URL and return the project ID, list ID, and task ID embedded in it. ' +
      'Use this as the first step before calling other ProofHub tools.',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string', description: 'Full ProofHub task URL, e.g. https://kpi.proofhub.com/bappswift/#app/todos/project-7189443252/list-270280503800/task-514774338823' },
      },
      required: ['url'],
    },
  },

• index.js:102-187 (registration)

  Tool is registered in the ListToolsRequestSchema handler as part of the tools array returned by the MCP server.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'proofhub_parse_url',
        description:
          'Parse a ProofHub task URL and return the project ID, list ID, and task ID embedded in it. ' +
          'Use this as the first step before calling other ProofHub tools.',
        inputSchema: {
          type: 'object',
          properties: {
            url: { type: 'string', description: 'Full ProofHub task URL, e.g. https://kpi.proofhub.com/bappswift/#app/todos/project-7189443252/list-270280503800/task-514774338823' },
          },
          required: ['url'],
        },
      },
      {
        name: 'proofhub_get_task',
        description: 'Fetch full task details (title, description, stage, custom fields, assignees) from ProofHub.',
        inputSchema: {
          type: 'object',
          properties: {
            project_id: { type: 'string' },
            list_id:    { type: 'string' },
            task_id:    { type: 'string' },
          },
          required: ['project_id', 'list_id', 'task_id'],
        },
      },
      {
        name: 'proofhub_get_comments',
        description: 'Fetch all comments on a ProofHub task, including their full text.',
        inputSchema: {
          type: 'object',
          properties: {
            project_id: { type: 'string' },
            list_id:    { type: 'string' },
            task_id:    { type: 'string' },
          },
          required: ['project_id', 'list_id', 'task_id'],
        },
      },
      {
        name: 'proofhub_get_task_with_bug_links',
        description:
          'One-shot tool: given a ProofHub task URL (or IDs), fetches the task description AND all comments, ' +
          'then extracts any bug-tracker links (Jira, Linear, GitHub Issues, GitLab, YouTrack, ClickUp, Asana, etc.) ' +
          'found in any of those texts. Returns the task data plus a deduplicated list of bug links.',
        inputSchema: {
          type: 'object',
          properties: {
            url:        { type: 'string', description: 'Full ProofHub task URL (preferred). If supplied, project_id/list_id/task_id are ignored.' },
            project_id: { type: 'string' },
            list_id:    { type: 'string' },
            task_id:    { type: 'string' },
          },
        },
      },
      {
        name: 'proofhub_create_comment',
        description: 'Post a new comment on a ProofHub task.',
        inputSchema: {
          type: 'object',
          properties: {
            project_id:  { type: 'string' },
            list_id:     { type: 'string' },
            task_id:     { type: 'string' },
            description: { type: 'string', description: 'Comment text (plain text or HTML).' },
          },
          required: ['project_id', 'list_id', 'task_id', 'description'],
        },
      },
      {
        name: 'proofhub_get_task_history',
        description: 'Fetch the activity history of a ProofHub task (stage changes, edits, etc.).',
        inputSchema: {
          type: 'object',
          properties: {
            project_id: { type: 'string' },
            list_id:    { type: 'string' },
            task_id:    { type: 'string' },
          },
          required: ['project_id', 'list_id', 'task_id'],
        },
      },
    ],
  }));

• index.js:56-65 (helper)

  Helper function parseProofHubUrl() that uses regex to extract project-XXX, list-XXX, and task-XXX IDs from a ProofHub URL.

  function parseProofHubUrl(url) {
    const projectMatch = url.match(/project-(\d+)/);
    const listMatch    = url.match(/list-(\d+)/);
    const taskMatch    = url.match(/task-(\d+)/);
    return {
      projectId: projectMatch?.[1] || null,
      listId:    listMatch?.[1]    || null,
      taskId:    taskMatch?.[1]    || null,
    };
  }