report-issue

When to Use

Typical triggers:

• A git tool handler returns wrong results or throws on valid input
• A git provider (CliGitProvider) fails or misbehaves — wrong output parsing, error transformation, timeout handling
• Transport bugs — HTTP (Hono + Streamable HTTP), stdio, SSE framing, session handling
• Auth bugs — JWT / OAuth / scope enforcement
• Storage backend misbehaves — in-memory, filesystem, supabase, cloudflare
• Domain logic errors — wrong git output, missing edge cases, bad state transitions
• Resource handlers return stale, incomplete, or incorrect data
• Missing or incorrect .describe() on schema fields causing poor LLM tool use
• Feature requests — new git operations, verbosity levels, response fields, auth strategies, storage providers

For general gh CLI workflows outside issue filing (PRs, workflows, API access), see the github-cli skill.

Before Filing

1. Confirm the repo:

   gh repo view --json nameWithOwner -q '.nameWithOwner'
   

   Should output cyanheads/git-mcp-server.

2. Search existing issues:

   gh issue list --search "your error message or keyword"
   

3. Reproduce the issue — confirm it's reproducible. Note the exact input, transport mode (stdio/http), git provider (cli), and any relevant env vars (GIT_SIGN_COMMITS, GIT_BASE_DIR, STORAGE_PROVIDER_TYPE, etc.).

4. Check logs — review server output and, if running HTTP, the response body for structured error details (McpError code + context).

5. Capture versions — bun pm ls @cyanheads/git-mcp-server, bun --version, git --version, OS version.

Writing Well-Structured Issues

Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).

• Lead with specifics. Name the tool, provider, resource, or symptom. "Currently git_merge throws McpError(INTERNAL_ERROR) on a CONFLICT exit instead of returning {conflicts: true}" beats "Merge is broken." A reader should know what's wrong before the end of the first sentence.
• Embed library/service links on first mention. [Hono](https://hono.dev/), [tsyringe](https://github.com/microsoft/tsyringe), [jose](https://github.com/panva/jose). Link to the canonical repo so readers can verify the dependency and reach docs in one click.
• Use owner/repo#N for cross-repo issue references. GitHub auto-renders them as linked references (e.g. cyanheads/mcp-ts-template#46). Bare #N only works for same-repo issues.
• Add a Related: #N line near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
• Lead design sections with a philosophy sentence. Bold a short principle before the tradeoff details — e.g. "Philosophy: conflicts are a structured success, not an error." Establishes the lens for the rest of the section.
• Prefer Markdown tables for comparisons. When showing options, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
• Separate ### Scope from ### Out of scope. The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
• Use Depends on: owner/repo#N to declare ordering explicitly when implementation is blocked on another issue landing first.
• Skip collaborator-framing sign-offs. Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.