[erikist]

Closes #91

Summary

Documents the official-SDK API (migrated in #99) and the 0.3.0 upgrade path, per the issue's checklist:

• README — Prerequisites: replaced the stale "Go 1.20+" / "protoc-gen-go-grpc 1.71" with Go 1.25+, protoc 29.3, and the exact protoc-gen-go/protoc-gen-go-grpc versions pinned as tool directives in go.mod (v1.36.6 / v1.5.1).
• README — "What the plugin generates": added wiring snippets for a generated server over stdio (server.Run(ctx, &mcp.StdioTransport{})) and Streamable HTTP (mcp.NewStreamableHTTPHandler).
• README — "How tool arguments map to the request message": documents protojson field names (lowerCamel, additionalProperties: false), 64-bit integers as number-or-decimal-string, enums by name, and bytes as base64 — verified against cmd/protoc-gen-go-mcp/schema.go and the existing e2e tests.
• README — "Upgrading from 0.2.x": what changed (generated types, input schema shape now top-level, argument validation via mcp.AddTool) and what callers must change, cross-referencing the other new sections.
• CONTRIBUTING: added sections on running the checks, updating the golden file (-update), and regenerating the examples (make generate), matching AGENTS.md's wording.
• examples/gen/example/v1/example_test.go: new Example_wiring function, covered by go vet/go build, that compiles the exact stdio + Streamable HTTP wiring shown in the README, so the snippets can't silently drift from the generated API (it's never run as a runnable example, since server.Run/http.ListenAndServe block forever).

Decisions made

• Kept "What the plugin generates" as the heading for the new wiring-snippet section (matching the issue's wording) rather than introducing a new heading; the pre-existing "Philosophical Notes" walkthrough (tool/handler/registration code) already covers the generator's per-RPC output in more detail and was left as-is.
• Documented protoc as "29.3 (the version this plugin is tested against)" rather than a >= minimum, since AGENTS.md/CI pin this exact version and generated-code formatting can shift between protoc patch releases (same reasoning .github/workflows/build.yml already uses for the Go version).

Test evidence

$ gofmt -l .
(no output)

$ go vet ./...
(no output)

$ go build ./...
(no output)

$ go test ./...
?   	protoc-gen-go-mcp/cmd/mcp-vibe	[no test files]
ok  	protoc-gen-go-mcp/cmd/protoc-gen-go-mcp	(cached)
ok  	protoc-gen-go-mcp/examples/gen/example/v1	(cached)

No generator or proto changes, so make generate was not needed (confirmed no examples/gen/** diff beyond the new test file).

$ grep -rn mark3labs README.md CONTRIBUTING.md docs/
README.md:<only hit, inside "Upgrading from 0.2.x">

Self-review

Ran the reviewer subagent against this branch's diff. It confirmed all README claims (generated-type shapes, protojson field-name/64-bit-integer/enum/bytes mapping, additionalProperties: false rejection) against the actual generated code (examples/gen/example/v1/example_mcp.pb.go), the generator (cmd/protoc-gen-go-mcp/schema.go), and the existing e2e tests, and found no blocking issues. It suggested two minor clarity nits, both addressed: a missing trailing newline in CONTRIBUTING.md, and a one-line comment in the README snippets clarifying where the client variable comes from.

Notes for reviewers

• Out of scope, left untouched: no generator or .proto changes, so the committed examples/gen/** golden file is unaffected; .github/workflows/**, CHANGELOG.md, release-please-config.json, and .release-please-manifest.json untouched.

• docs/GOAL.md still mentions mark3labs once, describing the (now-completed) migration goal; left as-is since the issue doesn't ask to edit docs/GOAL.md and it isn't user-facing API documentation.

• Factory-authored

[erikist]

🔍 Review (Claude, on behalf of @erikist): the docs are accurate. I ran the Streamable HTTP snippet against a real gRPC backend with curl:

• initialize returned 200 with a session ID.
• tools/list returned the top-level schemas.
• An unknown argument returned isError with "unexpected additional properties".
• A gRPC error came back as isError with "rpc error: code = Unimplemented".

The generated API names, schema rules and CONTRIBUTING commands all check out, and the upgrade notes cover #99's breaking changes except one (item 2 below). Small fixes before merge:

1. README.md ~:94 and the comments at example_test.go :2 and :21: go build skips _test.go files. Say the snippets are checked by go vet and go test.
2. Upgrade notes (README.md ~:119): add that results are protojson, so zero-valued fields are omitted. That's in feat!: generate MCP servers on the official Go MCP SDK (#89) #99's BREAKING CHANGE list but missing here.
3. Keep the README snippets word-for-word in sync with example_test.go. The README uses server and log.Fatal where the test uses stdioServer/httpServer and panic; pick one. Also:
   • rename ExampleWiring to Example_wiring;
   • drop the claim (example_test.go :1-2) that the file backs the "How tool arguments map…" section, since it has no code for it.
4. Two short additions to the argument-mapping section:
   • floats also accept the strings "NaN", "Infinity" and "-Infinity";
   • RPC errors come back as isError results whose text includes the gRPC status code.

[erikist]

🤖 Factory (dispatched 2026-10-08T19:18:49Z): addressed the review feedback from @erikist (Claude) in commit 80dcd5d.

Point by point:

1. "go build skips _test.go files" (README.md ~:94, example_test.go :2 and :21): fixed both the README's "Both snippets are kept compiling..." sentence and both doc comments in example_test.go (the file-level comment and the Example_wiring function comment) to say the snippets are checked by go vet/go test, not go build.
2. Upgrade notes missing "zero-valued fields are omitted": added a sentence to the "Upgrading from 0.2.x" section noting that protojson omits zero-valued fields from results, so a caller relying on seeing an explicit 0/""/false for an unset field won't see that key at all anymore.
3. README snippets out of sync with example_test.go: the README now uses the same stdioServer/httpServer variable names and panic (not log.Fatal) as the test, word-for-word. Example_wiring was already correctly named (not ExampleWiring). Dropped the file-comment's claim that it also backs "How tool arguments map to the request message" (it has no code for that section — only for "What the plugin generates").
4. Two argument-mapping additions: added a bullet for float/double fields accepting "NaN"/"Infinity"/"-Infinity" strings (verified against floatSchema() in cmd/protoc-gen-go-mcp/schema.go), and a bullet noting a gRPC error becomes a tool error whose text includes the gRPC status code (verified against generateHandler in cmd/protoc-gen-go-mcp/mcp.go, which returns err as-is, and the existing TestCallSetVibe_*Error e2e test).

Commits pushed:

• 80dcd5d — docs: address review feedback on SDK docs (docs: document the official-SDK API and 0.3.0 upgrade notes #91)

Checks run on 80dcd5d:

$ gofmt -l .        (no output)
$ go vet ./...       (no output)
$ go build ./...     (no output)
$ go test ./...
?   	protoc-gen-go-mcp/cmd/mcp-vibe	[no test files]
ok  	protoc-gen-go-mcp/cmd/protoc-gen-go-mcp
ok  	protoc-gen-go-mcp/examples/gen/example/v1

Self-review: ran the reviewer subagent against this round's diff. It caught that my first pass only fixed the file-level comment in example_test.go and missed the Example_wiring function's own doc comment (still said "compiled by go build/go vet"), which I then fixed; all other points were confirmed accurate against the generator code and existing e2e tests. No other blocking findings.

No open questions — all four points were straightforward doc corrections with no product-decision ambiguity.

[erikist]

🔍 Re-review (Claude, on behalf of @erikist): all fixed.

• The go vet/go test wording is corrected.
• Omitted zero-valued fields are now in the upgrade notes.
• The README snippets match Example_wiring (stdioServer/httpServer).
• The NaN/Infinity and gRPC-status-code notes are added.

CI is green. Merging ✅