In jsonprc2_test.go, binder.Bind starts a goroutine.
That goroutine begins to run during jsonrpc2.bindConnection, and
can race with the setting of conn.write in bindConnection.
This PR adds a sleep, which is a poor way to deal with the race, but
the least invasive change. Better ones include running the test
function after Dial returns, or adding a Connection.Ready method
to detect when initialization is complete.
This CL introduces a fundamental change to the jsonrpc2 library:
connection writes, which were previously serialized by the jsonrpc2
library itself, are now allowed to be concurrent.
The change in semantics of the jsonrpc2 library should hopefully be easy
to review, since moving the synchronization to the Writer implementation
is equivalent to the previous logic. However, this change is critical
for the streamable client transport, because it allows for concurrent
http requests to the server.
Consider that a write is a POST to the server, and we don't know that
write succeeded until we get the response header. Previously, we had the
following problem: if the client POSTs a request, and the server blocks
its response on a request made through the hanging GET, the client was
unable to respond because the initial POST is still blocked. We could
update our streamable server transport to force a flush of the response
headers, but we can't guarantee that other servers behave the same way.
Fundamentally, writes in the spec are asynchronous, and we need to
support that.
This CL effectively removes any dependencies on mcp from jsonschema.
This will enable us to move the repo.
This CL also deletes unused marshalStructWithMap and
unmarshalStructWithMap which had a dependency on FieldJSONInfo.
Fixes: #250
Audit all cases where params must not be null, and enforce this using
methodInfo via a new methodFlags bitfield that parameterizes method
requirements. Write extensive conformance tests catching all the
(server-side) crashes that were possible.
We should go further and validate schema against the spec, but that is
more indirect, more complicated, and potentially slower. For now we
adopt this more explicit approach.
Still TODO in a subsequent CL: verify the client side of this with
client conformance tests.
Additionally, improve some error messages that were redundant or leaked
internal implementation details.
Fixes#195
This fixes#151, which makes it easier for users to easily use GitHub
Codespaces, providing them with a VS Code like environment with their
preferred settings/themes and the required dependencies, all within the
browser.
This PR improves the formatting and internal link structure of both the
main `README.md` and the source file at `internal/readme/README.src.md`.
Changes include:
### 🛠 Changes Made
* Replaced plain-text warning with a GitHub-style admonition block (`>
[!WARNING]`) for improved visibility and consistency with other docs.
Example:
> [!WARNING]
> The SDK should be considered unreleased, and is currently unstable
> and subject to breaking changes. Please test it out and file bug
reports or API
> proposals, but don't use it in real projects. See the issue tracker
for known
> issues and missing features. We aim to release a stable version of the
SDK in
> August, 2025.
* Updated markdown links to use cleaner relative paths:
* Changed `CONTRIBUTING.md` reference to
`[CONTRIBUTING.md](/CONTRIBUTING.md)`
* Updated `examples/` reference to `[examples/](/examples/)`
* Ensured that all updates were mirrored in both the generated and
source README files.
### 📌 Why It Matters
These changes improve the readability and usability of the
documentation, especially when viewed on GitHub. The updated formatting
helps call attention to important warnings, and fixing relative paths
ensures that links work reliably across platforms and contexts.
Expose `jsonrpc2.MakeID`, `jsonrpc2.EncodeMessage` and
`jsonrpc2.DecodeMessage` functions to allow implementing custom
`mcp.Transport`.
Add an example that demonstrates a custom transport
implementation.
Fixes#110.
BREAKING CHANGE
Change the API for adding tools, prompts, resources and resource
templates to a server.
The ServerXXX types are gone along with the plural Add methods
(AddTools, AddPrompts etc.)
Instead there are single Add methods (AddTool, AddPrompt).
In addition, instead of NewServerTool, there is AddTool[In, Out].
Fixes#73.
Fix an example using params.Name instead of params.Arguments.Name. All
credit due to @A11Might for noticing this. Sending a separate PR to keep
the internal/readme source consistent.
After some experience with the flattened version of Content, we see that
it can easily lead to incorrect usage and is a harder API to read.
Therefore, this CL changes back to a design similar to what we had prior
to https://go.dev/cl/672415, though opting to promote content
unmarshalling to the protocol types that use it, which leads to an
overall simpler api.
* mcp: move to 2025-06-18 schema
Add types and fields for the latest MCP schema.
The main challenge here was dealing with the presence of _meta fields
on many types, like Tool, Prompt and Resource.
- Distinguish between the _meta field of a request's params, which
includes a progress token, from the _meta field on other types,
which is simply a map.
- Redefine GetMeta to return a pointer to the map. We wanted to avoid
that, but I don't see a clean way to do so. An alternative would be
to have GetMeta return a map, and SetMeta to set it.
- Provide GetProgressToken for requests only (not notifications or other
types).
- Still to do: deal with the meta and annotation fields of ContentBlock,
which are currently duplicated for Resource and ResourceContents.
* Meta and progress token redesign
Update the README to remove the table of contents, and update the target
stability date from 'mid July' to 'August': mid July does not allow
enough time for testing.
In CL 682976, Alan Donovan correctly points out that the term in the MCP
spec is 'stdio', and therefore the correct capitalization is Stdio.
Change-Id: Ib5bbe04f1a61de886298b4d0adc13aefd6aadd9c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/683075
Reviewed-by: Alan Donovan <adonovan@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Change CONTRIBUTING.md and README.md to reflect that the MCP SDK is
being moved to github.com/modelcontextprotocol/go-sdk, and to include
content from the 'Governance' section of the design doc. Also, include
the antitrust policy as a section in CONTRIBUTING.md.
Change-Id: I46784d8e57b2a2cab8895593f633d20a2e15c8ba
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682976
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Remove dependencies on the eventtest and testenv packages from
jsonrpc2_v2 and mcp packages, in preparation for forking.
Change-Id: Id0efb0c3187629f6fb1822cc853ec52acea41b0d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682696
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
The NewTool and NewPrompt constructors were unidiomatic, because they
returned a ServerTool and ServerPrompt, respectively, rather than a Tool
and Prompt. Rename to be consistent with the constructed object name.
Change-Id: Ife3f16f783368401f792660c4272e1bb5ae61638
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682375
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
In preparation for extracting the jsonrpc2_v2 package, update the Reader
and Writer interfaces to not report byte counts, and remove the
internal/event dependency.
Change-Id: Ie6b373736fe297c8427cd4ece7ddad33e275864b
Reviewed-on: https://go-review.googlesource.com/c/tools/+/678956
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
CallToolParams.Arguments is any.
Clients can send whatever they want.
Tool authors who create their own ToolHandler (bypassing NewTool)
will receive the arguments as a map[string]any which has been
validated against the input schema.
Tool authors who call NewTool can choose the type that the arguments
unmarshal into.
There is no double-unmarshaling and no downcasting.
There is no way for tool authors to avoid the unmarshal, and no way to
avoid the validation unless the omit an input schema, which is probably
bad for LLMs. If tool authors want this optimization, we can provide
it later.
Change-Id: Ieb201e56c7fb8a23bb1a93b27e946630ec9e79ad
Reviewed-on: https://go-review.googlesource.com/c/tools/+/679595
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Add Wrapf, a function that helps with error wrapping.
Change-Id: I102695f75e4d217e09f828f4723cbfcbbe83f887
Reviewed-on: https://go-review.googlesource.com/c/tools/+/679177
Reviewed-by: Robert Findley <rfindley@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Do a thorough job of parsing json struct tags.
Move the code to a place where both mcp and jsonschema can use it.
Change-Id: I6c86308834706b12a1e22cd96ae120590f49d3f4
Reviewed-on: https://go-review.googlesource.com/c/tools/+/678757
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Make Tool APIs future-proof by pushing generics into CallToolParams, and
using CallToolParams throughout. This has several advantages:
- We no longer need the awkward CallToolOptions type, which is almost
but not quite like CallToolParams.
- NewTool no longer needs to define its own handler type: it accepts a
ToolHandler[TArgs]. This also means its signature is future-proof.
Additionally, provide a `CallTool` helper (the analog of NewTool) to
serve as a more strongly typed variant of `ClientSession.CallTool`.
+ design, protocol generation
Change-Id: I80172a25bc50734dae84a541aa4776ed9161694e
Reviewed-on: https://go-review.googlesource.com/c/tools/+/676495
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Modify the conformance test driver to support outgoing responses.
They are returned for incoming requests in order.
Add a test that returns a file resource, which involves the server
sending a roots/list request to the client.
Change-Id: Ie7eb69a8c99ccbf11721518cfffb21244c03e532
Reviewed-on: https://go-review.googlesource.com/c/tools/+/677475
Commit-Queue: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Add the beginnings of some testdata-driven conformance tests that check
JSON-level compatibility of SDK messages, and fix some bugs in our JSON
message handling:
- "params" can be missing
- "_meta" should not be null
- lists of tools/prompts/resources should not be null
In order to implement this, we need to be able to know when the server
is done processing messages. In general, this is a hard problem; for
gopls we do this with a complicated system of progress reporting and
accounting. However, the new synctest package makes this trivial, as we
can call synctest.Wait to detect when the server is idle. Therefore,
this test requires 1.25 (it uses synctest.Test, added in 1.25, and so
can't run at 1.24 with GOEXPERIMENT=synctest).
Change-Id: I97fa28b56868340ece266a58e1eb3c3bf8cfe0e9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/676538
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
Change-Id: I8066b22cb87e09fb160de3b8ff2d8fdde6ec3dcf
Reviewed-on: https://go-review.googlesource.com/c/tools/+/675815
Reviewed-by: David Chase <drchase@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Use the weave program from golang.org/x/example to weave together
the README text with buildable programs. This ensures the code in the
README compiles.
Change-Id: Ib5e10c8f808cc6d1ed4addbee784607e910ba30b
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673796
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Now that the protocol package is merged into the mcp package, clean up
the higher level 'Content' union types, in favor of types constructors.
Change-Id: I37bedb0ff0a296eef799ba65c37ca7f94ee1dbbe
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672415
Reviewed-by: Jonathan Amsterdam <jba@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
The generated protocol package is part of the SDK API, so it shouldn't
be internal.
Change-Id: I5306af48019b1599707b939b348eb6ae4f766ca9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/670356
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
The jsonschema package is part of of the API of the mcp package,
so it should not be internal.
Change-Id: I9520797837329fc2cda09c2f46ec4d48d031b9d3
Reviewed-on: https://go-review.googlesource.com/c/tools/+/669996
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
This is the first CL that deals with the process of preparing a schema for validation.
Perform some basic checks on the scheme. Along the way, compile regexps and store
them in the schema for use during validation.
Change-Id: I0e5e6ce28656dcecb6d2d4b2fdc98998fa05b6f1
Reviewed-on: https://go-review.googlesource.com/c/tools/+/669696
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Determine if a slice contains unique items by hashing them.
This should take linear time on average, better than the previous
quadratic algorithm.
Change-Id: I8dc95bb6f29d802bdbc64bc7f7e698c71eae5ce7
Reviewed-on: https://go-review.googlesource.com/c/tools/+/669455
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Some JSON Schema keywords, like minLength, are logically integers.
The JSON Schema spec allows them to be written as floating-point
values with zero fractional part, which is a reasonable choice, since
JSON doesn't distinguish the two.
We could simply validate these fields as integers in the normal course
of events (namely, validating the schema against its meta-schema),
but this CL does a little better: it uses *int struct fields for
these keywords, preventing them from ever being non-integers.
The UnmarshalJSON method still accepts integral floating-point values.
Marshaling is unaffected, and the results don't change: encoding/json
has always marshaled integral floats without the decimal part.
Other choices:
- Leave them as float64: you could then get away with
Schema{MinLength: Ptr(1.5)}
and though you couldn't get far with that, it's still irksome.
- json.Number: same problem as float64, plus it's even harder to write
as a literal.
- int64: now `Ptr(1)` doesn't work (it's a *int, not a *int64).
Anyway, these keywords all compare against len(x) in Go, which
is of type int.
Change-Id: Ie3f08bd8a5deaf2a21344d6ab873551c011b12d5
Reviewed-on: https://go-review.googlesource.com/c/tools/+/668315
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Add validation for JSON objects (Go maps).
The map keys are called "properties."
As with arrays, annotations are needed to support the
unevaluatedProperties keyword.
Change-Id: Ia01f74300f4bcdbce94065572d83c46dfaa53ae7
Reviewed-on: https://go-review.googlesource.com/c/tools/+/668256
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Add support for all content types, and formalize the conversion of
content to and from the wire format (as a discriminated union).
Change-Id: I93678ce98c02176a524d2c82425fb1267ad68bf0
Reviewed-on: https://go-review.googlesource.com/c/tools/+/669135
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
Add support for 'prompts/list' and 'prompts/get', and registering
prompts on the server using AddPrompts. Add a 'MakePrompt' helper to
construct prompts from a prompt handler using reflection.
Change-Id: I479cb9c9b99313cca99640c1f5ea1939363759e6
Reviewed-on: https://go-review.googlesource.com/c/tools/+/669015
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Implement variadic options for building tools and schemas, to allow
easier customization of tool input schemas.
Also, make fields required, unless they are marked as "omitempty".
Change-Id: I7a29258fae3ec5e7ea4906ed30ed6750979de962
Reviewed-on: https://go-review.googlesource.com/c/tools/+/668955
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Add validation for the keywords dealing with JSON arrays.
We call the elements of an array its "items."
The unevaluatedItems keyword introduces some complexity. Its schema
applies to all items in the array that have not been successfully
validated ("evaluated" is the spec's misleading term) by this schema or
subschemas acting on the same array. The logic keywords like allOf and
anyOf thus contribute to the set of evaluated items.
Following the spec, we say that a schema produces "annotations" that
describe the items it has evaluated. The annotations type collects this
information. For the "contains" keyword we need to represent the set
of evaluated items, but for others we can optimize with an integer or
boolean. For example, the "items" keyword applies its schema to every
item in the array. If even one fails to validate, the array fails to
validate, and the validate call exits before reaching unevaluatedItems.
Therefore, if "items" succeeds, it has successfully validated every
item, so unevaluatedItems does not apply. A boolean annotation suffices
to record this fact.
The logic of "anyOf" must change so it can track all evaluated items.
It must still visit the remaining subschemas even after a subschema
succeeds.
Anticipating the next CL, which deals with JSON objects (maps), the
annotations struct supports properties as well as items.
Change-Id: I98283d36c9a55f4cae97636cbec20c4886daea11
Reviewed-on: https://go-review.googlesource.com/c/tools/+/668235
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Validate keywords that combine schemas with various logical operators.
Also add iterators over schemas. Now we only need them to skip some
tests, but later they will come in handy for non-test code.
Change-Id: Idaf41efea4d693b6be0ee5c6c3a527664b8c472f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/668115
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Add validation for keywords related to numbers and strings.
It may be surprising that keywords like "minimum" or "minLength"
don't imply that the instance is a number or string.
But that is how JSON Schema is designed.
Change-Id: I8805a5fe91ee345931e1c989f174ea2d0be6665a
Reviewed-on: https://go-review.googlesource.com/c/tools/+/667975
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Jonathan Amsterdam <jba@google.com>
