Implement Go interceptor chain (#4)

## Summary

Implements the Go SDK for MCP interceptors — validation and mutation
middleware for any MCP server.

The framework treats interceptors as first-class MCP primitives: they
are registered on an MCP server, discoverable via `interceptors/list`,
and invocable via `interceptor/invoke` — the same JSON-RPC pattern as
tools, prompts, and resources. A chain engine orchestrates execution
across one or more interceptor servers, and an optional go-sdk
middleware integration applies interceptors automatically on every
matching request/response.

## Architecture

**Three-layer design:**

1. **`interceptors`** — Protocol-agnostic core. Defines interceptor
types (validators, mutators), metadata, invocation, wire types, and
results. Zero MCP dependencies.

2. **`interceptors/mcpserver`** — MCP server integration. Wraps
`mcp.Server` to register `interceptors/list` and `interceptor/invoke` as
custom JSON-RPC methods and advertise interceptor capabilities during
`initialize`.

3. **`interceptors/chain`** — Chain engine. Orchestrates execution
across N interceptor servers with trust-boundary-aware ordering,
priority-based mutation sequencing, parallel validation, audit-mode
isolation, and fail-open/fail-closed semantics.

4. **`interceptors/integrations/gomiddleware`** — Optional go-sdk
middleware. Installs on `mcp.Server` via `AddReceivingMiddleware()` to
automatically run the interceptor chain on every matching
request/response.

**Key design decisions:**

- **Trust-boundary ordering** — request phase: validate → mutate;
response phase: mutate → validate. Validation always guards the boundary
crossing.
- **Wire-level invocation** — the chain calls `interceptor/invoke` over
the MCP transport (even in-process via `LocalChain()`), so local and
remote interceptor servers use the same interface.
- **Audit-mode isolation** — audit-mode mutators compute transformations
without applying them. Only audit mutators pay the serialization cost.
- **Concurrency** — validators run in parallel; mutators run
sequentially in priority order.

### Package Structure

| Package | File | Responsibility |
|---------|------|----------------|
| `interceptors` | `interceptor.go` | Enums, Metadata, Interceptor
interface, Validator/Mutator structs, handler types, Invocation |
| `interceptors` | `wire.go` | Wire types: ListParams/Result,
InvokeParams/Result, InterceptorInfo, event/method constants |
| `interceptors` | `priority.go` | Priority with phase-aware resolution
and JSON marshaling |
| `interceptors` | `doc.go` | Package documentation with examples |
| `interceptors/chain` | `chain.go` | Chain engine: discovery,
filtering, sorting, execution orchestration |
| `interceptors/chain` | `result.go` | ExecutionResult, AbortInfo |
| `interceptors/chain` | `doc.go` | Sub-package documentation |
| `interceptors/mcpserver` | `server.go` | MCP server wrapper,
interceptor registry, capability advertisement, `LocalChain()` |
| `interceptors/mcpserver` | `rpc.go` | `interceptors/list` and
`interceptor/invoke` JSON-RPC handlers |
| `interceptors/mcpserver` | `doc.go` | Sub-package documentation |
| `integrations/gomiddleware` | `middleware.go` | go-sdk `Middleware`
that runs the chain on every request/response |
| `integrations/gomiddleware` | `errors.go` | Abort-to-JSONRPC error
conversion |
| `integrations/gomiddleware` | `doc.go` | Sub-package documentation |

### Documentation

- `doc/DESIGN.md` — architecture, execution model, integration with
go-sdk
- `doc/CONFORMANCE.md` — SEP conformance status
- `doc/PERFORMANCE.md` — per-request cost model

### Examples

- `examples/validator` — blocks dangerous tool calls, demonstrates
`WithContextProvider`
- `examples/mutator` — tags tool responses with audit trail

## Vendor: go-sdk v1.4.0 with custom method support

Vendors `go-sdk` with minimal extensions for custom JSON-RPC methods:

- `Server.AddCustomMethod` — registers a handler that bypasses the typed
pipeline
- `ClientSession.CallCustom` — sends raw JSON-RPC calls for custom
methods

These changes are generic (not interceptor-specific) and enable any MCP
extension to define its own JSON-RPC methods.

## TODO

- More integration tests
- Unit tests
- Support wildcards for event interception (separate PR)

---------

Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>
This commit is contained in:
Kurt Degiorgio 2026-04-29 15:29:25 +01:00 • committed by GitHub
commit c9900f02ab
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 62908 additions and 19 deletions

View file

@ -0,0 +1,52 @@
// Copyright 2025 The MCP Interceptors Authors. All rights reserved.
// Use of this source code is governed by an Apache-2.0
// license that can be found in the LICENSE file.
// Package mcpserver registers interceptors as first-class MCP
// primitives. Adding an interceptor to the server makes it
// discoverable via "interceptors/list" and invocable via
// "interceptor/invoke", so any MCP client — local or remote — can
// discover and call interceptors using standard JSON-RPC.
//
// # Getting Started
//
// Wrap an existing [mcp.Server] with [NewServer] and register
// interceptors:
//
// srv := mcpserver.NewServer(mcpServer, mcpserver.WithLogger(logger))
// srv.AddInterceptor(myValidator)
// srv.AddInterceptor(myMutator)
// srv.Run(ctx, transport)
//
// At this point any connected MCP client can call interceptors/list
// and interceptor/invoke.
//
// For convenience, [Server.LocalChain] creates a [chain.Chain] wired
// to the server over an in-memory transport, ready for use with the
// gomiddleware package:
//
// chain, err := srv.LocalChain(ctx)
// mcpServer.AddReceivingMiddleware(
// gomiddleware.Middleware(chain,
// gomiddleware.WithContextProvider(myProvider),
// ),
// )
//
// # JSON-RPC Methods
//
// The server registers two JSON-RPC methods:
//
// - "interceptors/list": Returns all registered interceptors,
// optionally filtered by event name.
// - "interceptor/invoke": Invokes a single interceptor by name
// for a given event, phase, and payload.
//
// # Transports
//
// The server works with any transport supported by the go-sdk.
// For stdio, use [Server.Run]. For HTTP, use
// [NewStreamableHTTPHandler]:
//
// handler := mcpserver.NewStreamableHTTPHandler(srv, nil)
// http.ListenAndServe(":8080", handler)
package mcpserver

View file

@ -0,0 +1,113 @@
// Copyright 2025 The MCP Interceptors Authors. All rights reserved.
// Use of this source code is governed by an Apache-2.0
// license that can be found in the LICENSE file.
package mcpserver
import (
"context"
"encoding/json"
"fmt"
"slices"
"time"
"github.com/modelcontextprotocol/go-sdk/jsonrpc"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
)
// handleList implements the "interceptors/list" JSON-RPC method.
// It returns all registered interceptors, optionally filtered by event.
func (s *Server) handleList(_ context.Context, _ *mcp.ServerSession, raw json.RawMessage) (any, error) {
var params interceptors.ListParams
if len(raw) > 0 {
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
}
all := s.getInterceptors()
infos := make([]interceptors.InterceptorInfo, 0, len(all))
for _, ri := range all {
if params.Event != "" && !slices.Contains(ri.GetMetadata().Hook.Events, params.Event) {
continue
}
infos = append(infos, interceptors.InfoFromInterceptor(ri))
}
return &interceptors.ListResult{Interceptors: infos}, nil
}
// handleInvoke implements the "interceptor/invoke" JSON-RPC method.
// It invokes a single interceptor by name and returns its result.
func (s *Server) handleInvoke(ctx context.Context, _ *mcp.ServerSession, raw json.RawMessage) (any, error) {
var params interceptors.InvokeParams
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
if params.Name == "" {
return nil, &jsonrpc.Error{
Code: jsonrpc.CodeInvalidParams,
Message: "name is required",
}
}
// Look up the interceptor by name.
i := s.findByName(params.Name)
if i == nil {
return nil, &jsonrpc.Error{
Code: jsonrpc.CodeInvalidParams,
Message: fmt.Sprintf("interceptor %q not found", params.Name),
}
}
// Apply timeout if specified.
if params.TimeoutMs > 0 {
var cancel context.CancelFunc
ctx, cancel = context.WithTimeout(ctx, time.Duration(params.TimeoutMs)*time.Millisecond)
defer cancel()
}
inv := &interceptors.Invocation{
Event: params.Event,
Phase: params.Phase,
Payload: params.Payload,
Config: params.Config,
Context: params.Context,
}
start := time.Now()
result := &interceptors.InvokeResult{
Interceptor: params.Name,
Type: i.GetType(),
Phase: params.Phase,
}
defer func() { result.DurationMs = time.Since(start).Milliseconds() }()
switch v := i.(type) {
case *interceptors.Validator:
vr, err := v.Handler(ctx, inv)
if err != nil {
return nil, err
}
result.Validation = vr
case *interceptors.Mutator:
mr, err := v.Handler(ctx, inv)
if err != nil {
return nil, err
}
result.Mutation = mr
result.Payload = mr.Payload
default:
return nil, &jsonrpc.Error{
Code: jsonrpc.CodeInternalError,
Message: fmt.Sprintf("unsupported interceptor type %T", i),
}
}
return result, nil
}

View file

@ -0,0 +1,264 @@
package mcpserver_test
import (
"context"
"encoding/json"
"fmt"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
)
// --- interceptors/list tests ---
func TestListInterceptors(t *testing.T) {
t.Parallel()
cs := setupRPCServer(t,
allowAllValidator("v1"),
blockToolValidator("dangerous"),
)
var result interceptors.ListResult
err := cs.CallCustom(context.Background(), interceptors.MethodList, nil, &result)
require.NoError(t, err)
assert.Len(t, result.Interceptors, 2)
names := make([]string, len(result.Interceptors))
for i, info := range result.Interceptors {
names[i] = info.Name
}
assert.Contains(t, names, "v1")
assert.Contains(t, names, "block-dangerous")
}
func TestListWithEventFilter(t *testing.T) {
t.Parallel()
toolsValidator := allowAllValidator("tools-v")
promptsValidator := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "prompts-v",
Hook: interceptors.Hook{
Events: []string{interceptors.EventPromptsGet},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
return &interceptors.ValidationResult{Valid: true}, nil
},
}
cs := setupRPCServer(t, toolsValidator, promptsValidator)
// Filter for tools/call — should only return tools-v
var result interceptors.ListResult
err := cs.CallCustom(context.Background(), interceptors.MethodList,
&interceptors.ListParams{Event: interceptors.EventToolsCall}, &result)
require.NoError(t, err)
assert.Len(t, result.Interceptors, 1)
assert.Equal(t, "tools-v", result.Interceptors[0].Name)
// Filter for prompts/get — should only return prompts-v
var result2 interceptors.ListResult
err = cs.CallCustom(context.Background(), interceptors.MethodList,
&interceptors.ListParams{Event: interceptors.EventPromptsGet}, &result2)
require.NoError(t, err)
assert.Len(t, result2.Interceptors, 1)
assert.Equal(t, "prompts-v", result2.Interceptors[0].Name)
// Filter for non-existent event — empty
var result3 interceptors.ListResult
err = cs.CallCustom(context.Background(), interceptors.MethodList,
&interceptors.ListParams{Event: "nonexistent/method"}, &result3)
require.NoError(t, err)
assert.Empty(t, result3.Interceptors)
}
// --- interceptor/invoke tests ---
func TestInvokeValidator(t *testing.T) {
t.Parallel()
cs := setupRPCServer(t, allowAllValidator("v1"))
payload, _ := json.Marshal(map[string]any{"name": "echo", "arguments": map[string]any{"text": "hello"}})
var result interceptors.InvokeResult
err := cs.CallCustom(context.Background(), interceptors.MethodInvoke,
&interceptors.InvokeParams{
Name: "v1",
Event: interceptors.EventToolsCall,
Phase: interceptors.PhaseRequest,
Payload: payload,
}, &result)
require.NoError(t, err)
assert.Equal(t, "v1", result.Interceptor)
assert.Equal(t, interceptors.TypeValidation, result.Type)
assert.Equal(t, interceptors.PhaseRequest, result.Phase)
require.NotNil(t, result.Validation)
assert.True(t, result.Validation.Valid)
assert.Nil(t, result.Mutation)
assert.Nil(t, result.Payload)
}
func TestInvokeValidatorRejects(t *testing.T) {
t.Parallel()
rejectAll := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "reject-all",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "rejected", Severity: interceptors.SeverityError},
},
}, nil
},
}
cs := setupRPCServer(t, rejectAll)
payload, _ := json.Marshal(map[string]any{"name": "echo"})
var result interceptors.InvokeResult
err := cs.CallCustom(context.Background(), interceptors.MethodInvoke,
&interceptors.InvokeParams{
Name: "reject-all",
Event: interceptors.EventToolsCall,
Phase: interceptors.PhaseRequest,
Payload: payload,
}, &result)
require.NoError(t, err)
assert.Equal(t, "reject-all", result.Interceptor)
assert.Equal(t, interceptors.TypeValidation, result.Type)
require.NotNil(t, result.Validation)
assert.False(t, result.Validation.Valid)
assert.Len(t, result.Validation.Messages, 1)
assert.Equal(t, "rejected", result.Validation.Messages[0].Message)
}
func TestInvokeMutator(t *testing.T) {
t.Parallel()
mutator := &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: "add-field",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected payload type %T", inv.Payload)
}
var m map[string]any
if err := json.Unmarshal(raw, &m); err != nil {
return nil, err
}
m["injected"] = true
data, err := json.Marshal(m)
if err != nil {
return nil, err
}
return &interceptors.MutationResult{Modified: true, Info: map[string]any{"added": "injected"}, Payload: json.RawMessage(data)}, nil
},
}
cs := setupRPCServer(t, mutator)
payload, _ := json.Marshal(map[string]any{"name": "echo"})
var result interceptors.InvokeResult
err := cs.CallCustom(context.Background(), interceptors.MethodInvoke,
&interceptors.InvokeParams{
Name: "add-field",
Event: interceptors.EventToolsCall,
Phase: interceptors.PhaseRequest,
Payload: payload,
}, &result)
require.NoError(t, err)
assert.Equal(t, "add-field", result.Interceptor)
assert.Equal(t, interceptors.TypeMutation, result.Type)
require.NotNil(t, result.Mutation)
assert.True(t, result.Mutation.Modified)
assert.Equal(t, "injected", result.Mutation.Info["added"])
// Verify mutated payload contains the injected field.
require.NotNil(t, result.Payload)
var mutated map[string]any
require.NoError(t, json.Unmarshal(result.Payload, &mutated))
assert.Equal(t, true, mutated["injected"])
assert.Equal(t, "echo", mutated["name"])
}
func TestInvokeUnknownName(t *testing.T) {
t.Parallel()
cs := setupRPCServer(t, allowAllValidator("v1"))
payload, _ := json.Marshal(map[string]any{})
var result interceptors.InvokeResult
err := cs.CallCustom(context.Background(), interceptors.MethodInvoke,
&interceptors.InvokeParams{
Name: "nonexistent",
Event: interceptors.EventToolsCall,
Phase: interceptors.PhaseRequest,
Payload: payload,
}, &result)
require.Error(t, err)
assert.Contains(t, err.Error(), "nonexistent")
}
func TestInvokeTimeout(t *testing.T) {
t.Parallel()
slowValidator := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "slow-v",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(ctx context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
select {
case <-time.After(5 * time.Second):
return &interceptors.ValidationResult{Valid: true}, nil
case <-ctx.Done():
return nil, ctx.Err()
}
},
}
cs := setupRPCServer(t, slowValidator)
payload, _ := json.Marshal(map[string]any{})
var result interceptors.InvokeResult
err := cs.CallCustom(context.Background(), interceptors.MethodInvoke,
&interceptors.InvokeParams{
Name: "slow-v",
Event: interceptors.EventToolsCall,
Phase: interceptors.PhaseRequest,
Payload: payload,
TimeoutMs: 50,
}, &result)
require.Error(t, err)
}

View file

@ -0,0 +1,232 @@
// Copyright 2025 The MCP Interceptors Authors. All rights reserved.
// Use of this source code is governed by an Apache-2.0
// license that can be found in the LICENSE file.
package mcpserver
import (
"context"
"log/slog"
"net/http"
"sync"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/chain"
)
// extensionID is the capability key used in Capabilities.Experimental
const extensionID = "io.modelcontextprotocol/interceptors"
// ServerOption configures a Server.
type ServerOption func(*Server)
// WithLogger sets the logger for interceptor chain execution.
// If not set, slog.Default() is used.
func WithLogger(l *slog.Logger) ServerOption {
return func(s *Server) {
s.logger = l
}
}
// Server wraps an *mcp.Server with interceptor support. Interceptors are
// registered as first-class MCP resources discoverable via the
// "interceptors/list" JSON-RPC method and invocable via
// "interceptor/invoke".
type Server struct {
inner *mcp.Server
mu sync.RWMutex
interceptors []interceptors.Interceptor
logger *slog.Logger
}
// NewServer creates a new interceptor server wrapping the given mcp.Server.
// It registers the "interceptors/list" and "interceptor/invoke" JSON-RPC
// methods and installs a receiving middleware to enrich the initialize
// response with interceptor capabilities.
func NewServer(server *mcp.Server, opts ...ServerOption) *Server {
s := &Server{
inner: server,
}
for _, opt := range opts {
opt(s)
}
if s.logger == nil {
s.logger = slog.Default()
}
// Register JSON-RPC methods for interceptor discovery and invocation.
server.AddCustomMethod(interceptors.MethodList, s.handleList)
server.AddCustomMethod(interceptors.MethodInvoke, s.handleInvoke)
// Install lightweight middleware to enrich initialize responses.
server.AddReceivingMiddleware(s.initMiddleware())
return s
}
// AddInterceptor registers an interceptor. It panics if the interceptor
// has a nil handler. Except for the panic it is safe to call while the server is running,
// returns the receiver for chaining.
func (s *Server) AddInterceptor(i interceptors.Interceptor) *Server {
switch v := i.(type) {
case *interceptors.Validator:
if v.Handler == nil {
panic("interceptors: validator " + v.Name + " has nil handler")
}
case *interceptors.Mutator:
if v.Handler == nil {
panic("interceptors: mutator " + v.Name + " has nil handler")
}
}
s.mu.Lock()
s.interceptors = append(s.interceptors, i)
s.mu.Unlock()
return s
}
// findByName returns the interceptor with the given name, or nil if not found.
func (s *Server) findByName(name string) interceptors.Interceptor {
s.mu.RLock()
defer s.mu.RUnlock()
for _, i := range s.interceptors {
if i.GetMetadata().Name == name {
return i
}
}
return nil
}
// getInterceptors returns a snapshot of the current interceptor list.
func (s *Server) getInterceptors() []interceptors.Interceptor {
s.mu.RLock()
defer s.mu.RUnlock()
cp := make([]interceptors.Interceptor, len(s.interceptors))
copy(cp, s.interceptors)
return cp
}
// LocalChain creates an interceptor Chain connected to this server
// via in-memory transport. This is the primary way to get a Chain
// for use with middleware.
//
// The returned chain discovers interceptors from the server via
// interceptors/list and invokes them via interceptor/invoke, exactly
// as a remote chain would — but over an in-memory transport.
func (s *Server) LocalChain(ctx context.Context) (*chain.Chain, error) {
serverTransport, clientTransport := mcp.NewInMemoryTransports()
// Connect the server side.
ss, err := s.inner.Connect(ctx, serverTransport, nil)
if err != nil {
return nil, err
}
// Connect a client through the other end.
client := mcp.NewClient(&mcp.Implementation{
Name: "interceptor-chain-client",
Version: "internal",
}, nil)
cs, err := client.Connect(ctx, clientTransport, nil)
if err != nil {
ss.Close()
return nil, err
}
ch := chain.NewChain(chain.WithChainLogger(s.logger))
if err := ch.AddMCPServer(ctx, cs); err != nil {
cs.Close()
ss.Close()
return nil, err
}
return ch, nil
}
// MCPServer returns the underlying *mcp.Server. This is useful when
// composing with other extensions (e.g., variants):
//
// is := mcpserver.NewServer(mcpServer)
// is.AddInterceptor(myValidator)
// vs.WithVariant(variant, is.MCPServer(), 0)
func (s *Server) MCPServer() *mcp.Server {
return s.inner
}
// Run delegates to the inner server's Run method. Convenience for standalone
// use (e.g., stdio).
func (s *Server) Run(ctx context.Context, t mcp.Transport) error {
return s.inner.Run(ctx, t)
}
// initMiddleware returns a lightweight mcp.Middleware that enriches the
// initialize response with interceptor capability metadata.
func (s *Server) initMiddleware() mcp.Middleware {
return func(next mcp.MethodHandler) mcp.MethodHandler {
return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
result, err := next(ctx, method, req)
if err != nil {
return nil, err
}
if method == "initialize" {
return s.enrichInitResult(result)
}
return result, nil
}
}
}
// enrichInitResult injects interceptor capability metadata into the
// InitializeResult, following the same pattern as the variants extension.
// The capability is declared under Capabilities.Experimental so it works
// without upstream go-sdk changes.
func (s *Server) enrichInitResult(result mcp.Result) (mcp.Result, error) {
initResult, ok := result.(*mcp.InitializeResult)
if !ok {
return result, nil
}
if initResult.Capabilities == nil {
initResult.Capabilities = &mcp.ServerCapabilities{}
}
if initResult.Capabilities.Experimental == nil {
initResult.Capabilities.Experimental = make(map[string]any)
}
all := s.getInterceptors()
supportedEvents := map[string]bool{}
for _, ri := range all {
for _, e := range ri.GetMetadata().Hook.Events {
supportedEvents[e] = true
}
}
events := make([]string, 0, len(supportedEvents))
for e := range supportedEvents {
events = append(events, e)
}
initResult.Capabilities.Experimental[extensionID] = map[string]any{
"supportedEvents": events,
}
return initResult, nil
}
// NewStreamableHTTPHandler returns a new [mcp.StreamableHTTPHandler] for
// serving multiple concurrent clients over HTTP. It mirrors
// [mcp.NewStreamableHTTPHandler].
//
// handler := mcpserver.NewStreamableHTTPHandler(srv, nil)
// http.ListenAndServe(":8080", handler)
func NewStreamableHTTPHandler(s *Server, opts *mcp.StreamableHTTPOptions) *mcp.StreamableHTTPHandler {
if s == nil {
panic("mcpserver: nil Server")
}
srv := s.MCPServer()
return mcp.NewStreamableHTTPHandler(
func(r *http.Request) *mcp.Server { return srv },
opts,
)
}

View file

@ -0,0 +1,612 @@
package mcpserver_test
import (
"context"
"encoding/json"
"fmt"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
)
func TestServer_ValidatorRejectsBlockedTool(t *testing.T) {
t.Parallel()
cs := setup(t, blockToolValidator("echo"))
_, err := callEcho(t, cs)
assert.Error(t, err)
}
func TestServer_ValidatorAllowsTool(t *testing.T) {
t.Parallel()
cs := setup(t, allowAllValidator("allow-all"))
result, err := callEcho(t, cs)
require.NoError(t, err)
assert.True(t, strings.HasPrefix(resultText(t, result), "echo:"))
}
func TestServer_MutatorModifiesResponse(t *testing.T) {
t.Parallel()
cs := setup(t, prefixMutator("prefix", "[mutated]", interceptors.PhaseResponse, 0, interceptors.ModeEnforce))
result, err := callEcho(t, cs)
require.NoError(t, err)
assert.True(t, strings.HasPrefix(resultText(t, result), "[mutated] echo:"))
}
func TestServer_ChainedMutatorsWithAuditMode(t *testing.T) {
t.Parallel()
// 5 response mutators in priority order. Mutator 3 (priority 30) is
// audit-mode: its "[AUDIT]" prefix must NOT appear in the final output.
// Expected final text (applied innermost-first by ascending priority):
//
// [M5] [M4] [M2] [M1] echo: ...
cs := setup(t,
prefixMutator("m1", "[M1]", interceptors.PhaseResponse, 10, interceptors.ModeEnforce),
prefixMutator("m2", "[M2]", interceptors.PhaseResponse, 20, interceptors.ModeEnforce),
prefixMutator("m3-audit", "[AUDIT]", interceptors.PhaseResponse, 30, interceptors.ModeAudit),
prefixMutator("m4", "[M4]", interceptors.PhaseResponse, 40, interceptors.ModeEnforce),
prefixMutator("m5", "[M5]", interceptors.PhaseResponse, 50, interceptors.ModeEnforce),
)
result, err := callEcho(t, cs)
require.NoError(t, err)
text := resultText(t, result)
assert.True(t, strings.HasPrefix(text, "[M5] [M4] [M2] [M1] echo:"))
assert.NotContains(t, text, "[AUDIT]")
}
func TestServer_MutatorFailureAbortsChain(t *testing.T) {
t.Parallel()
// 3 response mutators. Mutator 2 (priority 20) returns an error
// and is fail-closed. The chain aborts; client receives an error.
cs := setup(t,
prefixMutator("m1", "[M1]", interceptors.PhaseResponse, 10, interceptors.ModeEnforce),
failMutator("m2-fail", interceptors.PhaseResponse, 20),
prefixMutator("m3", "[M3]", interceptors.PhaseResponse, 30, interceptors.ModeEnforce),
)
_, err := callEcho(t, cs)
assert.Error(t, err)
}
func TestServer_ValidatorWarnDoesNotBlock(t *testing.T) {
t.Parallel()
// A validator returns Valid=false with only SeverityWarn messages.
// The chain should continue — warn-only failures don't abort.
warnValidator := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "warn-only",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "something looks off", Severity: interceptors.SeverityWarn},
},
}, nil
},
}
cs := setup(t, warnValidator)
result, err := callEcho(t, cs)
require.NoError(t, err)
assert.True(t, strings.HasPrefix(resultText(t, result), "echo:"))
}
func TestServer_ValidationFailurePreventsM(t *testing.T) {
t.Parallel()
// A validator rejects the request. A mutator is also registered but
// should never run because the chain aborts before mutators.
mutatorRan := atomic.Bool{}
spy := &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: "spy-mutator",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
mutatorRan.Store(true)
return &interceptors.MutationResult{Modified: false}, nil
},
}
cs := setup(t, blockToolValidator("echo"), spy)
_, err := callEcho(t, cs)
assert.Error(t, err)
assert.False(t, mutatorRan.Load(), "mutator should not run after validation failure")
}
func TestServer_ValidatorTimeoutAbortsChain(t *testing.T) {
t.Parallel()
slowValidator := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "slow-validator",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(ctx context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(100 * time.Millisecond):
return &interceptors.ValidationResult{Valid: true}, nil
}
},
}
cs := setup(t, slowValidator)
// Per-invocation timeout: context expires before the 100ms handler completes.
_, err := callEchoWithTimeout(t, cs, 5*time.Millisecond)
require.Error(t, err)
assert.Contains(t, err.Error(), "context deadline exceeded")
}
func TestServer_MutatorTimeoutAbortsChain(t *testing.T) {
t.Parallel()
// 3 response mutators. Mutator 2 (priority 20) blocks longer than
// the invocation timeout. The chain aborts; client receives an error.
slowMutator := &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: "m2-slow",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
PriorityHint: interceptors.NewPriority(20),
},
Handler: func(ctx context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-time.After(100 * time.Millisecond):
return &interceptors.MutationResult{Modified: false}, nil
}
},
}
cs := setup(t,
prefixMutator("m1", "[M1]", interceptors.PhaseResponse, 10, interceptors.ModeEnforce),
slowMutator,
prefixMutator("m3", "[M3]", interceptors.PhaseResponse, 30, interceptors.ModeEnforce),
)
// Per-invocation timeout: context expires before the 100ms handler completes.
_, err := callEchoWithTimeout(t, cs, 5*time.Millisecond)
require.Error(t, err)
assert.Contains(t, err.Error(), "context deadline exceeded")
}
func TestServer_MutatorFailOpenContinuesChain(t *testing.T) {
t.Parallel()
// 3 response mutators. Mutator 2 (priority 20) returns an error but
// has FailOpen set. The chain continues; M1 and M3 both apply.
failOpenMutator := &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: "m2-failopen",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
FailOpen: true,
PriorityHint: interceptors.NewPriority(20),
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
return nil, fmt.Errorf("simulated failure")
},
}
cs := setup(t,
prefixMutator("m1", "[M1]", interceptors.PhaseResponse, 10, interceptors.ModeEnforce),
failOpenMutator,
prefixMutator("m3", "[M3]", interceptors.PhaseResponse, 30, interceptors.ModeEnforce),
)
result, err := callEcho(t, cs)
require.NoError(t, err)
text := resultText(t, result)
assert.Contains(t, text, "[M1]")
assert.Contains(t, text, "[M3]")
}
func TestServer_ResponseMutatorSeesMutatedParams(t *testing.T) {
t.Parallel()
// A request mutator injects a marker into the arguments. A response
// mutator reads the request payload and copies the marker into the
// response text.
//
// NOTE: In the SEP model, interceptors receive json.RawMessage payloads.
// Response-phase interceptors only see the response payload, not the
// request params. This test is simplified to verify request mutation
// flows through to the echo handler's output.
reqMutator := &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: "inject-marker",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected payload type %T", inv.Payload)
}
var params map[string]any
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
args, _ := params["arguments"].(map[string]any)
if args == nil {
args = map[string]any{}
}
args["marker"] = "injected-by-request-mutator"
params["arguments"] = args
data, err := json.Marshal(params)
if err != nil {
return nil, err
}
return &interceptors.MutationResult{Modified: true, Payload: json.RawMessage(data)}, nil
},
}
cs := setup(t, reqMutator)
result, err := callEcho(t, cs)
require.NoError(t, err)
assert.Contains(t, resultText(t, result), "injected-by-request-mutator")
}
func TestServer_CombinedValidatorsAndMutators(t *testing.T) {
t.Parallel()
// Exercises the full chain with 3 validators and 3 mutators on each
// side, verifying:
//
// Request: Validate (parallel) → Mutate (sequential by priority)
// Response: Mutate (sequential by priority) → Validate (parallel)
//
// Request mutators inject fields into arguments (reflected in echo output).
// Response mutators prepend tags to text (visible in final result).
// Atomic counters confirm every interceptor actually ran.
var (
reqValCount atomic.Int32
reqMutCount atomic.Int32
respMutCount atomic.Int32
respValCount atomic.Int32
)
// --- Request validators (3, parallel) ---
// req-v1: passes if tool name is "echo".
reqV1 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "req-v1-tool-check",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
reqValCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var params struct {
Name string `json:"name"`
}
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
if params.Name != "echo" {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "only echo allowed", Severity: interceptors.SeverityError},
},
}, nil
}
return &interceptors.ValidationResult{Valid: true}, nil
},
}
// req-v2: passes if arguments contain "text".
reqV2 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "req-v2-args-check",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
reqValCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var params struct {
Arguments json.RawMessage `json:"arguments"`
}
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
var args map[string]any
if err := json.Unmarshal(params.Arguments, &args); err != nil {
return nil, err
}
if _, ok := args["text"]; !ok {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "missing text argument", Severity: interceptors.SeverityError},
},
}, nil
}
return &interceptors.ValidationResult{Valid: true}, nil
},
}
// req-v3: always passes with a warning (warn doesn't block).
reqV3 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "req-v3-warn",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
reqValCount.Add(1)
return &interceptors.ValidationResult{
Valid: true,
Messages: []interceptors.ValidationMessage{
{Message: "request noted", Severity: interceptors.SeverityWarn},
},
}, nil
},
}
// --- Request mutators (3, sequential by priority 10 → 20 → 30) ---
// Each adds a field to the arguments.
requestArgMutator := func(name, key, value string, priority int) *interceptors.Mutator {
return &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: name,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
PriorityHint: interceptors.NewPriority(priority),
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
reqMutCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var params map[string]any
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
argsRaw := params["arguments"]
var args map[string]any
if argsRaw != nil {
argsBytes, _ := json.Marshal(argsRaw)
json.Unmarshal(argsBytes, &args)
}
if args == nil {
args = map[string]any{}
}
args[key] = value
params["arguments"] = args
data, err := json.Marshal(params)
if err != nil {
return nil, err
}
return &interceptors.MutationResult{Modified: true, Payload: json.RawMessage(data)}, nil
},
}
}
reqM1 := requestArgMutator("req-m1", "step1", "done", 10)
reqM2 := requestArgMutator("req-m2", "step2", "done", 20)
reqM3 := requestArgMutator("req-m3", "step3", "done", 30)
// --- Response mutators (3, sequential by priority 10 → 20 → 30) ---
// Each prepends a tag. Applied innermost-first, so final text is:
// [RM3] [RM2] [RM1] echo: ...
respPrefixMutator := func(name, tag string, priority int) *interceptors.Mutator {
return &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: name,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
PriorityHint: interceptors.NewPriority(priority),
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
respMutCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var result mcp.CallToolResult
if err := json.Unmarshal(raw, &result); err != nil {
return nil, err
}
for _, c := range result.Content {
if tc, ok := c.(*mcp.TextContent); ok {
tc.Text = tag + " " + tc.Text
}
}
data, err := json.Marshal(&result)
if err != nil {
return nil, err
}
return &interceptors.MutationResult{Modified: true, Payload: json.RawMessage(data)}, nil
},
}
}
respM1 := respPrefixMutator("resp-m1", "[RM1]", 10)
respM2 := respPrefixMutator("resp-m2", "[RM2]", 20)
respM3 := respPrefixMutator("resp-m3", "[RM3]", 30)
// --- Response validators (3, parallel) ---
// Run after response mutators.
// resp-v1: passes if response has content.
respV1 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "resp-v1-has-content",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
respValCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var result mcp.CallToolResult
if err := json.Unmarshal(raw, &result); err != nil {
return nil, err
}
if len(result.Content) == 0 {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "empty response", Severity: interceptors.SeverityError},
},
}, nil
}
return &interceptors.ValidationResult{Valid: true}, nil
},
}
// resp-v2: rejects if response text doesn't contain "[RM1]".
// This proves the response-side ordering (Mutate → Validate): if
// this validator ran before mutators, it wouldn't find the tag.
respV2 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "resp-v2-sees-mutation",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
respValCount.Add(1)
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected type %T", inv.Payload)
}
var result mcp.CallToolResult
if err := json.Unmarshal(raw, &result); err != nil {
return nil, err
}
for _, c := range result.Content {
if tc, ok := c.(*mcp.TextContent); ok {
if strings.Contains(tc.Text, "[RM1]") {
return &interceptors.ValidationResult{Valid: true}, nil
}
}
}
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: "response missing mutator tag [RM1]", Severity: interceptors.SeverityError},
},
}, nil
},
}
// resp-v3: always passes with an info message.
respV3 := &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "resp-v3-info",
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseResponse,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
respValCount.Add(1)
return &interceptors.ValidationResult{
Valid: true,
Messages: []interceptors.ValidationMessage{
{Message: "response looks good", Severity: interceptors.SeverityInfo},
},
}, nil
},
}
cs := setup(t,
reqV1, reqV2, reqV3,
reqM1, reqM2, reqM3,
respM1, respM2, respM3,
respV1, respV2, respV3,
)
result, err := callEcho(t, cs)
require.NoError(t, err)
text := resultText(t, result)
// Response mutators applied in priority order (outermost = highest priority).
assert.True(t, strings.HasPrefix(text, "[RM3] [RM2] [RM1] echo:"),
"expected response mutator tags in priority order, got: %s", text)
// Request mutators injected fields into arguments (visible in echo output).
assert.Contains(t, text, "step1")
assert.Contains(t, text, "step2")
assert.Contains(t, text, "step3")
// Every interceptor ran exactly once.
assert.Equal(t, int32(3), reqValCount.Load(), "expected 3 request validators to run")
assert.Equal(t, int32(3), reqMutCount.Load(), "expected 3 request mutators to run")
assert.Equal(t, int32(3), respMutCount.Load(), "expected 3 response mutators to run")
assert.Equal(t, int32(3), respValCount.Load(), "expected 3 response validators to run")
}

View file

@ -0,0 +1,282 @@
package mcpserver_test
import (
"context"
"encoding/json"
"fmt"
"net/http/httptest"
"testing"
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/stretchr/testify/require"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/integrations/gomiddleware"
"github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors/mcpserver"
)
// --- Server setup ---
// setup creates an HTTP test server with interceptor support and a connected
// client session. The server has a single "echo" tool registered for
// EventToolsCall. Cleanup is registered via t.Cleanup.
func setup(t *testing.T, is ...interceptors.Interceptor) *mcp.ClientSession {
t.Helper()
return setupWithTools(t, defaultTools(), is...)
}
// setupWithTools creates an HTTP test server with the given tools and
// interceptors. Uses LocalChain to create a chain that invokes
// interceptors via interceptor/invoke over in-memory transport.
// Cleanup is registered via t.Cleanup.
func setupWithTools(t *testing.T, tools []testTool, is ...interceptors.Interceptor) *mcp.ClientSession {
t.Helper()
mcpServer := mcp.NewServer(&mcp.Implementation{
Name: "test-server",
Version: "0.1.0",
}, nil)
for _, tool := range tools {
mcpServer.AddTool(tool.tool, tool.handler)
}
srv := mcpserver.NewServer(mcpServer)
for _, i := range is {
srv.AddInterceptor(i)
}
// Create a chain via LocalChain (in-memory transport).
chain, err := srv.LocalChain(context.Background())
require.NoError(t, err)
// Install the middleware for automatic interceptor execution.
mcpServer.AddReceivingMiddleware(gomiddleware.Middleware(chain))
handler := mcpserver.NewStreamableHTTPHandler(srv, nil)
httpServer := httptest.NewServer(handler)
t.Cleanup(httpServer.Close)
client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "0.1.0"}, nil)
cs, err := client.Connect(context.Background(), &mcp.StreamableClientTransport{
Endpoint: httpServer.URL,
}, nil)
require.NoError(t, err)
t.Cleanup(func() { cs.Close() })
return cs
}
// --- Tool definitions ---
// testTool pairs a tool definition with its handler for use with setupWithTools.
type testTool struct {
tool *mcp.Tool
handler mcp.ToolHandler
}
// defaultTools returns the standard "echo" tool used by most tests.
func defaultTools() []testTool {
return []testTool{
{
tool: &mcp.Tool{
Name: "echo",
Description: "echoes input",
InputSchema: map[string]any{"type": "object"},
},
handler: func(_ context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("echo: %s", req.Params.Arguments)}},
}, nil
},
},
}
}
// --- Call helpers ---
// callEcho calls the "echo" tool and returns the result.
func callEcho(t *testing.T, cs *mcp.ClientSession) (*mcp.CallToolResult, error) {
t.Helper()
return cs.CallTool(context.Background(), &mcp.CallToolParams{
Name: "echo",
Arguments: map[string]any{"text": "hello"},
})
}
// callEchoWithTimeout calls the "echo" tool with a context timeout.
func callEchoWithTimeout(t *testing.T, cs *mcp.ClientSession, timeout time.Duration) (*mcp.CallToolResult, error) {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
return cs.CallTool(ctx, &mcp.CallToolParams{
Name: "echo",
Arguments: map[string]any{"text": "hello"},
})
}
// --- Assertion helpers ---
// resultText extracts the first TextContent string from a CallToolResult.
// Fails the test if the result has no content or the first item isn't TextContent.
func resultText(t *testing.T, result *mcp.CallToolResult) string {
t.Helper()
require.NotEmpty(t, result.Content)
tc, ok := result.Content[0].(*mcp.TextContent)
require.True(t, ok, "expected TextContent, got %T", result.Content[0])
return tc.Text
}
// --- RPC server setup ---
// setupRPCServer creates an interceptor server with the given interceptors
// and returns a connected client session. The client can call custom methods
// via raw JSON-RPC.
func setupRPCServer(t *testing.T, is ...interceptors.Interceptor) *mcp.ClientSession {
t.Helper()
mcpServer := mcp.NewServer(&mcp.Implementation{
Name: "test-server",
Version: "0.1.0",
}, nil)
// A minimal tool so the server has something to initialize with.
mcpServer.AddTool(&mcp.Tool{
Name: "echo",
Description: "echoes input",
InputSchema: map[string]any{"type": "object"},
}, func(_ context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("echo: %s", req.Params.Arguments)}},
}, nil
})
srv := mcpserver.NewServer(mcpServer)
for _, i := range is {
srv.AddInterceptor(i)
}
handler := mcpserver.NewStreamableHTTPHandler(srv, nil)
httpServer := httptest.NewServer(handler)
t.Cleanup(httpServer.Close)
client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "0.1.0"}, nil)
cs, err := client.Connect(context.Background(), &mcp.StreamableClientTransport{
Endpoint: httpServer.URL,
}, nil)
require.NoError(t, err)
t.Cleanup(func() { cs.Close() })
return cs
}
// --- Interceptor builders ---
// All handlers work with json.RawMessage payloads since that's what
// interceptor/invoke delivers.
// prefixMutator creates a mutator that prepends tag to each TextContent
// in a CallToolResult (response phase).
func prefixMutator(name, tag string, phase interceptors.InterceptionPhase, priority int, mode interceptors.Mode) *interceptors.Mutator {
return &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: name,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: phase,
},
Mode: mode,
PriorityHint: interceptors.NewPriority(priority),
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.MutationResult, error) {
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected payload type %T", inv.Payload)
}
var result mcp.CallToolResult
if err := json.Unmarshal(raw, &result); err != nil {
return nil, err
}
for _, c := range result.Content {
if tc, ok := c.(*mcp.TextContent); ok {
tc.Text = tag + " " + tc.Text
}
}
data, err := json.Marshal(&result)
if err != nil {
return nil, err
}
return &interceptors.MutationResult{Modified: true, Payload: json.RawMessage(data)}, nil
},
}
}
// failMutator creates a mutator that always returns an error.
func failMutator(name string, phase interceptors.InterceptionPhase, priority int) *interceptors.Mutator {
return &interceptors.Mutator{
Metadata: interceptors.Metadata{
Name: name,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: phase,
},
Mode: interceptors.ModeEnforce,
PriorityHint: interceptors.NewPriority(priority),
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.MutationResult, error) {
return nil, fmt.Errorf("simulated failure")
},
}
}
// blockToolValidator creates a request validator that rejects calls to the named tool.
func blockToolValidator(toolName string) *interceptors.Validator {
return &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: "block-" + toolName,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
raw, ok := inv.Payload.(json.RawMessage)
if !ok {
return nil, fmt.Errorf("unexpected payload type %T", inv.Payload)
}
var params struct {
Name string `json:"name"`
}
if err := json.Unmarshal(raw, &params); err != nil {
return nil, err
}
if params.Name == toolName {
return &interceptors.ValidationResult{
Valid: false,
Messages: []interceptors.ValidationMessage{
{Message: toolName + " is blocked", Severity: interceptors.SeverityError},
},
}, nil
}
return &interceptors.ValidationResult{Valid: true}, nil
},
}
}
// allowAllValidator creates a request validator that allows all calls.
func allowAllValidator(name string) *interceptors.Validator {
return &interceptors.Validator{
Metadata: interceptors.Metadata{
Name: name,
Hook: interceptors.Hook{
Events: []string{interceptors.EventToolsCall},
Phase: interceptors.PhaseRequest,
},
Mode: interceptors.ModeEnforce,
},
Handler: func(_ context.Context, _ *interceptors.Invocation) (*interceptors.ValidationResult, error) {
return &interceptors.ValidationResult{Valid: true}, nil
},
}
}