Index of every page on this site: llms.txt
All skills
googleapis avatar

/reproduce-bug

@a5dc5d4
by Google APIsgoogleapis/mcp-toolbox17k stars
1,805
Run it yourself

Reproduce a reported bug in googleapis/mcp-toolbox and decide whether it is real, delivering an evidence-backed verdict: confirmed, already fixed, misconfiguration, client-side, works as intended, not reproducible, or blocked. Use whenever a maintainer asks you to reproduce, verify, confirm, or investigate a bug report, asks "is this a real bug", "can you repro this", "does this still happen", or pastes an mcp-toolbox bug issue or stack trace to check. PROPOSE-ONLY: reproduces locally and reports; never comments on, labels, or closes the issue.

Use this Skill: https://skilld.dev/gh/googleapis/mcp-toolbox/reproduce-bug

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesdiscriminators.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Discriminator playbook

One section per false-alarm shape, ranked by how often it fires. Each gives the confirmation step, the fix, and the traps.

The shapes are stable, since they are ways people misread a tool rather than facts about the code. The error wording is not stable. Any error text quoted here is an illustration, not a fingerprint. Confirm it against the tree with the trace recipe in SKILL.md before quoting it to a reporter, and never conclude "that string does not exist, so the report is bogus": it may be their version's wording. Facts about released versions are frozen and safe to rely on; facts about main drift.

Wrong tool type

The most common misconfiguration. A source type is used where a tool type belongs, usually mysql instead of mysql-sql, because the reporter copied the source documentation page into their tools: block.

Confirm. Look up what is actually registered rather than trusting a list:

grep -rn 'resourceType string = ' --include="*.go" internal/tools/ | grep -i mysql
grep -rn 'SourceType string = ' --include="*.go" internal/sources/ | grep -i mysql

Tool types are registered in internal/tools/** and source types in internal/sources/**, each via a Register call in init(). If a value only appears under internal/sources/, it is not a tool type.

The raising sites are ErrUnknownToolType (internal/tools/tools.go) and the unknown source type error in internal/sources/sources.go. Wording has changed at least once, so match on the reporter's text, not on a remembered string.

Fix. Change the value, not the field name. This fails before any connection, so it reproduces at rung 1 with no database.

Trap. In legacy nested configs the field is spelled kind:, and that is correct for that format. Do not tell a reporter to rename kind to type. See the format mapping in repro-env.md.

Version skew

Docs track main, releases lag, so a reporter follows current documentation against an older binary and hits a field or flag that does not exist yet.

Confirm.

git log -S '<their exact error text>'                    # when did this wording exist
git log --oneline v<their-version>..HEAD -- <path>       # did the feature or fix land after them

An unknown-field error naming a field that is documented is the signature.

Fix. Point at the release that contains it, or note it is unreleased. This is already-fixed, not confirmed, and it needs a release note rather than code.

Trap. Trust their --version string over their prose. "Latest" and a :latest container tag are not versions. See the compatibility table in repro-env.md for what changed when.

Client-side

The failure is in an SDK, CLI, IDE extension, or the LLM itself, and the server is behaving correctly.

Confirm. Replay the same call as raw JSON-RPC against /mcp with curl (commands in repro-env.md). A correct server response settles it: the fault is above the transport.

Traps.

  • An agent-fixable failure (bad SQL, missing record) returns HTTP 200 with isError: true in the result, which reporters read as the server swallowing their error. An infrastructure or auth failure returns a 4XX/5XX JSON-RPC error instead, so a non-200 is not automatically wrong. Check which category applies before judging the response: see the error taxonomy in repro-env.md.
  • A request to /api/* judged against MCP expectations is a category error.
  • The bug may belong in an SDK repo. Say which one rather than closing flatly.

Parameter semantics

Parameters bind values. A placeholder in an identifier position never worked and is not a regression.

Confirm. Locate the placeholder in the statement.

  • Value position, WHERE id = $1: supported.
  • Identifier position, FROM $1 or DESCRIBE $1: works as intended. Template parameters are the supported mechanism.

Trap. Placeholder syntax is dialect-specific (? for MySQL and SQLite, $1 for Postgres, @name for MSSQL and BigQuery). The wrong style for the dialect is a different finding from the wrong position. Confirm the dialect's style from its tool implementation under internal/tools/ before calling it.

Deliberate behaviour change

Something that worked stopped working at an upgrade because a flag now gates it.

Confirm. Diff their flags against the release notes for their version bump, and find the commit with git log --oneline --grep='feat!' v<theirs>..HEAD.

The known instance is --enable-api: /api was ungated before v0.31.0, off by default from v0.31.0, and the status code when off changed between releases (bare 404 on v0.31.0, 410 with an explanatory message after). Match on the endpoint plus the upgrade, never on the status code.

Trap. A gate that surfaces as a bare 404 with no explanation is a real usability bug even when the gating is intended. Record it under secondary.

Database-side

Permissions, a missing extension, a firewall, or a maintenance state. Outside Toolbox entirely.

Confirm. Ask whether the identical statement with the identical credentials succeeds through psql, mysql, or the provider console. If it fails there too, Toolbox is the messenger.

Trap. Toolbox mishandling a database error is a Toolbox bug. Returning a silent nil instead of surfacing a permission error has been a real defect. The question is not "did the database fail" but "did Toolbox report the failure faithfully".

Credential escaping

Passwords with reserved characters, or ${ENV_VAR} substitution.

Confirm. Retry with a trivial alphanumeric password. If it succeeds, the issue is escaping rather than authentication.

Trap. Do not auto-dismiss this shape. Both connection-string escaping and environment-variable substitution have been genuine bugs. "Their password had a special character" is the start of the investigation, not the verdict. Never paste a real credential into a config, a command, or the report.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill provides a structured workflow for reproducing bug reports in the mcp-toolbox project. It includes standard development activities such as fetching issue details from GitHub, performing local builds, and using official vendor binaries for version verification. While the skill processes untrusted input from external bug reports, it incorporates best practices such as working in isolated scratch directories and avoiding the use of actual credentials.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

Signed by skilld at a5dc5d4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for googleapis/mcp-toolbox/reproduce-bug