Handlers and client/server methods take a single request argument
combining the session and params. This slightly simplifies the signature
for handlers, since there is no longer an often-ignored session
argument.
But more importantly, it opens the door to adding more information in
requests, such as auth info and HTTP request headers.
For #243.
As described in #272, there is really no reason for transports to be
closed structs with constructors, since their state must be established
by a call to Connect. Making them open structs simplifies their APIs,
and means that all transports can be extended in the future: we don't
have to create empty Options structs just for the purpose of future
compatibility.
For now, the related constructors and options structs are simply
deprecated (with go:fix directives where possible). A future CL will
remove them prior to the v1.0.0 release.
For #272
- Correct MethodHandler type parameter to use fully qualified
mcp.ServerSession
- Update parameter types to use proper mcp.Params and mcp.Result instead
of any
- Ensure example code matches the actual API
## Background
Since the Server has a map of ServersSessions->subscriptions, and takes
care of routing ResourceUpdate messages to ServerSessions, I think the
decision was made to leave *ServerSession out of the
SubscribeHandler/UnsubscribeHandler signatures. However, resource
subscriptions are not specific to the a particular client and this
information is kept private in the Session today.
## Proposal
Align the Subscribe/Unsubscribe handlers with the other two handlers
that are client specific (ProgressNotificationHandler, and
RootListChangeHanlder), and include *ServerSession in the signature.
It comes in practice because because a gateway server that needs to
forward subscriptions still needs this information. The routing logic in
Server is convenient and means that most servers won't need to know
which ServerSessions are subscribed. But I think there are still use
cases where the user will need to know.
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.
I added an example for how rate limiting should be implemented using
middleware.
Fixes#22
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
Rate limiting can be enabled using middleware. This adds an example on
how to do that.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
N/A
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
This pull request addresses multiple minor documentation and code
comment fixes to correct typos and improve clarity. These changes do not
introduce functional modifications but enhance readability and
professionalism.
### Documentation Fixes:
* Corrected a typo in the "Security Considerations" section header in
`design/design.md`. ("Securty" → "Security")
* Fixed spelling errors in the "Governance and Community" section of
`design/design.md`. ("accomodating" → "accommodating")
* Updated the "Proposals" section in `design/design.md` to fix a typo.
("accomodate" → "accommodate")
### Code Comment Fixes:
* Corrected a typo in a comment in `mcp/logging.go`. ("LoggingMesssage"
→ "LoggingMessage")
* Fixed a typo in a comment in `mcp/streamable.go`. ("priviledged" →
"privileged")
<!-- Provide a brief summary of your changes -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
This PR is for fixing some typos in the repo
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
by code diff
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
N/A
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
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.
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>
Allow customizing the http.Client used for HTTP MCP client transports,
by adding client options structs.
Change-Id: I2297acb136f8d0f7fa70d58cd244a6a81cc89751
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682756
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>
After implementing the Streamable transport, it is apparent to me that
the name 'Stream' is confusing, as it can refer either to a stream in
the streamable transport, or to a JSON-RPC stream.
But the name 'Connection' is available, and a natural name for the
result of the Transport.Connect interface method. Therefore, rename
Stream to Connection, and update the streamable implementation to refer
to its HTTP connections as 'streams', consistent with other SDKs.
Change-Id: Ica55f84caabcbfa5a2fe029cc0c2db57da574875
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682376
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.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>
Add an (almost) complete implementation of the streamable HTTP
transport, including:
- A StreamableHTTPHandler for serving sessions.
- A StreamableHTTPServerTransport that supports session resumption.
- A minimal StreamableHTTPClientTransport.
Additionally, include the following minor changes:
- Refactor SSE event reading to use an iterator.
- Start to to aliases for JSON-RPC types (incomplete)
- Fix handling for null tool arguments (again)
Still to do:
- The streamable client does not support retry/resumption, or the
side-channel GET requests.
- Support configurable session and event retention (garbage collection).
- Expose the HTTP client used for HTTP requests (for auth).
Change-Id: Ieba216ef901169b4660d601386fa0c7c7bb4c4b2
Reviewed-on: https://go-review.googlesource.com/c/tools/+/667515
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Implement sending middleware.
Sending middleware is useful for adding tracing, progress tokens,
and so on.
Change-Id: I0acab2550f0212d549c4adbcf1ebf425a9486df6
Reviewed-on: https://go-review.googlesource.com/c/tools/+/676355
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Write a separate constraint for ClientSession | ServerSession,
and change the pointerness of the type parameter.
There is still a dynamic cast, but overall I think this is a bit
simpler:
- The exported types have the more readable constraint "Session"
instead of "ClientSession | ServerSession".
- We can put the unexported methods in Session instead of needing a
separate interface (previously "session").
- This CL enables a simplified treatment of sending middleware, in
the next CL.
Change-Id: I41184fe93ea201d1da29dbfba26ac59f93771277
Reviewed-on: https://go-review.googlesource.com/c/tools/+/676175
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Add a section the the MCP SDK design discussing governance and community
engagement.
Change-Id: I554d8d5623201053a17a17c21dc596c4cdd0878c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/677540
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@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>
Meta is a struct that contains a map[string]any, and a ProgressToken
field.
Each Params and Result type has a Meta as a value field.
Meta marshals and unmarshals specially, so the ProgressToken field
becomes part of the map. The marshalling code is generalized in
anticipation of every Params and Result growing a map of additional
properties.
Change-Id: I6d2f34270d33501c96437f24f91ef3e51d20d955
Reviewed-on: https://go-review.googlesource.com/c/tools/+/674956
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Provide a ServerSession method that directly implements the spec
method.
Also provide a custom slog.Handler that writes a notification on each
log call. It uses a slog.JSONHandler to format the message as JSON, then
adds the additional fields of LoggingMessageParams.
I decided that the direct method should handle levels, since that is
in the spec, but that rate-limiting is an extra feature, so is only
provided in the slog handler.
Change-Id: I1190ca124e992e61fb633ac52ee3492c8e6d99c9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/674498
Auto-Submit: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Fix some typos found during the Google import of x/tools.
Change-Id: I8ea38d3e1bd09bedbc98ed8c8146e88e84aa051f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/674975
Auto-Submit: Robert Findley <rfindley@google.com>
Reviewed-by: Hongxiang Jiang <hxjiang@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Implement middleware for clients.
Make the middleware types generic so we can factor out code
from both peers.
I was able to make the request handler generic, with one weird trick
(see handleRequest).
The first three declarations of shared.go, and a few others as well,
are copied unchanged from middleware.go.
Change-Id: Ib3239d8fcfda022ddb5b554c38cff4cdbc3704c1
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673635
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Provide secure reading of files on the local filesystem.
There are subtleties in path manipulation on Windows that I don't fully
understand, so I defer that work for now.
Change-Id: Ic11f4617dde4ac0b31ccd5b0a772bb2f56db026f
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673196
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>
Implement the dispatcher middleware framework, allowing users to
wrap method dispatching with their own code.
The Dispatcher functions have an untyped params arg, but expect its
value to be a typed, unmarshaled XXXParams struct. That required
splitting the elegant dispatch[P, R] function into two parts, one
to do the unmarshaling and one to call the method. The nicest way
I could find to do that was to map from method names to a pair
of functions, one to unmarshal and one to call. We could also write
it as two switches on method name, which would require less machinery
but would duplicate the list of method names, already a tad fragile
because they are literal strings.
I also exported the initialize params and result, so user Dispatchers
could access them. All Params and Result types will have to be exported
for that reason.
Change-Id: Ie2c95cc17b4ef3d3d095dccdadb294e5f1590796
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673515
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Due to the irregularities of github-flavored markdown, I had to join all
paragraphs before posting the public design. Additionally, I made a few
wording tweaks.
If we want to continue editing the design here, we should keep it in
sync with the public design discussion. Therefore, copy back those
changes.
Change-Id: Ie6ab3b3f59b923bb58540e86bbb1451ce0b4815d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673199
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Do another pass of clean up for the design prior to posting.
Also, add a cached Roots iterator, as discussed.
Change-Id: If8d444b23c7332b89effb2fce8b3be28841f0882
Reviewed-on: https://go-review.googlesource.com/c/tools/+/673195
TryBot-Bypass: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
TryBot-Bypass: Robert Findley <rfindley@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Do a pass through the design doc, adding a bit more clean-up and
commentary.
Additionally, update ServerTool and ServerPrompt to be consistent with
the design.
Change-Id: I1b75c4690d86fe8946d512cb36a1fc2938b3c883
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672576
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Add a logical client session type back to the SDK, to bring it closer to
the design. Also, remove 'ConnectionOptions', which is better
implemented using middleware, and reimplement logging as a
LoggingTransport middleware, which is also added to the design.
Change-Id: I908b4f837d513ffc60ae5b6171a31519cffafebc
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672795
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Various typo and style changes.
Change-Id: Ifd4322dcf0bf2b2653bb38a023a51056424cca39
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672815
Reviewed-by: Robert Findley <rfindley@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Commit-Queue: Jonathan Amsterdam <jba@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Add a link to a recent commit that illustrates a backward-compatible
change.
Change-Id: I5e277f9417cf9bbbc5146512e29a3cb8205a4e14
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672716
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Commit-Queue: Jonathan Amsterdam <jba@google.com>
Update the design to mention our in-memory transport, since it is
generally useful, and update the implementation to use distinct types
for InMemoryTransport and StdIOTransport (the fact that they are both
implemented as an io.ReadWriteCloser is an implementation detail).
Change-Id: I8228ccf2092a56a730c113c4db105fb492cce112
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672715
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Commit-Queue: Robert Findley <rfindley@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
TryBot-Bypass: Robert Findley <rfindley@google.com>
Change-Id: I2cb8be82a91dea7755ea5514ee1fbe1e937135c9
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672376
Reviewed-by: Robert Findley <rfindley@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Commit-Queue: Jonathan Amsterdam <jba@google.com>
Get the name and signature of the handler right.
Change-Id: I743aaaee45cc07a741ab8ad16e90e1b1d5519b64
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672336
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Change-Id: I5f7a6bad296d23c1bc075eb767a243c24a42668c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672675
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Auto-Submit: Sam Thanawalla <samthanawalla@google.com>
TryBot-Bypass: Sam Thanawalla <samthanawalla@google.com>
Commit-Queue: Sam Thanawalla <samthanawalla@google.com>
CallTool takes a tool name, arguments, and an options struct.
Also, pass the params to ToolHandler.
Update the design doc accordingly.
Change-Id: I21b7995b607bea976ad708ebb6ac0716018f39cb
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672596
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>
Design for pagination.
Change-Id: I8257a499b1e4691382b5681b84a52030344ab0e3
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671135
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Mention that all methods from the spec have the same signature,
and then don't repeat those method declarations.
Modify all method calls in the doc to take a Params struct, even if
the current MCP spec says it is empty.
Change `string` to `[]byte` in some of the listed struct fields.
The current code generator incorrectly generates these as strings.
(I have a forthcoming CL to fix that.)
Also, elaborate the logging design.
Change-Id: I5f323d4d98a4b6045d3cdef770d13b4bfdcb1044
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671358
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Handle resource subscriptions by delegating to the user.
We don't need to use the word "Resource" in the handlers because
the Subscribe and Unsubscribe methods in the spec don't use that
name. If the spec adds another kind of subscription, they will pick
a new name.
The need for two handlers is dictated by backward compatibility.
We must pass the RPC params to the subscription handler, which means
we need different signatures for subscribe and unsubscribe.
Change-Id: I045abaf52dc9c3e96181331728d50cf36cc8ed91
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671895
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Minor changes to the roots part of the design.
Change-Id: I8125aecc5da297594f74d8d7dc5ef3d94dfa8519
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671356
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Fix typos and formatting, reword slightly.
Also, change names in the middleware section.
Change-Id: Ie86e5f633a07675ab188a8aaf70e51a48b0878bb
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671555
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
Put discussion of mcp-go up front, and address differences in the
individual sections. I think this leads to easier reading for the user
who is concerned about our divergence in design.
Change-Id: Ifd21f6b9eb570ad4a325b8a8800b7868dac12205
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671556
TryBot-Bypass: Robert Findley <rfindley@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Commit-Queue: Robert Findley <rfindley@google.com>
Per discussion, remove the separate protocol package in favor of a
single mcp package. Update the tools section accordingly, and add more
discussion about the decision of the NewTool API.
Change-Id: Ifb259555ca9d493ce63bc4f71e5f2fa295bdf09c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671496
TryBot-Bypass: Robert Findley <rfindley@google.com>
Commit-Queue: Robert Findley <rfindley@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
