Skip to content

small issues from the 2.8.0 docs audit (shipped text and examples) #357

Open

Description

@ViperJuice

Found by the 2.8.0 docs audit (shipped-docs lane); not fixed in the docs PR because each needs a code or data decision.

  1. Guidance level vs per-layer keys. _apply_level_preset (src/pmcp/config/guidance.py:85-104) always overwrites the per-layer YAML keys, so layers: settings are dead whenever level is set (always, by default). Either honour explicit layer keys over the preset or remove them from the schema.
  2. E302 hint. Oversized downstream output fails with E302 and the generic suggestion "Check tool arguments and server status"; it should say the output exceeded the limit and how to lower or narrow it.
  3. Shipped manifest pangram entry (manifest.yaml:~676) tells users to pass the API key on argv; use pmcp secrets set PANGRAM_API_KEY (prompts).
  4. browser_click snippet in src/pmcp/templates/code_examples.yaml uses a selector argument; current Playwright MCP appears to use target/ref. Verify against the pinned or current version.
  5. Source comments mention pmcp serve, which doesn't exist.
  6. .mcp-gateway/descriptions.yaml is a 2025-12-28 snapshot (only the context7 entry was corrected); regenerate it, or stop tracking it.

Activity

  1. ViperJuice commented on Oct 4, 2026

    @ViperJuice
    CollaboratorAuthor
    1. Dead snippet keys. In src/pmcp/templates/code_examples.yaml, the keys github::listIssues, sqlite::query and puppeteer::* don't match those servers' real tool names, so gateway.describe never shows them. The gateway::* keys match no server either. Either key them by the real tool names (derive the names from the manifest or a live tools/list, and add a test that every key names a tool a shipped server exposes), or remove them. Found by the docs: audit README, CHANGELOG, SECURITY, shipped guides and tool descriptions against the code for 2.8.0 #358 round-3 review.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions