Go SDK: Upgrade MCP SDK and remove vendored copy (#35)
<!-- Provide a brief summary of your changes -->
Update the Go interceptor SDK to use
`github.com/modelcontextprotocol/go-sdk` v1.7.0 custom method APIs and
remove the vendored Go SDK copy. This shouldn't update the behaviours,
but addding following functions.
Changed public/user-facing interfaces:
extension.Extension.Install now returns an error:
```
// before
ext.Install(mcpServer)
// after
if err := ext.Install(mcpServer); err != nil {
return err
}
```
New helper added:
```
extension.RegisterSendingMethods(client *mcp.Client) error
```
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
Pick up MCP Go SDK 1.7.0. This provides upstream custom method support,
so the local vendored SDK copy is no longer needed.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
- `go test -v ./...`
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
```go
if err := ext.Install(mcpServer); err != nil {
return err
}
```
The Go SDK module now requires Go 1.25 via
github.com/modelcontextprotocol/go-sdk v1.7.0.
## 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)
- [x] New feature (non-breaking change which adds functionality)
- [x] 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
-->
LocalChain now registers interceptor custom sending methods internally.
Manual remote chain setup should call
`extension.RegisterSendingMethods(client)` before connecting the MCP
client session used with chain.AddMCPServer.
Signed-off-by: Ukjae Jeong <jeongukjae@gmail.com>
This commit is contained in:
parent
1a3e5ef459
commit
8704137635
3 changed files with 231 additions and 57228 deletions
|
|
@ -9,8 +9,9 @@ Status of this Go SDK implementation against the SEP-2624 interceptor proposal.
|
|||
| Validation interceptors | Parallel execution, severity-based blocking, fail-open support |
|
||||
| Mutation interceptors | Sequential execution, priority ordering, payload threading via `json.RawMessage` |
|
||||
| Interceptor metadata | Name, version, description, events, phase, priorityHint (polymorphic JSON), compat, configSchema, mode, failOpen |
|
||||
| Event names | Constants for all standard server-side MCP methods; JSON-RPC method names used directly as event names |
|
||||
| Event names | Constants for common server-side MCP methods; other JSON-RPC method names can be used directly as event names |
|
||||
| Protocol methods | `interceptors/list` for discovery, `interceptor/invoke` for invocation — both registered as custom JSON-RPC methods |
|
||||
| MCP Go SDK integration | Uses `github.com/modelcontextprotocol/go-sdk` custom method APIs (`AddReceivingCustomMethod`, `AddSendingCustomMethod`, `CallCustomMethod`, `ParamsBase`, `ResultBase`) from v1.7.0; no vendored SDK patch is required |
|
||||
| `InterceptorChain` (SEP) | `chain.Chain` type with `chain.ChainEntry` objects pairing interceptor descriptors with MCP client sessions |
|
||||
| `ChainEntry` (SEP) | `chain.ChainEntry` struct holds `InterceptorInfo` + `*mcp.ClientSession` |
|
||||
| Chain discovery | `chain.Chain.AddMCPServer()` calls `interceptors/list` to discover interceptors from an MCP server |
|
||||
|
|
@ -23,9 +24,9 @@ Status of this Go SDK implementation against the SEP-2624 interceptor proposal.
|
|||
| Fail-open behavior | `FailOpen: true` interceptors log errors without aborting the chain |
|
||||
| Audit mode | `ModeAudit` records results without blocking; mutated payloads not propagated |
|
||||
| Timeout & context | Per-interceptor timeouts via `InvokeParams.TimeoutMs`, chain-level context cancellation, `InvocationContext` with principal/traceId |
|
||||
| Receiving direction (client → server) | All server-side method calls intercepted via `AddReceivingMiddleware` |
|
||||
| Receiving direction (client → server) | Server-side messages routed through `AddReceivingMiddleware` are intercepted, except skipped lifecycle and interceptor methods |
|
||||
| Capability declaration | Interceptor metadata injected into `initialize` response via `Capabilities.Extensions` |
|
||||
| First-party (in-process) deployment | `Server.LocalChain()` creates an in-memory transport `chain.Chain`; interceptors invoked via JSON-RPC even in-process |
|
||||
| First-party (in-process) deployment | `extension.Extension.LocalChain()` creates an in-memory transport `chain.Chain`; interceptors invoked via JSON-RPC even in-process |
|
||||
| Third-party and hybrid deployment | Chain entries can point to any `*mcp.ClientSession` — local (in-memory), stdio, or HTTP transport |
|
||||
| `json.RawMessage` payloads | Interceptor handlers receive `json.RawMessage` via `interceptor/invoke`, matching the SEP's JSON-level payload model |
|
||||
|
||||
|
|
@ -33,7 +34,8 @@ Status of this Go SDK implementation against the SEP-2624 interceptor proposal.
|
|||
|
||||
| Area | SEP expects | Notes |
|
||||
|------|-------------|-------|
|
||||
| Wildcard event matching | `"*/request"`, `"*/response"`, `"*"` | `matchesEvent` does exact match only; wildcard patterns are planned |
|
||||
| Server → client interception | Client features as interceptable events: `"sampling/createMessage"`, `"elicitation/create"`, `"roots/list"` | Requires `Server.AddSendingMiddleware` support in the go-sdk |
|
||||
| Per-interceptor config passthrough | `ChainExecutionParams.Config` map | Wired through to `InvokeParams.Config` but not yet used by middleware |
|
||||
| Remote interceptor servers | Connecting chain to external MCP servers over stdio/HTTP | Infrastructure is ready (`chain.Chain.AddMCPServer` accepts any `*mcp.ClientSession`); no convenience helpers yet |
|
||||
| Wildcard event matching | `"*"` MUST match all lifecycle events; namespace wildcards such as `"tools/*"` MAY be supported | `matchesHooks` does exact event matching only today |
|
||||
| Sending-side interception | Sending flow uses `Mutate → Validate → Send` for client→server and server→client boundaries | Only the server receiving middleware integration exists. `go-sdk` v1.7.0 now provides `Client.AddSendingMiddleware` and `Server.AddSendingMiddleware`, so this is a local implementation gap rather than an upstream SDK blocker |
|
||||
| Client feature events | `"sampling/createMessage"`, `"elicitation/create"`, `"roots/list"` | No client-side middleware integration yet; callers may still use raw method-name strings as events |
|
||||
| Per-interceptor config source and validation | `ChainExecutionParams.Config` overrides and `configSchema` validation | `ExecutionParams.Config` is passed through to `InvokeParams.Config`, but middleware does not load config and `configSchema` is not validated |
|
||||
| Remote interceptor server helpers | Convenient setup for stdio/HTTP interceptor servers | Infrastructure is ready (`chain.Chain.AddMCPServer` accepts any `*mcp.ClientSession`); no config-driven or transport-specific helper APIs yet |
|
||||
|
|
|
|||
|
|
@ -38,9 +38,10 @@ server via in-memory transport. Under the hood it:
|
|||
1. Creates an `InMemoryTransport` pair via `mcp.NewInMemoryTransports()`
|
||||
2. Connects the server side via `mcp.Server.Connect(ctx, serverTransport)`
|
||||
3. Creates an MCP client and connects via the client transport
|
||||
4. Calls `chain.AddMCPServer(ctx, clientSession)` which discovers
|
||||
4. Registers the interceptor custom sending methods on the client
|
||||
5. Calls `chain.AddMCPServer(ctx, clientSession)` which discovers
|
||||
interceptors via `interceptors/list`
|
||||
5. Returns the ready-to-use chain
|
||||
6. Returns the ready-to-use chain
|
||||
|
||||
This means interceptors are invoked through the full MCP JSON-RPC
|
||||
pathway — even when running in the same process — ensuring the same
|
||||
|
|
@ -59,22 +60,24 @@ The capability payload includes:
|
|||
|
||||
## Request/Response Lifecycle
|
||||
|
||||
When a JSON-RPC request arrives, `gomiddleware.Middleware` runs:
|
||||
When a JSON-RPC request or notification reaches the server receiving
|
||||
middleware, `gomiddleware.Middleware` runs:
|
||||
|
||||
```
|
||||
0. If method is skipped (initialize, notifications/*, interceptor/*) → passthrough
|
||||
0. If method is skipped → passthrough
|
||||
1. Marshal request params to json.RawMessage
|
||||
2. chain.Execute(ctx, {event, PhaseRequest, payload})
|
||||
→ For each interceptor: interceptor/invoke RPC via ClientSession
|
||||
3. If aborted → return JSON-RPC error
|
||||
4. Unmarshal mutated payload back into request params
|
||||
5. Call next handler next(ctx, method, req)
|
||||
6. Marshal response result to json.RawMessage
|
||||
7. chain.Execute(ctx, {event, PhaseResponse, payload})
|
||||
6. If the handler returns nil result (notification) → return
|
||||
7. Marshal response result to json.RawMessage
|
||||
8. chain.Execute(ctx, {event, PhaseResponse, payload})
|
||||
→ For each interceptor: interceptor/invoke RPC via ClientSession
|
||||
8. If aborted → return JSON-RPC error
|
||||
9. Unmarshal mutated payload back into response result
|
||||
10. Return result
|
||||
9. If aborted → return JSON-RPC error
|
||||
10. Unmarshal mutated payload back into response result
|
||||
11. Return result
|
||||
```
|
||||
|
||||
### JSON-RPC Payload Model
|
||||
|
|
@ -82,7 +85,8 @@ When a JSON-RPC request arrives, `gomiddleware.Middleware` runs:
|
|||
Interceptor handlers receive `json.RawMessage` as `inv.Payload` when
|
||||
invoked via `interceptor/invoke`. This is the SEP-correct behavior —
|
||||
payloads are JSON at the protocol level. Handlers unmarshal, inspect or
|
||||
modify, and (for mutators) set the updated JSON back on `inv.Payload`:
|
||||
modify, and (for mutators) return the updated JSON in
|
||||
`MutationResult.Payload`:
|
||||
|
||||
```go
|
||||
// Validator — unmarshal, inspect, return:
|
||||
|
|
@ -118,7 +122,9 @@ avoid intercepting lifecycle events:
|
|||
|
||||
### Intercepted
|
||||
|
||||
All JSON-RPC **method calls** routed through the server's receiving middleware:
|
||||
All JSON-RPC messages routed through the server's receiving middleware
|
||||
except the skipped methods above. The current integration is server-side
|
||||
receiving middleware only.
|
||||
|
||||
| Method | Event |
|
||||
|--------|-------|
|
||||
|
|
@ -130,8 +136,9 @@ All JSON-RPC **method calls** routed through the server's receiving middleware:
|
|||
| `resources/list` | `EventResourcesList` |
|
||||
| `resources/subscribe` | `EventResourcesSubscribe` |
|
||||
|
||||
Unknown methods pass through the middleware and are intercepted normally
|
||||
(the JSON-RPC method name is used as the event name).
|
||||
Custom methods registered with the Go SDK's receiving custom-method API
|
||||
also pass through the middleware and are intercepted using the JSON-RPC
|
||||
method name as the event name.
|
||||
|
||||
### Not Intercepted
|
||||
|
||||
|
|
@ -175,9 +182,9 @@ Response-phase validators see the post-mutation payload.
|
|||
### Mutator execution
|
||||
- Mutators run sequentially, ordered by `PriorityHint.Resolve(phase)`
|
||||
(ascending), with alphabetical name tiebreak.
|
||||
- Each mutator receives `json.RawMessage`, unmarshals, modifies, and sets
|
||||
the updated JSON back on `inv.Payload`. The chain passes the mutated
|
||||
payload from each mutator to the next.
|
||||
- Each mutator receives `json.RawMessage`, unmarshals, modifies, and
|
||||
returns updated JSON in `MutationResult.Payload`. The chain passes the
|
||||
returned payload from each mutator to the next.
|
||||
- If any mutator fails (and is not `FailOpen`), the chain aborts.
|
||||
- In `ModeAudit`, the mutated payload is not propagated to subsequent
|
||||
interceptors.
|
||||
|
|
@ -198,7 +205,7 @@ Response-phase validators see the post-mutation payload.
|
|||
|------|---------------|
|
||||
| `interceptor.go` | Interceptor interface, enums (Phase, Mode, InterceptorType, Severity), Metadata/Compat/Hook, Validator/Mutator structs and handler types, Invocation/InvocationContext/Principal, result types (ValidationResult, MutationResult) |
|
||||
| `priority.go` | Priority struct, NewPriority, Resolve, MarshalJSON, UnmarshalJSON |
|
||||
| `wire.go` | JSON-RPC method/event constants, wire types (ListParams, ListResult, InvokeParams, InvokeResult, InterceptorInfo) |
|
||||
| `wire.go` | Interceptor JSON-RPC method names, public event constants for common server methods, wire types (ListParams, ListResult, InvokeParams, InvokeResult, InterceptorInfo) |
|
||||
|
||||
### `interceptors/chain/` — chain orchestrator
|
||||
|
||||
|
|
@ -212,8 +219,8 @@ Response-phase validators see the post-mutation payload.
|
|||
| File | Responsibility |
|
||||
|------|---------------|
|
||||
| `server.go` | `Extension`, interceptor management, `Install`, `LocalChain`, capability declaration |
|
||||
| `client.go` | `RegisterSendingMethods`, which registers interceptor custom methods on an MCP client before connecting |
|
||||
| `rpc.go` | `handleList` and `handleInvoke` JSON-RPC method handlers |
|
||||
| `events.go` | Event name constants for standard MCP methods |
|
||||
|
||||
### `interceptors/integrations/gomiddleware/` — middleware
|
||||
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ Analysis of per-request costs and allocation patterns.
|
|||
|
||||
The interceptor chain follows the SEP execution model: each interceptor
|
||||
is invoked via `interceptor/invoke` JSON-RPC calls through an MCP client
|
||||
session. For in-process interceptors, `Server.LocalChain()` creates an
|
||||
in-memory transport, so the JSON-RPC overhead is minimal (no network I/O).
|
||||
session. For in-process interceptors, `Extension.LocalChain(ctx, server)`
|
||||
creates an in-memory transport, so there is no network I/O.
|
||||
|
||||
Payloads are `json.RawMessage` at the protocol level. The middleware
|
||||
marshals request params and response results once per phase, and
|
||||
|
|
@ -37,7 +37,7 @@ With interceptors active, each active phase incurs:
|
|||
| 1 | Marshal request params / response result | 1 `json.RawMessage` | 1 marshal |
|
||||
| 2 | `ChainExecutionResult` struct (with pre-allocated `Results` slice) | 1 struct + 1 slice | 0 |
|
||||
| 3 | Per-interceptor `interceptor/invoke` RPC | 1 `InvokeParams` + 1 `InvokeResult` per interceptor | 1 marshal + 1 unmarshal per interceptor (handled by go-sdk JSON-RPC layer) |
|
||||
| 4 | Validator execution (N=1 inline, N>1 goroutines) | 0 (N=1) / goroutines (N>1) | Handler-specific |
|
||||
| 4 | Validator execution | 1 goroutine per validator | Handler-specific |
|
||||
| 5 | Mutator payload threading | 0 | Payload passed as `json.RawMessage` between mutators |
|
||||
| 6 | Unmarshal mutated payload back to params/result | 0 | 1 unmarshal (if mutated) |
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue