Skip to content

Align READMEs and extend the smoke tests #270

Open

Description

@a-akimov

Problem

The READMEs follow a common outline, but their headings, build names and claims have drifted apart. No server README shows how to connect the server to a host, which is the whole point of the tutorial.

The smoke tests only check that each server answers one fixed call and that each client calls tools/list. So none of the inconsistencies described in the other issues would fail CI.

Tasks

READMEs

  • Use the same section headings in all ten READMEs. Today the run section is called "Run the server", "Build and run" or "Setup and run", depending on the README.
  • Add the same host config snippet (for example claude_desktop_config.json) to every server README.
  • weather-server-go/README.md:17 builds a binary named weather, but the tests and .gitignore use server. Pick one name.
  • Reconcile two contradictions about the Ruby server:
    • weather-server-ruby/README.md:40-46 says strict 2026-07-28 clients reject it, and that it has been verified only against the Ruby client. But tests/smoke-test.sh:88-94 tests it with the TypeScript client.
    • It now also passes the TypeScript test client at 2026-07-28, and the Rust client connects to it. Re-check the "verified only against the Ruby client" claim; the resultType caveat may still apply to stricter clients.
  • mcp-client-typescript/README.md:42 links to specification/draft/..., while the other READMEs link to 2026-07-28.
  • The Rust README says "put it in a .env file", but there's no .env.example (see Client polish and consistency #269).
  • The TypeScript and Ruby client READMEs say .py servers work. Either mention that uv is required or fix the launcher (see Client polish and consistency #269).
  • In every client README, state the SDK's default version-negotiation mode. The Go, Rust and Ruby READMEs say nothing about it today.
  • After Normalize the five weather servers renames the TypeScript tools, remove the "or get-forecast and get-alerts in TypeScript" note from the root README.

Tests (tests/helpers/mcp-test-client.ts, tests/smoke-test.sh)

  • For servers, assert:
    • the exact tool names
    • that both text and structured content are present
    • that the text output is the same across languages for the same fixed call
  • For servers, add one error-path call (for example state ZZ) and assert the shared error message.
  • Stop stale Rust binaries from winning. ensure_built builds only when neither a debug nor a release binary exists, and resolve_binary prefers the release binary, so an old release binary is used silently. During the SDK upgrade, this made the Rust tool-loop test run an old binary and report failures that the current source didn't have. Make the Rust and Go steps always rebuild, or at least use whichever binary is newer.
  • Once Stop breaking 2025-11-25 clients with get_alerts' array output schema is decided, document in the Rust client README what it sees from each server.

CI and dependencies (.github/)

  • ci.yml says "Node 24 is the Active LTS". That's no longer true: Node 24 moved to maintenance LTS on 2026-10-20, and Node 26 became LTS on 2026-10-28. Change it to "the oldest supported LTS".
  • Optional: run CI on both Node 24 and Node 26, so the minimum and the newest LTS are both tested.
  • Optional: include major updates in the github-actions group in dependabot.yml. It only groups minor and patch updates today, so each major bump arrives as its own PR.

Acceptance criteria

  • Every README has the same sections in the same order.
  • CI fails if a server renames a tool, drops its text content or changes an error message.

Activity

  1. added
    documentationImprovements or additions to documentation
    github_actionsPull requests that update GitHub Actions code
    on Nov 1, 2026
  2. self-assigned this
    on Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgithub_actionsPull requests that update GitHub Actions code

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions