experimental-ext-interceptors/go/sdk/interceptors/mcpserver/testharness_test.go
Kurt Degiorgio c9900f02ab
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>
2026-04-29 15:29:25 +01:00

282 lines
8.7 KiB
Go

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
},
}
}