Bug Triage

1---
2name: bug-triage
3description: >-
4  Triage open GitHub bug issues for Apify MCP server. Fetches issues, analyzes
5  root causes, drafts developer-to-developer responses, and posts after user
6  approval. Use when handling user bug reports, responding to issues, or
7  cleaning up stale bugs.
8argument-hint: "[issue numbers] [--label <label>] [--all]"
9allowed-tools: [Read, Glob, Grep, Bash, WebFetch, Agent]
10---
11 
12# Bug Triage
13 
14Triage open bug issues on `apify/apify-mcp-server`. Analyze, draft responses, get approval, post.
15 
16## Permissions
17 
18- **Read-only by default**: listing issues (`gh issue list`), viewing details and comments (`gh issue view`) — do these automatically, no need to ask.
19- **Write requires approval**: commenting (`gh issue comment`), closing (`gh issue close`), editing (`gh issue edit`) — **always present the draft and wait for explicit user approval before executing**.
20 
21## Step 0: Parse arguments
22 
23`$ARGUMENTS` controls scope:
24 
25| Input | Behavior |
26|---|---|
27| `623 641 639` | Triage specific issue numbers |
28| `--label bug` | Triage all open issues with label (default: `bug`) |
29| `--all` | Triage all open bug-labeled issues |
30| _(empty)_ | Same as `--all` |
31 
32## Step 1: Fetch issues
33 
34Use the arguments parsed in Step 0 to determine what to fetch.
35 
36**If specific issue numbers were provided**, skip the list queries and fetch each issue directly:
37 
38```bash
39gh issue view <number> --repo apify/apify-mcp-server --comments
40```
41 
42**Otherwise** (label mode, `--all`, or empty), fetch open bug reports. Use the label from Step 0 (default: `bug`). Bug reports come in two forms — find both:
43 
441. **By label**: issues with the parsed label
452. **By title prefix**: issues with `[Bug]` in the title (the bug report template adds this, but the label isn't always applied)
46 
47```bash
48# By label (use the label from Step 0, default: bug)
49gh issue list --repo apify/apify-mcp-server --label <label> --state open --json number,title,labels,createdAt,body --limit 30
50 
51# By title prefix (catches unlabeled bug reports)
52gh issue list --repo apify/apify-mcp-server --state open --search "[Bug] in:title" --json number,title,labels,createdAt,body --limit 30
53```
54 
55Merge both lists and deduplicate by issue number.
56 
57For each issue, fetch full details **including all comments** (comments often contain the real context):
58 
59```bash
60gh issue view <number> --repo apify/apify-mcp-server --comments
61```
62 
63**Always read comments before drafting a response.** Previous team members may have already replied, asked for details, or provided workarounds. Don't duplicate existing responses.
64 
65## Step 2: Categorize each issue
66 
67Assign one of these categories:
68 
69| Category | Criteria | Typical action |
70|---|---|---|
71| **Known fix** | Root cause is clear, documented fix exists | Draft response with fix, optionally close |
72| **Not our bug** | Server logs show it works; issue is in the MCP client (Claude Desktop, Cowork, etc.) | Explain findings, suggest workaround |
73| **Duplicate** | Same root cause as another open issue | Comment with link, close as duplicate |
74| **Needs info** | No logs, no config, vague description | Ask for specifics |
75| **Stale** | We asked for info, no reply for 2+ weeks | Close with helpful pointer |
76| **Actionable bug** | Real server-side bug we need to fix | Acknowledge, investigate further |
77 
78### Common root causes (from past triage)
79 
80These patterns recur. Check for them first:
81 
821. **SSE endpoint removed** (April 1, 2026): Users on `/sse` URLs get connection failures. Fix: switch to `https://mcp.apify.com` (streamable HTTP).
83 
842. **"Tools connected but Claude ignores them"**: MCP server logs show successful handshake and `tools/list`, but Claude doesn't use the tools in conversation. This is a Claude Desktop/Cowork behavior, not an Apify server bug. Users need to explicitly ask Claude to use Apify tools.
85 
863. **"Unable to connect to extension server"**: Claude Desktop extension install issues. Usually caused by corrupted npx cache, Claude silently downgrading the extension, or Node.js not on the GUI app's PATH. Fix: use the remote server `https://mcp.apify.com` as a custom connector.
87 
884. **npx cache corruption**: Stale cache prevents stdio server from starting. Fix: `rm -rf ~/.npm/_npx` (macOS/Linux) or `rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx` (Windows).
89 
905. **Claude Desktop connector downgrade**: Claude Desktop silently downgrades connectors to older versions. Fix: remove and re-add the connector.
91 
92## Step 3: Draft response
93 
94**Style rules:**
95- Developer-to-developer, plain language
96- Concise — 3-8 lines typical, no fluff
97- Acknowledge the issue and apologize briefly if the user is stuck
98- Reference documentation when a fix or troubleshooting guide exists
99- If the server works correctly (logs prove it), say so clearly
100- If closing, explain why and point to where to go next
101 
102**Key documentation links:**
103- Setup guide: `https://docs.apify.com/platform/integrations/mcp`
104- Claude Desktop troubleshooting: `https://docs.apify.com/platform/integrations/claude-desktop#troubleshooting`
105- Configurator: `https://mcp.apify.com`
106 
107**Use Apify MCP tools** (`search-apify-docs`, `fetch-apify-docs`) to find the right doc link if the issue touches a topic not covered above.
108 
109**The default recommendation** for connection issues is the remote server:
110 
111> Add a custom connector in Claude Desktop with URL `https://mcp.apify.com` and follow the OAuth flow.
112 
113## Step 4: Present and get approval
114 
115Present each issue to the user with:
1161. **Issue number + title + link** (`https://github.com/apify/apify-mcp-server/issues/<number>`)
1172. **Category** (from Step 2)
1183. **Summary** — one line on what's going on
1194. **Proposed response** — the draft comment in a blockquote
1205. **Proposed action** — comment only / comment + close / close as duplicate of #X / skip
121 
122**MANDATORY: Wait for explicit user approval before posting anything.** Never post, close, or modify an issue without the user saying yes.
123 
124## Step 5: Post
125 
126After approval:
127 
128```bash
129# Comment only
130gh issue comment <number> --repo apify/apify-mcp-server --body "<response>"
131 
132# Comment + close
133gh issue comment <number> --repo apify/apify-mcp-server --body "<response>" && \
134gh issue close <number> --repo apify/apify-mcp-server
135 
136# Close as duplicate
137gh issue comment <number> --repo apify/apify-mcp-server --body "Closing as a duplicate of #<other> — same root cause. We'll track and update there." && \
138gh issue close <number> --repo apify/apify-mcp-server
139```
140 
141Then move to the next issue. After the last one, print a summary table:
142 
143| Issue | Category | Action taken |
144|---|---|---|
145| #623 | Known fix | Commented, SSE migration |
146| #639 | Duplicate | Closed as dup of #641 |
147| ... | ... | ... |
148