alpaca-issue-tracker

name	alpaca-issue-tracker
description	Interact with the Alpaca Issue Tracker on a WordPress site using the WordPress Abilities API.

Alpaca Issue Tracker Skill

This skill allows a local agent to interact with the Alpaca Issue Tracker plugin installed on a WordPress site. It leverages the WordPress Abilities API (introduced in WordPress 6.9) to list, create, update, delete, and comment on issues programmatically.

For developer-oriented reference (permissions, payloads, and REST vs Abilities boundaries), see docs/developer/abilities-api.md in the plugin repository.

Authentication: "Authorize Application" Flow

To access the Abilities API endpoints, the agent must authenticate using WordPress Application Passwords. The recommended approach is the interactive Authorize Application flow.

Step 1: Generate Authorization URL

Direct the user to the WordPress Authorize Application screen:

https://<site-domain>/wp-admin/authorize-application.php?app_name=Alpaca+Local+Agent&success_url=<callback-url>&app_id=<unique-uuid>

• <site-domain>: The domain of the WordPress site.
• app_name: A user-friendly name for your agent.
• success_url (optional): The URL to redirect the user back to upon approval. If this parameter is omitted, the user will be presented with the generated Application Password directly in the WordPress browser UI, and they will need to manually copy and paste the password back into the agent.
• app_id (optional): A unique UUID generated by the agent.

Step 2: Capture Credentials

Depending on whether success_url was provided:

Option A: Automatic Redirect (with success_url)

Once the user approves the application, WordPress will redirect them to your success_url with the following query parameters:

<callback-url>?siteurl=https%3A%2F%2Fexample.com&user_login=agent_user&password=abcd+efgh+ijkl+mnop+qrst+uvwx

Extract and save:

• user_login: The username.
• password: The generated 24-character Application Password (strip spaces when using).

Option B: Manual Copy/Paste (without success_url)

If success_url is omitted, the user approves the application, and WordPress displays the new Application Password on screen. The user must manually copy and paste the password (e.g. abcd efgh ijkl mnop qrst uvwx) and provide their WordPress username back to the agent.

Step 3: Make Authenticated Requests

All subsequent REST API calls should include standard HTTP Basic Authentication headers using the username and the clean Application Password (spaces removed).

---

Invoking Abilities via the REST API

All abilities are exposed under the standard WordPress Abilities API endpoint namespace:

/wp-json/wp-abilities/v1/abilities/

• List All Abilities: GET /wp-json/wp-abilities/v1/abilities
• Execute an Ability: POST /wp-json/wp-abilities/v1/abilities/<ability-name>/run with body {"input": {...}}

---

Available Abilities Reference

1. alpaca/get-board

Retrieves the current project board columns (statuses) and all top-level issues.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/get-board/run
• Input Parameters: None.
• Example Response:

  [
    {
      "id": 12,
      "title": "Backlog",
      "issues": [
        {
          "id": 145,
          "title": "Fix navbar alignment",
          "slug": "fix-navbar-alignment",
          "comment_count": 2,
          "assignees": [],
          "labels": [],
          "meta": {
            "alpaca_high_priority": false,
            "lastActivity": "2026-06-04T14:00:00Z"
          }
        }
      ]
    }
  ]
  

2. alpaca/create-issue

Creates a new issue in the tracker.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/create-issue/run
• Input Parameters:
  • feedback (string, required): The title or content of the issue.
  • is_high_priority (boolean, optional): Whether to mark it as high priority.
• Example Request:

  {
    "input": {
      "feedback": "Database query timeout on dashboard",
      "is_high_priority": true
    }
  }
  

• Example Response:

  {
    "post_id": 146,
    "issue": {
      "id": 146,
      "slug": "database-query-timeout-on-dashboard",
      "title": "Database query timeout on dashboard",
      "author_id": 1,
      "author_name": "Admin",
      "meta": {
        "alpaca_high_priority": true
      }
    },
    "statusId": 12
  }
  

3. alpaca/get-issue

Retrieves detailed information for a specific issue.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/get-issue/run
• Input Parameters:
  • id (integer, required): The issue ID.
• Example Request:

  {
    "input": {
      "id": 146
    }
  }
  

• Example Response:

  {
    "success": true,
    "post_id": 146,
    "post_data": {
      "ID": 146,
      "post_title": "Database query timeout on dashboard",
      "post_content": "Database query timeout on dashboard",
      "post_author": "1"
    },
    "meta": {
      "alpaca_high_priority": true
    },
    "taxonomies": {
      "alpaca_status": [
        {
          "term_id": 12,
          "name": "Backlog",
          "slug": "backlog"
        }
      ]
    },
    "subissues": [],
    "comment_count": 0
  }
  

4. alpaca/update-issue

Updates specified fields of a given issue.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/update-issue/run
• Input Parameters:
  • id (integer, required): The ID of the issue.
  • title (string, optional): The new title.
  • content (string, optional): The new content/description.
  • status_id (integer, optional): The ID of the status term to assign.
  • is_high_priority (boolean, optional): High priority state.
  • parent_id (integer, optional): Parent issue ID (0 to remove parent).
  • assignees (array of strings, optional): Array of user slugs.
• Example Request:

  {
    "input": {
      "id": 146,
      "status_id": 13,
      "assignees": ["john_doe"]
    }
  }
  

• Example Response:

  {
    "post_id": 146,
    "issue": {
      "id": 146,
      "title": "Database query timeout on dashboard"
    },
    "statusId": 13
  }
  

5. alpaca/delete-issue

Moves a specific issue to the trash.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/delete-issue/run
• Input Parameters:
  • id (integer, required): The ID of the issue.
• Example Request:

  {
    "input": {
      "id": 146
    }
  }
  

• Example Response:

  {
    "success": true,
    "message": "Issue moved to trash successfully.",
    "id": 146
  }
  

6. alpaca/add-comment

Posts a comment (of hidden comment type issuecomment) on an issue.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/add-comment/run
• Input Parameters:
  • issue_id (integer, required): The ID of the issue.
  • content (string, required): The comment text.
• Example Request:

  {
    "input": {
      "issue_id": 146,
      "content": "This seems to be resolved after optimizing the index."
    }
  }
  

• Example Response:

  {
    "success": true,
    "comment_id": 204,
    "comment": {
      "id": 204,
      "content": "This seems to be resolved after optimizing the index.",
      "author_name": "Admin",
      "date": "2026-06-04 14:15:00"
    }
  }
  

7. alpaca/get-comments

Retrieves comments posted on an issue.

• Endpoint: POST /wp-json/wp-abilities/v1/abilities/alpaca/get-comments/run
• Input Parameters:
  • issue_id (integer, required): The ID of the issue.
• Example Request:

  {
    "input": {
      "issue_id": 146
    }
  }
  

• Example Response:

  [
    {
      "id": 204,
      "content": "This seems to be resolved after optimizing the index.",
      "author_name": "Admin",
      "author_id": 1,
      "author_user_agent": "human",
      "author_details": {
        "id": 1,
        "name": "Admin",
        "display_name": "Admin",
        "avatar": "https://example.com/avatar-48.png",
        "avatar_urls": {
          "24": "https://example.com/avatar-24.png",
          "48": "https://example.com/avatar-48.png",
          "96": "https://example.com/avatar-96.png"
        }
      },
      "meta": {
        "alpacaCommentTags": [],
        "alpacaNotificationContext": {},
        "alpacaCommentAttachments": [],
        "alpacaMentionedUsers": [],
        "alpacaCommentLastEdit": {}
      },
      "date": "2026-06-04 14:15:00",
      "date_gmt": "2026-06-04 18:15:00"
    }
  ]
  

---

Current Ability Surface Limitations

The current Abilities API integration exposes the core issue, board, and comment actions listed above. Some Alpaca Issue Tracker features remain available through the WordPress admin UI or existing REST endpoints, but are not currently supported as ability actions.

Agents should treat the following as unsupported through abilities for now:

• Creating, updating, deleting, or assigning labels. Label data may appear in board or issue responses, but label management still uses the plugin's REST/UI flow.
• Creating, updating, completing, deleting, or restoring subissues (checklist items). alpaca/get-issue may return existing subissues, but subissue management still uses the plugin's REST/UI flow.
• Setting or clearing issue deadlines. Deadline values may appear in issue/card metadata, but deadline writes still use the plugin's REST/UI flow.
• Reordering board columns or cards beyond status changes. Ability status changes can move an issue between statuses and update that issue's column order, but they do not expose full board drag-and-drop ordering.
• Uploading, deleting, or attaching files to comments. Attachment metadata may appear in comment responses, but file operations still use the plugin's REST/UI flow.
• Capturing browser context, screenshots, or page data during issue creation. alpaca/create-issue only accepts issue feedback and high-priority state.
• Restoring trashed issues. alpaca/delete-issue can move an issue to trash, but undelete/restore still uses the plugin's REST/UI flow.
• Reading or updating notification preferences. Notification settings still use the plugin's REST/UI flow.

---

Model Context Protocol (MCP) Adapter Support

If the WordPress site has the WordPress MCP Adapter installed, these registered abilities are automatically exposed to MCP clients as native MCP tools.

Tool Name Mapping

The MCP Adapter automatically translates namespaced ability names by replacing forward slashes (/) with hyphens (-).

The mapping is as follows:

Abilities API Name	MCP Tool Name
alpaca/get-board	alpaca-get-board
alpaca/create-issue	alpaca-create-issue
alpaca/get-issue	alpaca-get-issue
alpaca/update-issue	alpaca-update-issue
alpaca/delete-issue	alpaca-delete-issue
alpaca/add-comment	alpaca-add-comment
alpaca/get-comments	alpaca-get-comments