bug-triage

# Bug Triage Triage open bug issues on `apify/apify-mcp-server`. Analyze, draft responses, get approval, post. ## Permissions - **Read-only by default**: listing issues (`gh issue list`), viewing details and comments (`gh issue view`) — do these automatically, no need to ask. - **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**. ## Step 0: Parse arguments `$ARGUMENTS` controls scope: | Input | Behavior | |---|---| | `623 641 639` | Triage specific issue numbers | | `--label bug` | Triage all open issues with label (default: `bug`) | | `--all` | Triage all open bug-labeled issues | | _(empty)_ | Same as `--all` | ## Step 1: Fetch issues Use the arguments parsed in Step 0 to determine what to fetch. **If specific issue numbers were provided**, skip the list queries and fetch each issue directly: ```bash gh issue view <number> --repo apify/apify-mcp-server --comments ``` **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: 1. **By label**: issues with the parsed label 2. **By title prefix**: issues with `[Bug]` in the title (the bug report template adds this, but the label isn't always applied) ```bash # By label (use the label from Step 0, default: bug) gh issue list --repo apify/apify-mcp-server --label <label> --state open --json number,title,labels,createdAt,body --limit 30 # By title prefix (catches unlabeled bug reports) gh issue list --repo apify/apify-mcp-server --state open --search "[Bug] in:title" --json number,title,labels,createdAt,body --limit 30 ``` Merge both lists and deduplicate by issue number. For each issue, fetch full details **including all comments** (comments often contain the real context): ```bash gh issue view <number> --repo apify/apify-mcp-server --comments ``` **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. ## Step 2: Categorize each issue Assign one of these categories: | Category | Criteria | Typical action | |---|---|---| | **Known fix** | Root cause is clear, documented fix exists | Draft response with fix, optionally close | | **Not our bug** | Server logs show it works; issue is in the MCP client (Claude Desktop, Cowork, etc.) | Explain findings, suggest workaround | | **Duplicate** | Same root cause as another open issue | Comment with link, close as duplicate | | **Needs info** | No logs, no config, vague description | Ask for specifics | | **Stale** | We asked for info, no reply for 2+ weeks | Close with helpful pointer | | **Actionable bug** | Real server-side bug we need to fix | Acknowledge, investigate further | ### Common root causes (from past triage) These patterns recur. Check for them first: 1. **SSE endpoint removed** (April 1, 2026): Users on `/sse` URLs get connection failures. Fix: switch to `https://mcp.apify.com` (streamable HTTP). 2. **"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. 3. **"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. 4. **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). 5. **Claude Desktop connector downgrade**: Claude Desktop silently downgrades connectors to older versions. Fix: remove and re-add the connector. ## Step 3: Draft response **Style rules:** - Developer-to-developer, plain language - Concise — 3-8 lines typical, no fluff - Acknowledge the issue and apologize briefly if the user is stuck - Reference documentation when a fix or troubleshooting guide exists - If the server works correctly (logs prove it), say so clearly - If closing, explain why and point to where to go next **Key documentation links:** - Setup guide: `https://docs.apify.com/platform/integrations/mcp` - Claude Desktop troubleshooting: `https://docs.apify.com/platform/integrations/claude-desktop#troubleshooting` - Configurator: `https://mcp.apify.com` **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. **The default recommendation** for connection issues is the remote server: > Add a custom connector in Claude Desktop with URL `https://mcp.apify.com` and follow the OAuth flow. ## Step 4: Present and get approval Present each issue to the user with: 1. **Issue number + title + link** (`https://github.com/apify/apify-mcp-server/issues/<number>`) 2. **Category** (from Step 2) 3. **Summary** — one line on what's going on 4. **Proposed response** — the draft comment in a blockquote 5. **Proposed action** — comment only / comment + close / close as duplicate of #X / skip **MANDATORY: Wait for explicit user approval before posting anything.** Never post, close, or modify an issue without the user saying yes. ## Step 5: Post After approval: ```bash # Comment only gh issue comment <number> --repo apify/apify-mcp-server --body "<response>" # Comment + close gh issue comment <number> --repo apify/apify-mcp-server --body "<response>" && \ gh issue close <number> --repo apify/apify-mcp-server # Close as duplicate gh issue comment <number> --repo apify/apify-mcp-server --body "Closing as a duplicate of #<other> — same root cause. We'll track and update there." && \ gh issue close <number> --repo apify/apify-mcp-server ``` Then move to the next issue. After the last one, print a summary table: | Issue | Category | Action taken | |---|---|---| | #623 | Known fix | Commented, SSE migration | | #639 | Duplicate | Closed as dup of #641 | | ... | ... | ... |