Rename mcpserver package to extension, remove *mcp.Server field (#11)

## Summary

- Rename `interceptors/mcpserver/` → `interceptors/extension/`,
replacing the `Server` wrapper with a lightweight `Extension` that can
install itself on any `*mcp.Server`
- Remove the stored `*mcp.Server` field — `Extension` is now a pure
interceptor container with no server reference
- Add `Install(server)` method to register JSON-RPC methods and init
middleware on a given server
- Update `LocalChain(ctx)` → `LocalChain(ctx, server)` to accept the
server as a parameter
- Remove `MCPServer()`, `Run()`, and `NewStreamableHTTPHandler()`
wrapper methods — users interact with `mcp.Server` directly
- Update all examples, tests, and documentation to use the new API

## Why

`mcpserver.Server` pretended to *be* the server — it had `Run()`,
`NewStreamableHTTPHandler()`, etc. — but it could never cover the full
`*mcp.Server` API, so users constantly needed `MCPServer()` to unwrap
it.

`Extension` doesn't pretend to be the server. It's a pure interceptor
container that can install itself on any server (or multiple servers)
on the fly. No stored server reference, no wrapping, no delegation
surface to maintain.

### Before

```go
mcpServer := mcp.NewServer(...)
srv := mcpserver.NewServer(mcpServer)
srv.AddInterceptor(v)
chain, err := srv.LocalChain(ctx)
```

### After

```go
mcpServer := mcp.NewServer(...)
ext := extension.New()
ext.AddInterceptor(v)
ext.Install(mcpServer)
chain, err := ext.LocalChain(ctx, mcpServer)
```

Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>
This commit is contained in:
Kurt Degiorgio 2026-04-30 15:57:18 +01:00 • committed by GitHub
commit 074dc6cdbd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -1,232 +0,0 @@
// 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,
)
}