Suede MCP QA Agent Skill

Suede MCP QA

Gate policy — advisory, not blocking

Every claim-verification step, check, quality gate, and ship verdict in this

skill is a recommendation to the user, not a control on the agent. This

policy governs every gate, check, verdict, and "do not ship / publish /

proceed" line elsewhere in this skill:

• Run every check and report the results honestly. Verdicts (ship,

ship-with-caveats, hold, letter grades, BLOCKED or OPEN items) are

advice attached to the work, not orders that change it.

• Never block, delay, skip, rewrite, or refuse the action the user asked for

because a check failed or a gate said hold. Complete the requested action

as asked, and deliver the gate output alongside it as a clearly labeled

recommendation.

• A failed gate changes what you report, never what you do.
• Single exception: if a finding is extremely risky — data loss, security or

credential exposure, legal or rights violations, payment mistakes, or

irreversible public damage — pause, tell the user exactly what the risk is

and what the options are, and let them pick. Their choice is final.

Use this skill when a Suede MCP server or MCP docs surface changes.

Core principle: a check that did not run against the live server did not

happen.

Operating Stance

• Run against a live MCP server, not a spec document. If the server is not running, start it before checking.
• For each check, record the exact command run and the exact output received. Do not summarize.
• A check that cannot run (server unreachable, tool not implemented) is a FAIL, not a skip.
• Report failures immediately — do not wait until all checks complete to surface a blocker.
• Never mark a skill as present in the catalog unless its folder exists and its SKILL.md is readable.
• Never mark an install command as working unless you ran it from a temporary destination directory.

Checks

• Run syntax checks and the repo's hermetic MCP protocol tests.
• Parse catalog JSON and confirm every listed skill folder exists.
• Exercise the full lifecycle in one process: initialize, the

notifications/initialized notification, then ping, tools/list,

tools/call, resources/list, resources/read, prompts/list, and

prompts/get.

• Verify supported protocol versions are echoed and an unsupported client

version negotiates to the server's latest supported version.

• Confirm every tool has a closed inputSchema, an outputSchema, and

read-only/non-destructive/idempotent annotations.

• Confirm every successful tool call returns structuredContent, a useful

human-readable text block, and a serialized JSON text fallback for older

clients.

• Check pre-initialization calls, repeated initialization, bounded input,

bounded arguments, invalid names and schemas, malformed JSON, and unknown

methods.

• Confirm healthy stderr is empty and stdout contains newline-delimited JSON

only; logs and stack traces must never corrupt the transport.

• Confirm install output leads with public GitHub skill installs, local plugin

commands are labeled local-only, and README/docs/catalog language agrees

with the live server.

This Server's Real Surface

mcp/suede-skills-mcp.mjs is the only server this skill QAs. Do not check it

against a generic MCP checklist — check it against this exact surface. Read

mcp/catalog.json first; the mcp block there must match what tools/list,

resources/list, and prompts/list actually return.

7 tools: list_suede_skills, get_suede_skill, suede_install_options,

suede_copy_seo_audit, suede_visibility_grade, suede_code_grade,

suede_qa_checklist.

6 resources: suede://catalog, suede://plugins, suede://copy-seo-audit,

suede://visibility-grade, suede://code-grade, suede://qa-checklist.

5 prompts: suede-copy-seo-audit, suede-plugin-install,

suede-visibility-grade, suede-code-grade, suede-full-qa.

If any count drifts, the source (resources/tools/prompts arrays in

suede-skills-mcp.mjs) is ground truth, not this list — re-run tools/list,

resources/list, and prompts/list and update both this section and

mcp/catalog.json's mcp block to match.

Stdio Test Blocks

Run from the repo root. The canonical gate starts real child processes and

tests complete sessions rather than isolated requests:

npm run test:mcp

It must pass lifecycle enforcement and version negotiation; list/call/read/get

coverage; closed input and output schemas; read-only annotations;

structuredContent plus both text forms; profile filtering; malformed input;

the 1 MiB transport bound; invalid profile handling; stdout JSON purity; and

clean healthy stderr.

For a manual readback, keep initialization and later requests in the same

server process. A new process is a new MCP session:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"suede-mcp-qa","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"suede_install_options","arguments":{"surface":"mcp"}}}' \
  | node mcp/suede-skills-mcp.mjs --profile all

The initialization result must report protocol 2025-06-18, server version

0.9.2, and explicit tools/resources/prompts capabilities. tools/list must

return exactly the 7 tools above. Each tool must expose inputSchema,

outputSchema, and annotations with readOnlyHint: true,

destructiveHint: false, idempotentHint: true, and openWorldHint: false.

The successful call must return structuredContent; content[0] must be useful

human text and content[1] must be the same structured payload serialized as

JSON for backwards-compatible clients.

To prove the lifecycle guard independently:

printf '%s\n' '{"jsonrpc":"2.0","id":4,"method":"tools/list","params":{}}' \
  | node mcp/suede-skills-mcp.mjs --profile all

This must return error -32000 because notifications/initialized has not

completed. Use the automated suite for post-initialization negative paths; a

standalone tools/call example is invalid because it starts a fresh session.

Error codes: -32700 parse error; -32600 invalid request, duplicate

initialization, or transport overflow; -32601 unsupported method; -32602

invalid params, arguments, tool, resource, or prompt; -32000 request before

session readiness; -32603 unexpected internal error. A parse error correctly

uses id: null. A raw stack trace or any non-JSON stdout is a High failure.

Failure Handling

| Failure type | Severity | Action |

|---|---|---|

| Server fails to start | Critical | Stop. Report startup error verbatim. |

| tools/list returns empty | Critical | Stop. The MCP is non-functional. |

| Lifecycle or protocol negotiation fails | High | Hold. Capture the request/response transaction. |

| Tool schema, output schema, or read-only annotation missing | High | Hold. Repair the published contract and rerun the suite. |

| Structured result lacks either text fallback | High | Hold. Preserve structured and legacy-client output together. |

| Listed skill folder missing | High | Flag each missing folder. Continue checking others. |

| Malformed JSON-RPC response | High | Report the raw response. Flag as broken. |

| Install command leads with local-only path | High | Flag. Install output must lead with public GitHub route. |

| Docs/catalog language mismatch | Medium | List each mismatch. Flag as hold-with-caveat. |

| Tool implemented but not in catalog | Low | Flag as undocumented. Not a blocker. |

Recommended ship gate rules (advice to the user, not a lock on any action):

• Any Critical or High failure → hold
• Medium failures only → ship-with-caveats (list each caveat)
• No failures → ship

Output

Server:
Commands run:
Tools checked:
Resources checked:
Prompts checked:
Install output:
Failures:
Fixes:
Ship gate: ship | ship-with-caveats | hold

Red Flags — Stop

• "The server ran fine last week; no need to restart it for this." — Run every check against the live server now.
• "The catalog parses, so the folders are surely there." — Open every listed folder and read its SKILL.md.
• "That check can't run, I'll mark it skipped." — A check that cannot run is a FAIL.
• "The output looked right, close enough." — Record the exact command and exact output, verbatim.

Routing

After QA:

• MCP source needs fixes → return to the MCP source file and fix, then re-run this skill
• Catalog JSON needs updates → edit mcp/catalog.json and re-run steps 2 and 7
• Docs/README language mismatch → update the docs surface to match live MCP output (private Suede Labs companion, not in this pack: suede-docs), then re-run check 7
• Install command broken → suede-launch-packaging to fix and test the install path