# FogBugz MCP Helper
## Getting Started
- Configure `FOGBUGZ_BASE` with the full API endpoint, e.g. `https://example.fogbugz.com/api.asp`.
- Set `FOGBUGZ_TOKEN` to a personal API token that has access to the projects you intend to query.
- Avoid hardcoding credentials; prefer environment variables or your MCP client’s secret store.
## Available Tools
- `help`: Returns this guidance document.
- `search_cases`: Run FogBugz query syntax searches. Optional `cols` controls returned columns (comma-separated XML column names).
- `case_events`: Same as `search_cases` but always includes the `events` column (can be very large). Event code reference: https://support.fogbugz.com/article/55756-fogbugz-xml-api-event-codes
- `view_case`: Fetch a specific case with optional `cols`.
- `create_case`: Create a case (`title`, `ixProject` required; supports `event`, `ixArea`, `ixPersonAssignedTo`, `ixBugParent`, `ixFixFor`, `category`, `userStory`).
- `edit_case`: Update title, user story (`userStory`), event, or arbitrary FogBugz fields.
- `add_comment`: Adds an event comment (`text`) to a case.
- `attach_file`: Uploads a base64-encoded attachment (`contentBase64`) as `filename`.
- `list_children`: Lists child cases. Falls back to a search when `ixBugChildren` is absent.
- `case_outline`: Returns the full descendant tree for a case using the FogBugz `outline:<ixBug>` search syntax (handy for epics/parent tracking).
- `resolve_case`: Resolves a case and optionally posts a comment or extra fields.
- `reactivate_case`: Reopens a case and optionally posts a comment or extra fields.
- `list_categories`: Returns FogBugz categories (`ixCategory`, names, metadata).
- `list_areas`: Lists undeleted areas; pass `ixProject` to scope the results to a single project.
- `list_custom_fields`: Returns the custom-field names available on a specific case by querying `plugin_customfield` columns.
- `case_link`: Returns the human-facing FogBugz URL for a case (`https://<base>/f/cases/<ixBug>/`).
- Legacy dotted names (e.g., `fogbugz.help`) still work for backward compatibility.
> `userStory` arguments automatically map to the FogBugz custom field `plugin_customfields_at_fogcreek_com_userxstoryh815` so you never need to remember the raw XML name.
### Query Syntax Tips
- Combine filters with spaces (each term narrows results): `project:"Support" status:active assignedto:"Jane Smith"`.
- Use `ixbug:<id>` for exact matches; `parent:<id>` returns children.
- Phrase searches require quotes (`"memory leak"`); prefix match with `~` (`title:~sync*`).
- Boolean operators and parentheses (`(project:"API" or project:"CLI") and not status:closed`).
- Date filters: `opened:"last 7 days"`, `edited:"this week"`, `due:>2024-12-01`.
- Metadata filters: `type:"Bug"`, `priority:"High"`, `milestone:"Q4 Release"`, `tag:"ui"`.
- Append `cols=field1,field2` to control returned columns (our tools preload a rich default set).
- Test queries in the FogBugz search UI; MCP uses the same syntax/engine.
### Category Notes
- `category` accepts either a FogBugz category ID or one of the friendly names: Bug, Enhancement, Engineering Task, New Feature.
- For custom categories, provide the numeric ID returned by FogBugz (e.g., via `cols="ixCategory"`).
## Error Handling
- FogBugz API errors return their numeric codes and messages. Fix the offending request before retrying.
- Network or parsing failures yield code `-32000`; reattempt after verifying connectivity or credentials.
- Unexpected XML formats throw an "Invalid FogBugz response" error—usually indicates a bad endpoint or HTML error page.
## Recipes
- **Find & inspect a case**
1. Call `search_cases` with `q="project:\"My Project\" status:active"`.
2. Take the desired `ixBug` and call `view_case` with `cols="sTitle,sLatestTextSummary,ixPersonAssignedTo"`.
- **Add a comment to a case**
1. Call `add_comment` with `ixBug` and `text`.
2. Optionally follow with `view_case` to verify `sLatestTextSummary`.
- **Attach diagnostics**
1. Base64-encode the file content.
2. Call `attach_file` with `ixBug`, `filename`, and the encoded string.
3. Confirm via `view_case` with `cols="ixAttachments"` if needed.
- **Create a subcase in a milestone**
1. Call `create_case` with `ixBugParent` set to the parent case ID.
2. Include `ixFixFor` if the case should start in a specific milestone.
3. Add `category` (e.g., `category="Engineering Task"`) to set the case category.
4. Provide optional `ixPersonAssignedTo`, `ixArea`, or `userStory` as needed.
- **Resolve a case with context**
1. Prepare your resolution comment.
2. Call `resolve_case` with `comment` and optional fields like `{ sStatus: "Resolved (Fixed)" }`.
- **Reopen a case**
1. Call `reactivate_case` with `comment` describing the regression.
2. Follow up with `edit_case` if more fields need adjustment.
- **Find all active cases in a milestone**
1. Call `search_cases` (or `case_events` if you need history) with `q="status:active fixfor:\"Milestone Name\""`.
2. Optionally add columns (`cols="ixBug,sTitle,sPersonAssignedTo"`) to tailor the response.
3. Iterate the returned cases or feed them into follow-up tools (`view_case`, `add_comment`, etc.).
- **Bulk edits (by iterating individual calls)**
1. Use `search_cases` to collect the target `ixBug` values.
2. Call `edit_case`, `resolve_case`, `add_comment`, etc. once per case.
3. Throttle your loop (small batches or pauses) to avoid overloading the FogBugz server.
- **Get details for every descendant case**
1. Run `case_outline` with `ixBug=<epic-id>`; the result contains `outline` (root) and `forest` (all top-level branches).
2. Traverse the `children` arrays directly, or for richer fields call `view_case` on each `ixBug`.
3. Combine with `list_children` if you only need a single level of the hierarchy.
4. Use the cols param to include columns for each child. This way you can pull details for many decendants at once. NOTE: Be careful with the cols, because you could inflect a large data pull that may fail.
