Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(mcp): support 2026-07-28 alongside legacy clients (#4095)

Perfecto03e2c47aecbf
diff --git a/go.mod b/go.mod
index 7ce2b564e..446d06638 100644
--- a/go.mod
+++ b/go.mod
@@ -34,7 +34,7 @@ require (
github.com/joho/godotenv v1.5.1
github.com/ks3sdklib/aws-sdk-go v1.11.0
github.com/larksuite/oapi-sdk-go/v3 v3.9.7
- github.com/mark3labs/mcp-go v0.52.0
+ github.com/mark3labs/mcp-go v1.1.1
github.com/matiasinsaurralde/go-e2b v0.1.1-0.20260808041540-fdc08ceaa1c1
github.com/milvus-io/milvus/client/v2 v2.6.4
github.com/minio/minio-go/v7 v7.1.0
diff --git a/go.sum b/go.sum
index 528734cfd..de97b765a 100644
--- a/go.sum
+++ b/go.sum
@@ -2231,8 +2231,8 @@ github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czP
github.com/magiconair/properties v1.8.1/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ=
github.com/mailru/easyjson v0.9.0 h1:PrnmzHw7262yW8sTBwxi1PdJA3Iw/EKBa8psRf7d9a4=
github.com/mailru/easyjson v0.9.0/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
-github.com/mark3labs/mcp-go v0.52.0 h1:uRSzupNSUyPGDpF4owY5X4zEpACPwBnlM3FAFuXN6gQ=
-github.com/mark3labs/mcp-go v0.52.0/go.mod h1:Zg9cB2HdwdMMVgY0xtTzq3KvYIOJQDsaut+jWjwDaQY=
+github.com/mark3labs/mcp-go v1.1.1 h1:PMZjyayCF01Y4R2kQXgDtsmxVLOdq1Mol4CnzzTYSEo=
+github.com/mark3labs/mcp-go v1.1.1/go.mod h1:r2fW4o3wsoJ7IMsx1Wuq5xeP8PRGXPDfNveoGAYbb/s=
github.com/matiasinsaurralde/go-e2b v0.1.1-0.20260808041540-fdc08ceaa1c1 h1:iEhD0FOnY0m/7SyTF3vijOXbO++uLNckvD2Ttp87vw0=
github.com/matiasinsaurralde/go-e2b v0.1.1-0.20260808041540-fdc08ceaa1c1/go.mod h1:JTycrO2WcWcZeUNZH6XIk10sV7UixdsGKOt4HQXZiiQ=
github.com/matryer/is v1.4.0/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
diff --git a/internal/application/service/mcp_metadata.go b/internal/application/service/mcp_metadata.go
index 7a34298d3..3478d1da2 100644
--- a/internal/application/service/mcp_metadata.go
+++ b/internal/application/service/mcp_metadata.go
@@ -221,6 +221,9 @@ func (s *mcpServiceService) RefreshMCPMetadata(
if err != nil {
return nil, fmt.Errorf("could not refresh complete MCP directory: %w", err)
}
+ if s.mcpManager != nil {
+ s.mcpManager.InvalidateToolSchemas(service.ID, client)
+ }
const maxLoggedTools = 30
logged := 0
for i, tool := range listed {
diff --git a/internal/application/service/mcp_metadata_test.go b/internal/application/service/mcp_metadata_test.go
index 2ffba28a0..a9ef9621f 100644
--- a/internal/application/service/mcp_metadata_test.go
+++ b/internal/application/service/mcp_metadata_test.go
@@ -1,10 +1,14 @@
package service
import (
+ "bytes"
"context"
"encoding/json"
+ "io"
+ "net/http"
"net/http/httptest"
"strings"
+ "sync"
"testing"
"github.com/Tencent/WeKnora/internal/application/repository"
@@ -19,6 +23,94 @@ import (
"gorm.io/gorm"
)
+func TestMCPMetadataRefreshInvalidatesLiveHeaderSchemas(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ require.NoError(t, err)
+ require.NoError(t, db.AutoMigrate(&types.MCPService{}, &types.MCPMetadata{}))
+ repo := repository.NewMCPServiceRepository(db)
+ manager := mcp.NewMCPManager(nil)
+ t.Cleanup(manager.Shutdown)
+ metadata := NewMCPServiceService(repo, manager, nil).(interfaces.MCPMetadataService)
+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(1))
+ server := sdkserver.NewMCPServer("Regions", "1")
+ setHeader := func(name string) {
+ server.AddTool(sdkmcp.Tool{Name: "lookup", RawInputSchema: json.RawMessage(
+ `{"type":"object","properties":{"place":{"type":"string","x-mcp-header":"` + name + `"}}}`,
+ )}, func(context.Context, sdkmcp.CallToolRequest) (*sdkmcp.CallToolResult, error) {
+ return sdkmcp.NewToolResultText("ok"), nil
+ })
+ }
+ setHeader("Region")
+ handler := sdkserver.NewStreamableHTTPServer(server, sdkserver.WithStateLess(true))
+ var mu sync.Mutex
+ lists := 0
+ var sent []string
+ upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method == http.MethodPost {
+ body, _ := io.ReadAll(r.Body)
+ r.Body = io.NopCloser(bytes.NewReader(body))
+ var request struct {
+ Method string `json:"method"`
+ }
+ _ = json.Unmarshal(body, &request)
+ mu.Lock()
+ switch request.Method {
+ case "tools/list":
+ lists++
+ case "tools/call":
+ sent = append(sent, "region="+r.Header.Get("Mcp-Param-Region")+
+ " zone="+r.Header.Get("Mcp-Param-Zone"))
+ }
+ mu.Unlock()
+ }
+ handler.ServeHTTP(w, r)
+ }))
+ t.Cleanup(upstream.Close)
+ service := &types.MCPService{
+ ID: "svc", TenantID: 1, Name: "Regions", Enabled: true,
+ URL: &upstream.URL, TransportType: types.MCPTransportHTTPStreamable,
+ }
+ require.NoError(t, repo.Create(ctx, service))
+ stored, err := repo.GetByID(ctx, 1, "svc")
+ require.NoError(t, err)
+ live, err := manager.GetOrCreateClient(ctx, stored)
+ require.NoError(t, err)
+ counts := func() (int, []string) {
+ mu.Lock()
+ defer mu.Unlock()
+ return lists, append([]string(nil), sent...)
+ }
+ call := func(value string) {
+ t.Helper()
+ result, err := live.CallTool(ctx, "lookup", map[string]interface{}{"place": value})
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+ }
+
+ call("A")
+ listsBefore, headers := counts()
+ require.Equal(t, 1, listsBefore)
+ require.Equal(t, []string{"region=A zone="}, headers)
+
+ setHeader("Zone")
+ _, err = metadata.RefreshMCPMetadata(ctx, 1, "svc")
+ require.NoError(t, err)
+ afterRefresh, _ := counts()
+ require.Equal(t, listsBefore+1, afterRefresh, "the refresh lists on its own temporary client")
+ require.True(t, live.IsConnected(), "invalidation keeps the live connection")
+
+ call("B")
+ afterCall, headers := counts()
+ require.Equal(t, afterRefresh+1, afterCall, "the live client reloads its directory")
+ require.Equal(t, []string{"region=A zone=", "region= zone=B"}, headers)
+ call("C")
+ afterReuse, headers := counts()
+ require.Equal(t, afterCall, afterReuse, "the reloaded directory is cached again")
+ require.Equal(t, "region= zone=C", headers[2])
+}
+
func TestMCPMetadataRefreshAndOfflineEditing(t *testing.T) {
utils.SetSSRFWhitelistFromRaw("127.0.0.1")
t.Cleanup(utils.ResetSSRFWhitelistForTest)
diff --git a/internal/application/service/mcp_service.go b/internal/application/service/mcp_service.go
index a595c0d28..0516349a2 100644
--- a/internal/application/service/mcp_service.go
+++ b/internal/application/service/mcp_service.go
@@ -430,6 +430,8 @@ func (s *mcpServiceService) TestMCPService(
}
logger.GetLogger(ctx).Warnf("Failed to list tools: %v", err)
tools = []*types.MCPTool{}
+ } else if s.mcpManager != nil {
+ s.mcpManager.InvalidateToolSchemas(service.ID, client)
}
resources, err := client.ListResources(testCtx)
diff --git a/internal/mcp/client.go b/internal/mcp/client.go
index c490af998..29553aa38 100644
--- a/internal/mcp/client.go
+++ b/internal/mcp/client.go
@@ -70,11 +70,58 @@ type ClientConfig struct {
type mcpGoClient struct {
service *types.MCPService
client *client.Client
+ discovery *discoverTransport
oauth *oauthRuntime
connected atomic.Bool
initialized atomic.Bool
metadataMu sync.RWMutex
instructions string
+ toolSchemas map[string]json.RawMessage
+ // newProbe builds an independent connection with the same outbound policy.
+ newProbe func() (*mcpGoClient, error)
+}
+
+// The SDK hides probe failures when the legacy handshake succeeds. Observe
+// transport failures so a temporary outage does not permanently select legacy.
+type discoverTransport struct {
+ transport.HTTPConnection
+ failed atomic.Bool
+ // probeOnly stops the SDK's legacy fallback from opening a second session.
+ probeOnly atomic.Bool
+}
+
+var errDiscoverProbeOnly = errors.New("protocol probe does not open legacy sessions")
+
+func (t *discoverTransport) SendRequest(
+ ctx context.Context, request transport.JSONRPCRequest,
+) (*transport.JSONRPCResponse, error) {
+ if request.Method == string(mcp.MethodInitialize) && t.probeOnly.Load() {
+ return nil, errDiscoverProbeOnly
+ }
+ response, err := t.HTTPConnection.SendRequest(ctx, request)
+ if request.Method == string(mcp.MethodServerDiscover) {
+ // JSON-RPC errors, including method-not-found, are valid peer answers
+ // and must remain under the SDK's protocol negotiation policy.
+ t.failed.Store(err != nil)
+ }
+ return response, err
+}
+
+func (t *discoverTransport) SetRequestHandler(handler transport.RequestHandler) {
+ if bidirectional, ok := t.HTTPConnection.(transport.BidirectionalInterface); ok {
+ bidirectional.SetRequestHandler(handler)
+ }
+}
+
+func (t *discoverTransport) SetConnectionLostHandler(handler func(error)) {
+ if setter, ok := t.HTTPConnection.(interface{ SetConnectionLostHandler(func(error)) }); ok {
+ setter.SetConnectionLostHandler(handler)
+ }
+}
+
+func (t *discoverTransport) RequiresLegacyProtocol() bool {
+ legacy, ok := t.HTTPConnection.(interface{ RequiresLegacyProtocol() bool })
+ return ok && legacy.RequiresLegacyProtocol()
}
// applyAuthHeaders injects the auth header for the SELECTED strategy only —
@@ -161,10 +208,7 @@ func NewMCPClient(config *ClientConfig) (MCPClient, error) {
}
// Create HTTP client with timeout
- timeout := 30 * time.Second
- if config.Service.AdvancedConfig != nil && config.Service.AdvancedConfig.Timeout > 0 {
- timeout = time.Duration(config.Service.AdvancedConfig.Timeout) * time.Second
- }
+ timeout := serviceTimeout(config.Service)
clientCfg := secutils.DefaultSSRFSafeHTTPClientConfig()
clientCfg.SameOriginRedirectsOnly = true
@@ -188,23 +232,20 @@ func NewMCPClient(config *ClientConfig) (MCPClient, error) {
}
// Create client based on transport type
- var mcpClient *client.Client
+ var connection transport.HTTPConnection
switch config.Service.TransportType {
case types.MCPTransportSSE:
if config.Service.URL == nil || *config.Service.URL == "" {
return nil, fmt.Errorf("URL is required for SSE transport")
}
+ options := []transport.ClientOption{
+ transport.WithHTTPClient(httpClient),
+ transport.WithHeaders(headers),
+ }
if useOAuth {
- mcpClient, err = client.NewOAuthSSEClient(*config.Service.URL, oauthConfig,
- transport.WithHTTPClient(httpClient),
- transport.WithHeaders(headers),
- )
- } else {
- mcpClient, err = client.NewSSEMCPClient(*config.Service.URL,
- client.WithHTTPClient(httpClient),
- client.WithHeaders(headers),
- )
+ options = append(options, transport.WithOAuth(oauthConfig))
}
+ connection, err = transport.NewSSE(*config.Service.URL, options...)
if err != nil {
return nil, fmt.Errorf("failed to create SSE client: %w", err)
}
@@ -212,18 +253,14 @@ func NewMCPClient(config *ClientConfig) (MCPClient, error) {
if config.Service.URL == nil || *config.Service.URL == "" {
return nil, fmt.Errorf("URL is required for HTTP Streamable transport")
}
+ options := []transport.StreamableHTTPCOption{
+ transport.WithHTTPBasicClient(httpClient),
+ transport.WithHTTPHeaders(headers),
+ }
if useOAuth {
- mcpClient, err = client.NewOAuthStreamableHttpClient(*config.Service.URL, oauthConfig,
- transport.WithHTTPBasicClient(httpClient),
- transport.WithHTTPHeaders(headers),
- )
- } else {
- // For HTTP streamable, we need to use transport options
- mcpClient, err = client.NewStreamableHttpClient(*config.Service.URL,
- transport.WithHTTPBasicClient(httpClient),
- transport.WithHTTPHeaders(headers),
- )
+ options = append(options, transport.WithHTTPOAuth(oauthConfig))
}
+ connection, err = transport.NewStreamableHTTP(*config.Service.URL, options...)
if err != nil {
return nil, fmt.Errorf("failed to create HTTP streamable client: %w", err)
}
@@ -234,9 +271,12 @@ func NewMCPClient(config *ClientConfig) (MCPClient, error) {
return nil, ErrUnsupportedTransport
}
+ discovery := &discoverTransport{HTTPConnection: connection}
+ mcpClient := client.NewClient(discovery, client.WithDiscoverTimeout(discoverProbeTimeout(config.Service)))
instance := &mcpGoClient{
- service: config.Service,
- client: mcpClient,
+ service: config.Service,
+ client: mcpClient,
+ discovery: discovery,
}
if useOAuth {
instance.oauth = newOAuthRuntime(
@@ -248,10 +288,33 @@ func NewMCPClient(config *ClientConfig) (MCPClient, error) {
oauthConfig,
)
}
+ probeConfig := *config
+ instance.newProbe = func() (*mcpGoClient, error) {
+ cfg := probeConfig
+ probe, err := NewMCPClient(&cfg)
+ if err != nil {
+ return nil, err
+ }
+ return probe.(*mcpGoClient), nil
+ }
mcpClient.OnConnectionLost(instance.onConnectionLost)
return instance, nil
}
+func serviceTimeout(service *types.MCPService) time.Duration {
+ if service.AdvancedConfig != nil && service.AdvancedConfig.Timeout > 0 {
+ return time.Duration(service.AdvancedConfig.Timeout) * time.Second
+ }
+ return 30 * time.Second
+}
+
+// Each of at most two probes gets a quarter of the service timeout, capped at
+// 2.5s: together they use at most half the budget and 5s, leaving time for
+// legacy handshakes even with a 1s service timeout.
+func discoverProbeTimeout(service *types.MCPService) time.Duration {
+ return min(serviceTimeout(service)/4, 2500*time.Millisecond)
+}
+
// buildOAuthConfig returns the OAuth configuration for an OAuth-enabled MCP
// service, or (_, false, nil) when the service does not use OAuth. It loads
// the dynamically-registered client_id and wires a per-user token store so
@@ -297,9 +360,13 @@ func (c *mcpGoClient) onConnectionLost(err error) {
// checkErrorAndDisconnectIfNeeded checks for transport errors that indicate the
// session is no longer valid and proactively disconnects the client so that
// subsequent GetOrCreateClient calls will establish a fresh connection.
-// Both SSE and HTTP Streamable transports use server-assigned sessions
-// (via Mcp-Session-Id header) that can expire or be invalidated.
+// Modern Streamable HTTP maps method-level 404s to session termination too,
+// but modern SSE can still lose its transport session.
func (c *mcpGoClient) checkErrorAndDisconnectIfNeeded(err error) {
+ if c.client != nil && mcp.IsModernProtocol(c.client.ProtocolVersion()) &&
+ errors.Is(err, transport.ErrSessionTerminated) {
+ return
+ }
var transportErr *transport.Error
if !errors.As(err, &transportErr) || transportErr.Err == nil {
return
@@ -370,6 +437,9 @@ func (c *mcpGoClient) Disconnect() error {
return nil
}
c.initialized.Store(false)
+ c.metadataMu.Lock()
+ c.toolSchemas = nil
+ c.metadataMu.Unlock()
// Close the client
if c.client != nil {
@@ -397,8 +467,17 @@ func (c *mcpGoClient) Initialize(ctx context.Context) (*InitializeResult, error)
}
result, err := oauthCall(ctx, c, func() (*mcp.InitializeResult, error) {
- return c.client.Initialize(ctx, req)
+ result, err := c.client.Initialize(ctx, req)
+ if ctx.Err() != nil {
+ return nil, ctx.Err()
+ }
+ return result, err
})
+ if err == nil && c.shouldReprobe(ctx, result.ProtocolVersion) {
+ if modern := c.adoptModernProbe(ctx, req); modern != nil {
+ result = modern
+ }
+ }
if err != nil {
c.checkErrorAndDisconnectIfNeeded(err)
if oerr := asOAuthRequired(err); oerr != nil {
@@ -462,6 +541,48 @@ func (c *mcpGoClient) Initialize(ctx context.Context) (*InitializeResult, error)
}, nil
}
+// A transient discover failure gets one more probe before the manager caches a
+// legacy client, unless too little time is left for it.
+func (c *mcpGoClient) shouldReprobe(ctx context.Context, version string) bool {
+ if mcp.IsModernProtocol(version) || c.newProbe == nil || c.discovery == nil || !c.discovery.failed.Load() {
+ return false
+ }
+ deadline, ok := ctx.Deadline()
+ return !ok || time.Until(deadline) >= discoverProbeTimeout(c.service)
+}
+
+// A second Initialize on the live client would send server/discover without
+// Mcp-Session-Id. Stateful legacy peers answer 404, which the SDK treats as
+// session termination and clears the working session even if it then falls
+// back to legacy. Probe on an independent connection instead and adopt it only
+// once it has negotiated the stateless protocol; otherwise the live session
+// stays untouched.
+func (c *mcpGoClient) adoptModernProbe(ctx context.Context, req mcp.InitializeRequest) *mcp.InitializeResult {
+ probe, err := c.newProbe()
+ if err != nil {
+ return nil
+ }
+ probe.discovery.probeOnly.Store(true)
+ if err := probe.Connect(ctx); err != nil {
+ _ = probe.client.Close()
+ return nil
+ }
+ result, err := probe.client.Initialize(ctx, req)
+ if err != nil || ctx.Err() != nil || !mcp.IsModernProtocol(result.ProtocolVersion) {
+ _ = probe.Disconnect()
+ return nil
+ }
+ probe.discovery.probeOnly.Store(false)
+ legacy := c.client
+ legacy.OnConnectionLost(func(error) {})
+ c.client, c.discovery, c.oauth = probe.client, probe.discovery, probe.oauth
+ c.client.OnConnectionLost(c.onConnectionLost)
+ _ = legacy.Close()
+ logger.Debugf(ctx, "MCP protocol re-probe adopted %s service=%s",
+ result.ProtocolVersion, secutils.SanitizeForLog(c.service.Name))
+ return result
+}
+
// ServerInstructions retains server-wide MCP documentation from initialize.
// It is separate from credentials and can accompany model-facing tools.
func (c *mcpGoClient) ServerInstructions() string {
@@ -483,10 +604,24 @@ func (c *mcpGoClient) ListTools(ctx context.Context) ([]*types.MCPTool, error) {
c.checkErrorAndDisconnectIfNeeded(err)
return nil, fmt.Errorf("failed to list tools: %w", err)
}
+ // Publish header annotations only after the bounded directory is complete.
+ schemas := make(map[string]json.RawMessage, len(tools))
+ for _, tool := range tools {
+ schemas[tool.Name] = append(json.RawMessage(nil), tool.InputSchema...)
+ }
+ c.metadataMu.Lock()
+ c.toolSchemas = schemas
+ c.metadataMu.Unlock()
return tools, nil
}
+func (c *mcpGoClient) invalidateToolSchemas() {
+ c.metadataMu.Lock()
+ c.toolSchemas = nil
+ c.metadataMu.Unlock()
+}
+
// A tenant-supplied MCP endpoint is untrusted, and the whole directory is held
// in memory and schema-compiled afterwards. Bound protocol pagination so a
// hostile or looping server cannot grow it without limit under the list
@@ -512,13 +647,29 @@ func (c *mcpGoClient) listRawTools(ctx context.Context) ([]*types.MCPTool, error
if pages >= maxToolListPages {
return nil, fmt.Errorf("tools/list exceeded %d pages", maxToolListPages)
}
+ params := struct {
+ Cursor string `json:"cursor,omitempty"`
+ Meta *mcp.Meta `json:"_meta,omitempty"`
+ }{Cursor: cursor}
+ var headers http.Header
+ if version := c.client.ProtocolVersion(); mcp.IsModernProtocol(version) {
+ // This raw-schema path bypasses the SDK request builder. Use its
+ // metadata/header helpers without losing unknown JSON Schema fields.
+ params.Meta = &mcp.Meta{}
+ params.Meta.SetProtocolVersion(version)
+ params.Meta.SetClientInfo(mcp.Implementation{Name: "WeKnora", Version: "1.0.0"})
+ params.Meta.SetClientCapabilities(mcp.ClientCapabilities{})
+ headers = make(http.Header)
+ for name, value := range mcp.StandardHeaders(version, mcp.MethodToolsList, nil) {
+ headers.Set(name, value)
+ }
+ }
response, err := c.client.GetTransport().SendRequest(ctx, transport.JSONRPCRequest{
JSONRPC: mcp.JSONRPC_VERSION,
ID: mcp.NewRequestId("weknora-tools-" + uuid.NewString()),
Method: "tools/list",
- Params: struct {
- Cursor string `json:"cursor,omitempty"`
- }{cursor},
+ Params: params,
+ Header: headers,
})
if err != nil {
return nil, transport.NewError(err)
@@ -606,6 +757,36 @@ func (c *mcpGoClient) CallTool(ctx context.Context, name string, args map[string
Arguments: args,
},
}
+ if mcp.IsModernProtocol(c.client.ProtocolVersion()) {
+ c.metadataMu.RLock()
+ schema, cached := c.toolSchemas[name]
+ c.metadataMu.RUnlock()
+ if !cached {
+ // Agent discovery may use a persisted directory or a different
+ // connection. Reconnects also start with no header annotations.
+ // Load the complete, bounded directory on this authenticated client
+ // before executing; never send a call with incomplete metadata.
+ if _, err := c.ListTools(ctx); err != nil {
+ return nil, fmt.Errorf("failed to load schema for tool %q: %w", name, err)
+ }
+ c.metadataMu.RLock()
+ schema, cached = c.toolSchemas[name]
+ c.metadataMu.RUnlock()
+ if !cached {
+ return nil, fmt.Errorf("tool %q not found in MCP directory", name)
+ }
+ }
+ // Raw directory reads bypass the SDK's tool cache. Reuse its annotation
+ // helper so modern gateways receive the same parameter headers.
+ params, err := json.Marshal(req.Params)
+ if err != nil {
+ return nil, fmt.Errorf("failed to encode tool arguments: %w", err)
+ }
+ req.Header = make(http.Header)
+ for key, value := range mcp.GenerateParamHeaders(&mcp.Tool{Name: name, RawInputSchema: schema}, params) {
+ req.Header.Set(key, value)
+ }
+ }
result, err := oauthCall(ctx, c, func() (*mcp.CallToolResult, error) {
return c.client.CallTool(ctx, req)
diff --git a/internal/mcp/client_param_headers_test.go b/internal/mcp/client_param_headers_test.go
new file mode 100644
index 000000000..6afd75ef8
--- /dev/null
+++ b/internal/mcp/client_param_headers_test.go
@@ -0,0 +1,222 @@
+package mcp
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/utils"
+ sdk "github.com/mark3labs/mcp-go/mcp"
+ "github.com/mark3labs/mcp-go/server"
+ "github.com/stretchr/testify/require"
+)
+
+// Directory refreshes use a temporary client, while Agent calls may only have
+// the persisted tool definition. Neither that refresh nor a retired connection
+// can populate the schema cache of the connection that actually calls the tool.
+func TestCallToolParamHeadersWithoutConnectionDiscovery(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ for _, mode := range []string{"modern", "legacy"} {
+ for _, scenario := range []string{"persisted directory", "reconnected"} {
+ t.Run(mode+"/"+scenario, func(t *testing.T) {
+ peer := newParamHeaderPeer(t, mode == "legacy")
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ manager := NewMCPManager(nil)
+ defer manager.CloseAll()
+ var directoryClient MCPClient
+ var err error
+ if scenario == "persisted directory" {
+ directoryClient, err = NewMCPClient(&ClientConfig{Service: peer.service})
+ require.NoError(t, err)
+ require.NoError(t, directoryClient.Connect(ctx))
+ _, err = directoryClient.Initialize(ctx)
+ } else {
+ directoryClient, err = manager.GetOrCreateClient(ctx, peer.service)
+ }
+ require.NoError(t, err)
+ tools, err := directoryClient.ListTools(ctx)
+ require.NoError(t, err)
+ require.Len(t, tools, 2)
+ require.Equal(t, "echo", tools[1].Name)
+ if scenario == "persisted directory" {
+ require.NoError(t, directoryClient.Disconnect())
+ } else {
+ require.NoError(t, manager.CloseClient(peer.service.ID))
+ }
+
+ c, err := manager.GetOrCreateClient(ctx, peer.service)
+ require.NoError(t, err)
+ beforeLists, _ := peer.counts()
+ for _, value := range []string{"first", "second"} {
+ // Use the saved definition without listing tools on this client.
+ result, err := c.CallTool(ctx, tools[1].Name, map[string]interface{}{"value": value})
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+ require.Equal(t, "ok", result.Content[0].Text)
+ }
+ afterLists, headers := peer.counts()
+ if mode == "modern" {
+ require.Equal(t, []string{"first", "second"}, headers)
+ // Two tools plus the empty terminal page. A second call must
+ // reuse the complete cache instead of listing again.
+ require.Equal(t, 3, afterLists-beforeLists)
+ } else {
+ require.Equal(t, []string{"", ""}, headers)
+ require.Equal(t, beforeLists, afterLists, "legacy calls need no header discovery")
+ }
+ })
+ }
+ }
+}
+
+func TestCallToolParamHeadersDiscoveryFailure(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ peer := newParamHeaderPeer(t, false)
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ manager := NewMCPManager(nil)
+ defer manager.CloseAll()
+ c, err := manager.GetOrCreateClient(ctx, peer.service)
+ require.NoError(t, err)
+ peer.mu.Lock()
+ peer.failPage = true
+ peer.mu.Unlock()
+ _, err = c.CallTool(ctx, "echo", map[string]interface{}{"value": "first"})
+ require.ErrorContains(t, err, "directory unavailable")
+ lists, headers := peer.counts()
+ require.Equal(t, 2, lists)
+ require.Empty(t, headers, "do not execute with missing or partial call metadata")
+ rawClient := c.(*managedMCPClient).MCPClient.(*mcpGoClient)
+ rawClient.metadataMu.RLock()
+ emptyCache := len(rawClient.toolSchemas) == 0
+ rawClient.metadataMu.RUnlock()
+ require.True(t, emptyCache, "a failed paginated discovery must not cache its first page")
+
+ peer.mu.Lock()
+ peer.failPage = false
+ peer.mu.Unlock()
+ result, err := c.CallTool(ctx, "echo", map[string]interface{}{"value": "retry"})
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+ lists, headers = peer.counts()
+ require.Equal(t, 5, lists)
+ require.Equal(t, []string{"retry"}, headers)
+}
+
+func TestCallToolParamHeadersDiscoveryStopsBeforeExecution(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ for _, scenario := range []string{"cancelled", "missing tool"} {
+ t.Run(scenario, func(t *testing.T) {
+ peer := newParamHeaderPeer(t, false)
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ manager := NewMCPManager(nil)
+ defer manager.CloseAll()
+ c, err := manager.GetOrCreateClient(ctx, peer.service)
+ require.NoError(t, err)
+ name := "missing"
+ if scenario == "cancelled" {
+ name = "echo"
+ cancel()
+ }
+ _, err = c.CallTool(ctx, name, map[string]interface{}{"value": "unused"})
+ lists, headers := peer.counts()
+ if scenario == "cancelled" {
+ require.ErrorIs(t, err, context.Canceled)
+ require.Zero(t, lists)
+ } else {
+ require.ErrorContains(t, err, `tool "missing" not found`)
+ require.Equal(t, 3, lists)
+ }
+ require.Empty(t, headers, "do not execute without a resolved schema")
+ })
+ }
+}
+
+type paramHeaderPeer struct {
+ service *types.MCPService
+ mu sync.Mutex
+ lists int
+ headers []string
+ failPage bool
+}
+
+func (p *paramHeaderPeer) counts() (int, []string) {
+ p.mu.Lock()
+ defer p.mu.Unlock()
+ return p.lists, append([]string(nil), p.headers...)
+}
+
+func newParamHeaderPeer(t *testing.T, legacy bool) *paramHeaderPeer {
+ t.Helper()
+ p := &paramHeaderPeer{}
+ s := server.NewMCPServer("param-headers", "1", server.WithPaginationLimit(1))
+ for _, name := range []string{"alpha", "echo"} {
+ s.AddTool(sdk.Tool{Name: name, RawInputSchema: json.RawMessage(`{
+ "type":"object","properties":{"value":{"type":"string","x-mcp-header":"Value"}}
+ }`)}, func(context.Context, sdk.CallToolRequest) (*sdk.CallToolResult, error) {
+ return sdk.NewToolResultText("ok"), nil
+ })
+ }
+ handler := server.NewStreamableHTTPServer(s, server.WithStateLess(true))
+ httpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method == http.MethodPost {
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ t.Error(err)
+ return
+ }
+ r.Body = io.NopCloser(bytes.NewReader(body))
+ var request struct {
+ ID json.RawMessage `json:"id"`
+ Method string `json:"method"`
+ Params struct {
+ Cursor string `json:"cursor"`
+ } `json:"params"`
+ }
+ if err := json.Unmarshal(body, &request); err != nil {
+ t.Error(err)
+ return
+ }
+ p.mu.Lock()
+ if request.Method == "tools/list" {
+ p.lists++
+ }
+ if request.Method == "tools/call" {
+ p.headers = append(p.headers, r.Header.Get("Mcp-Param-Value"))
+ }
+ failPage := p.failPage && request.Method == "tools/list" && request.Params.Cursor != ""
+ p.mu.Unlock()
+ if (legacy && request.Method == "server/discover") || failPage {
+ code, message := -32601, "Method not found"
+ if failPage {
+ code, message = -32603, "directory unavailable"
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "jsonrpc": "2.0", "id": request.ID,
+ "error": map[string]any{"code": code, "message": message},
+ })
+ return
+ }
+ }
+ handler.ServeHTTP(w, r)
+ }))
+ t.Cleanup(httpServer.Close)
+ p.service = &types.MCPService{
+ ID: "param-headers", Name: "param-headers", Enabled: true,
+ URL: &httpServer.URL, TransportType: types.MCPTransportHTTPStreamable,
+ }
+ return p
+}
diff --git a/internal/mcp/client_protocol_test.go b/internal/mcp/client_protocol_test.go
new file mode 100644
index 000000000..8436f993d
--- /dev/null
+++ b/internal/mcp/client_protocol_test.go
@@ -0,0 +1,681 @@
+package mcp
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/utils"
+ "github.com/mark3labs/mcp-go/client/transport"
+ sdk "github.com/mark3labs/mcp-go/mcp"
+ "github.com/mark3labs/mcp-go/server"
+ "github.com/stretchr/testify/require"
+)
+
+type protocolTestTransport struct {
+ transport.HTTPConnection
+ send func(context.Context, transport.JSONRPCRequest) (*transport.JSONRPCResponse, error)
+}
+
+func (t *protocolTestTransport) SendRequest(
+ ctx context.Context, request transport.JSONRPCRequest,
+) (*transport.JSONRPCResponse, error) {
+ return t.send(ctx, request)
+}
+
+func (*protocolTestTransport) Start(context.Context) error { return nil }
+func (*protocolTestTransport) Close() error { return nil }
+func (*protocolTestTransport) SetProtocolVersion(string) {}
+func (*protocolTestTransport) SetNotificationHandler(func(sdk.JSONRPCNotification)) {}
+func (*protocolTestTransport) SendNotification(context.Context, sdk.JSONRPCNotification) error {
+ return nil
+}
+
+type protocolTestSend func(context.Context, transport.JSONRPCRequest) (*transport.JSONRPCResponse, error)
+
+func newProtocolTestClient(t *testing.T, timeout int, send protocolTestSend) *mcpGoClient {
+ t.Helper()
+ return newProtocolProbeTestClient(t, timeout, send, send)
+}
+
+// The live connection and the independent re-probe connection get separate
+// mock transports so tests can tell which one a request used.
+func newProtocolProbeTestClient(t *testing.T, timeout int, live, probe protocolTestSend) *mcpGoClient {
+ t.Helper()
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ url := "http://127.0.0.1/mcp"
+ c, err := NewMCPClient(&ClientConfig{Service: &types.MCPService{
+ ID: "peer", Name: "peer", URL: &url, TransportType: types.MCPTransportHTTPStreamable,
+ AdvancedConfig: &types.MCPAdvancedConfig{Timeout: timeout},
+ }})
+ require.NoError(t, err)
+ wrapped := c.(*mcpGoClient)
+ wrapped.discovery.HTTPConnection = &protocolTestTransport{send: live}
+ newProbe := wrapped.newProbe
+ wrapped.newProbe = func() (*mcpGoClient, error) {
+ p, err := newProbe()
+ if err != nil {
+ return nil, err
+ }
+ p.discovery.HTTPConnection = &protocolTestTransport{send: probe}
+ return p, nil
+ }
+ require.NoError(t, c.Connect(context.Background()))
+ t.Cleanup(func() { require.NoError(t, c.Disconnect()) })
+ return wrapped
+}
+
+func TestProtocolDiscoveryRetry(t *testing.T) {
+ for _, mode := range []string{
+ "method-not-found", "transient-unavailable", "transient-unauthorized", "transient-timeout",
+ "silent-legacy", "unavailable", "cancelled", "cancelled-after-handshake",
+ } {
+ t.Run(mode, func(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+ discoverCount, liveDiscovers, liveInitializes, probeInitializes := 0, 0, 0, 0
+ peer := func(probe bool) protocolTestSend {
+ return func(ctx context.Context, request transport.JSONRPCRequest) (*transport.JSONRPCResponse, error) {
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+ if !probe {
+ switch request.Method {
+ case "server/discover":
+ liveDiscovers++
+ case "initialize":
+ liveInitializes++
+ }
+ } else if request.Method == "initialize" {
+ probeInitializes++
+ }
+ return protocolRetryPeer(t, mode, &discoverCount, cancel)(ctx, request)
+ }
+ }
+ c := newProtocolProbeTestClient(t, 1, peer(false), peer(true))
+ result, err := c.Initialize(ctx)
+ if mode == "cancelled" || mode == "cancelled-after-handshake" || mode == "unavailable" {
+ require.Error(t, err)
+ require.Nil(t, result)
+ require.False(t, c.initialized.Load())
+ require.Equal(t, 1, discoverCount)
+ if mode != "unavailable" {
+ require.ErrorIs(t, err, context.Canceled)
+ }
+ return
+ }
+ require.NoError(t, err)
+ wantVersion := sdk.LATEST_PROTOCOL_VERSION
+ if mode == "silent-legacy" || mode == "method-not-found" {
+ wantVersion = sdk.LATEST_LEGACY_PROTOCOL_VERSION
+ }
+ require.Equal(t, wantVersion, result.ProtocolVersion)
+ require.Equal(t, wantVersion, c.client.ProtocolVersion())
+ if mode == "method-not-found" {
+ require.Equal(t, 1, discoverCount)
+ } else {
+ require.Equal(t, 2, discoverCount)
+ }
+ require.Equal(t, 1, liveDiscovers, "the live session must never be probed again")
+ require.Equal(t, 1, liveInitializes, "the live session must never be re-initialized")
+ require.Zero(t, probeInitializes, "the probe must not open a second legacy session")
+ _, err = c.ListTools(ctx)
+ require.NoError(t, err)
+ call, err := c.CallTool(ctx, "echo", map[string]interface{}{"x": "value"})
+ require.NoError(t, err)
+ require.Equal(t, "ok", call.Content[0].Text)
+ })
+ }
+}
+
+func protocolRetryPeer(t *testing.T, mode string, discoverCount *int, cancel context.CancelFunc) protocolTestSend {
+ return func(ctx context.Context, request transport.JSONRPCRequest) (*transport.JSONRPCResponse, error) {
+ result := func(raw string) (*transport.JSONRPCResponse, error) {
+ return &transport.JSONRPCResponse{Result: json.RawMessage(raw)}, nil
+ }
+ switch request.Method {
+ case "server/discover":
+ *discoverCount++
+ discoverCount := *discoverCount
+ if mode == "method-not-found" {
+ return &transport.JSONRPCResponse{Error: &sdk.JSONRPCErrorDetails{
+ Code: -32601, Message: "Method not found",
+ }}, nil
+ }
+ if mode == "silent-legacy" || (mode == "transient-timeout" && discoverCount == 1) {
+ <-ctx.Done()
+ return nil, ctx.Err()
+ }
+ if mode == "cancelled" {
+ cancel()
+ return nil, ctx.Err()
+ }
+ if discoverCount == 1 || mode == "unavailable" {
+ if mode == "transient-unauthorized" {
+ return nil, &transport.AuthorizationRequiredError{}
+ }
+ return nil, errors.New("request failed with status 503")
+ }
+ return result(`{"capabilities":{"tools":{}},"protocolVersions":["2026-07-28"]}`)
+ case "initialize":
+ if mode == "unavailable" {
+ return nil, errors.New("request failed with status 503")
+ }
+ if mode == "cancelled-after-handshake" {
+ cancel()
+ }
+ return result(`{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},` +
+ `"serverInfo":{"name":"peer","version":"1"}}`)
+ case "tools/list":
+ return result(`{"tools":[{"name":"echo","inputSchema":{"type":"object",` +
+ `"properties":{"x":{"type":"string","x-mcp-header":"Value"}}}}]}`)
+ case "tools/call":
+ wantHeader := "value"
+ if mode == "silent-legacy" || mode == "method-not-found" {
+ wantHeader = ""
+ }
+ require.Equal(t, wantHeader, request.Header.Get("Mcp-Param-Value"))
+ return result(`{"content":[{"type":"text","text":"ok"}]}`)
+ default:
+ t.Fatalf("unexpected method %s", request.Method)
+ return nil, nil
+ }
+ }
+}
+
+func TestProtocolDiscoveryRetryKeepsLegacySuccess(t *testing.T) {
+ for _, mode := range []string{"retry-unavailable", "retry-cancelled", "retry-skipped"} {
+ t.Run(mode, func(t *testing.T) {
+ timeout := time.Second
+ if mode == "retry-skipped" {
+ // Leaves less than one 250ms probe after the first handshake.
+ timeout = 500 * time.Millisecond
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), timeout)
+ defer cancel()
+ discoverCount, initializeCount, probeDiscovers, probeInitializes, liveLists := 0, 0, 0, 0, 0
+ probe := func(ctx context.Context, request transport.JSONRPCRequest) (*transport.JSONRPCResponse, error) {
+ switch request.Method {
+ case "server/discover":
+ discoverCount++
+ probeDiscovers++
+ if mode == "retry-cancelled" {
+ cancel()
+ return nil, ctx.Err()
+ }
+ // A stateful legacy peer rejects a sessionless request.
+ return nil, transport.ErrSessionTerminated
+ case "initialize":
+ probeInitializes++
+ return nil, errors.New("request failed with status 503")
+ default:
+ t.Fatalf("unexpected probe method %s", request.Method)
+ return nil, nil
+ }
+ }
+ c := newProtocolProbeTestClient(t, 1, func(
+ ctx context.Context, request transport.JSONRPCRequest,
+ ) (*transport.JSONRPCResponse, error) {
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+ switch request.Method {
+ case "server/discover":
+ discoverCount++
+ return nil, errors.New("request failed with status 503")
+ case "initialize":
+ initializeCount++
+ if initializeCount > 1 {
+ return nil, errors.New("request failed with status 503")
+ }
+ if mode == "retry-skipped" {
+ select {
+ case <-time.After(300 * time.Millisecond):
+ case <-ctx.Done():
+ return nil, ctx.Err()
+ }
+ }
+ return &transport.JSONRPCResponse{Result: json.RawMessage(
+ `{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},` +
+ `"serverInfo":{"name":"peer","version":"1"}}`,
+ )}, nil
+ case "tools/list":
+ liveLists++
+ return &transport.JSONRPCResponse{Result: json.RawMessage(
+ `{"tools":[{"name":"echo","inputSchema":{"type":"object"}}]}`,
+ )}, nil
+ default:
+ t.Fatalf("unexpected method %s", request.Method)
+ return nil, nil
+ }
+ }, probe)
+ result, err := c.Initialize(ctx)
+ require.NoError(t, err)
+ require.NotNil(t, result)
+ require.Equal(t, sdk.LATEST_LEGACY_PROTOCOL_VERSION, result.ProtocolVersion)
+ require.Equal(t, sdk.LATEST_LEGACY_PROTOCOL_VERSION, c.client.ProtocolVersion())
+ require.True(t, c.initialized.Load())
+ require.Equal(t, 1, initializeCount, "the live session must never be re-initialized")
+ require.Zero(t, probeInitializes, "the probe must not open a second legacy session")
+ if mode == "retry-skipped" {
+ require.Equal(t, 1, discoverCount)
+ require.Zero(t, probeDiscovers)
+ } else {
+ require.Equal(t, 2, discoverCount)
+ require.Equal(t, 1, probeDiscovers)
+ }
+ tools, err := c.ListTools(context.Background())
+ require.NoError(t, err)
+ require.Len(t, tools, 1)
+ require.Equal(t, 1, liveLists, "the original connection keeps serving requests")
+ })
+ }
+}
+
+// statefulLegacyPeer behaves like a session-managed legacy Streamable HTTP
+// server: every non-initialize request without its session gets a 404, which
+// mcp-go reports as session termination and answers by clearing its session.
+type statefulLegacyPeer struct {
+ modernRetry bool
+ mu sync.Mutex
+ discovers int
+ initializes int
+ lists int
+ deleted []string
+}
+
+func (p *statefulLegacyPeer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ session := r.Header.Get("Mcp-Session-Id")
+ if r.Method == http.MethodDelete {
+ p.mu.Lock()
+ p.deleted = append(p.deleted, session)
+ p.mu.Unlock()
+ return
+ }
+ if r.Method != http.MethodPost {
+ w.WriteHeader(http.StatusMethodNotAllowed)
+ return
+ }
+ var request struct {
+ ID json.RawMessage `json:"id"`
+ Method string `json:"method"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+ w.WriteHeader(http.StatusBadRequest)
+ return
+ }
+ reply := func(result string) {
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "jsonrpc": "2.0", "id": request.ID, "result": json.RawMessage(result),
+ })
+ }
+ modern := r.Header.Get("Mcp-Protocol-Version") == sdk.LATEST_PROTOCOL_VERSION
+ p.mu.Lock()
+ defer p.mu.Unlock()
+ switch {
+ case request.Method == "server/discover":
+ p.discovers++
+ switch {
+ case p.discovers == 1:
+ w.WriteHeader(http.StatusServiceUnavailable)
+ case p.modernRetry:
+ reply(`{"capabilities":{"tools":{}},"protocolVersions":["2026-07-28"]}`)
+ case session == "":
+ w.WriteHeader(http.StatusNotFound)
+ default:
+ w.WriteHeader(http.StatusBadRequest)
+ }
+ case request.Method == "initialize":
+ p.initializes++
+ if p.initializes > 1 {
+ w.WriteHeader(http.StatusServiceUnavailable)
+ return
+ }
+ w.Header().Set("Mcp-Session-Id", "sess-1")
+ reply(`{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},` +
+ `"serverInfo":{"name":"stateful","version":"1"}}`)
+ case !modern && session != "sess-1":
+ w.WriteHeader(http.StatusNotFound)
+ case request.ID == nil:
+ w.WriteHeader(http.StatusAccepted)
+ case request.Method == "tools/list":
+ p.lists++
+ reply(`{"tools":[{"name":"echo","inputSchema":{"type":"object"}}]}`)
+ default:
+ w.WriteHeader(http.StatusBadRequest)
+ }
+}
+
+func TestProtocolDiscoveryRetryKeepsStatefulLegacySession(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ for _, mode := range []string{"probe-legacy", "probe-modern"} {
+ t.Run(mode, func(t *testing.T) {
+ peer := &statefulLegacyPeer{modernRetry: mode == "probe-modern"}
+ httpServer := httptest.NewServer(peer)
+ defer httpServer.Close()
+ c, err := NewMCPClient(&ClientConfig{Service: &types.MCPService{
+ ID: "stateful", Name: "stateful", URL: &httpServer.URL,
+ TransportType: types.MCPTransportHTTPStreamable,
+ AdvancedConfig: &types.MCPAdvancedConfig{Timeout: 3},
+ }})
+ require.NoError(t, err)
+ wrapped := c.(*mcpGoClient)
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+ require.NoError(t, c.Connect(ctx))
+ result, err := c.Initialize(ctx)
+ require.NoError(t, err)
+ wantVersion := sdk.LATEST_LEGACY_PROTOCOL_VERSION
+ if mode == "probe-modern" {
+ wantVersion = sdk.LATEST_PROTOCOL_VERSION
+ }
+ require.Equal(t, wantVersion, result.ProtocolVersion)
+ require.Equal(t, wantVersion, wrapped.client.ProtocolVersion())
+ if mode == "probe-legacy" {
+ require.Equal(t, "sess-1", wrapped.client.GetSessionId(), "the probe must not clear the live session")
+ }
+ tools, err := c.ListTools(ctx)
+ require.NoError(t, err)
+ require.Len(t, tools, 1)
+ require.NoError(t, c.Disconnect())
+ peer.mu.Lock()
+ defer peer.mu.Unlock()
+ require.Equal(t, 2, peer.discovers)
+ require.Equal(t, 1, peer.initializes, "neither connection may initialize again")
+ require.Equal(t, 1, peer.lists)
+ require.Equal(t, []string{"sess-1"}, peer.deleted, "the legacy session is closed exactly once")
+ })
+ }
+}
+
+func TestOutboundProtocolNegotiation(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ for _, mode := range []string{
+ "modern", "legacy", "silent-legacy", "transient-unavailable", "transient-unauthorized",
+ "transient-timeout", "unauthorized", "unavailable", "cancelled",
+ } {
+ t.Run(mode, func(t *testing.T) {
+ wantModern := mode == "modern" || mode == "transient-unavailable" ||
+ mode == "transient-unauthorized" || mode == "transient-timeout"
+ s := server.NewMCPServer("peer", "1", server.WithPaginationLimit(1))
+ schema := json.RawMessage(`{
+ "type":"object", "oneOf":[{"required":["x"]},{"required":["y"]}],
+ "definitions":{"value":{"type":"string"}},
+ "properties":{"x":{"type":"string","x-mcp-header":"Value"},
+ "y":{"$ref":"#/definitions/value"}}
+ }`)
+ for _, name := range []string{"first", "second"} {
+ s.AddTool(sdk.Tool{Name: name, RawInputSchema: schema},
+ func(context.Context, sdk.CallToolRequest) (*sdk.CallToolResult, error) {
+ return sdk.NewToolResultText("ok"), nil
+ })
+ }
+ handler := server.NewStreamableHTTPServer(s, server.WithStateLess(true))
+ var mu sync.Mutex
+ var methods []string
+ discoverCount := 0
+ httpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ handler.ServeHTTP(w, r)
+ return
+ }
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ return
+ }
+ r.Body = io.NopCloser(bytes.NewReader(body))
+ var request struct {
+ ID json.RawMessage `json:"id"`
+ Method string `json:"method"`
+ }
+ if json.Unmarshal(body, &request) != nil {
+ t.Error("invalid JSON request")
+ return
+ }
+ mu.Lock()
+ methods = append(methods, request.Method)
+ if request.Method == "server/discover" {
+ discoverCount++
+ }
+ probe := discoverCount
+ mu.Unlock()
+ if r.Header.Get("Authorization") != "Bearer fixture" {
+ t.Error("missing bearer")
+ }
+ if request.Method == "tools/call" {
+ if wantModern {
+ if got := r.Header.Get("Mcp-Param-Value"); got != "value" {
+ t.Errorf("Mcp-Param-Value = %q, want value", got)
+ }
+ } else {
+ if got := r.Header.Get("Mcp-Param-Value"); got != "" {
+ t.Errorf("legacy call added Mcp-Param-Value = %q", got)
+ }
+ }
+ }
+ if mode == "unauthorized" {
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ }
+ if mode == "unavailable" {
+ http.Error(w, "unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ if request.Method == "server/discover" {
+ if probe == 1 {
+ switch mode {
+ case "transient-unavailable":
+ http.Error(w, "unavailable", http.StatusServiceUnavailable)
+ return
+ case "transient-unauthorized":
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ case "transient-timeout":
+ <-r.Context().Done()
+ return
+ }
+ }
+ switch mode {
+ case "silent-legacy", "cancelled":
+ <-r.Context().Done()
+ return
+ case "legacy":
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "jsonrpc": "2.0", "id": request.ID,
+ "error": map[string]any{"code": -32601, "message": "Method not found"},
+ })
+ return
+ }
+ }
+ handler.ServeHTTP(w, r)
+ }))
+ defer httpServer.Close()
+ c, err := NewMCPClient(&ClientConfig{Service: &types.MCPService{
+ ID: "peer", Name: "peer", URL: &httpServer.URL, TransportType: types.MCPTransportHTTPStreamable,
+ AuthConfig: &types.MCPAuthConfig{AuthType: types.MCPAuthBearer, Token: "fixture"},
+ AdvancedConfig: &types.MCPAdvancedConfig{Timeout: 3},
+ }})
+ require.NoError(t, err)
+ defer func() { require.NoError(t, c.Disconnect()) }()
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+ require.NoError(t, c.Connect(ctx))
+ if mode == "cancelled" {
+ var stop context.CancelFunc
+ ctx, stop = context.WithTimeout(ctx, 100*time.Millisecond)
+ defer stop()
+ }
+ result, err := c.Initialize(ctx)
+ if mode == "unauthorized" || mode == "unavailable" || mode == "cancelled" {
+ require.Error(t, err)
+ require.Nil(t, result)
+ require.False(t, c.(*mcpGoClient).initialized.Load())
+ if mode == "cancelled" {
+ require.ErrorIs(t, err, context.DeadlineExceeded)
+ }
+ mu.Lock()
+ defer mu.Unlock()
+ if mode != "cancelled" {
+ require.Equal(t, []string{"server/discover", "initialize"}, methods)
+ }
+ return
+ }
+ require.NoError(t, err)
+ wantVersion := sdk.LATEST_LEGACY_PROTOCOL_VERSION
+ if wantModern {
+ wantVersion = sdk.LATEST_PROTOCOL_VERSION
+ }
+ require.Equal(t, wantVersion, result.ProtocolVersion)
+ require.Equal(t, wantVersion, c.(*mcpGoClient).client.ProtocolVersion())
+ tools, err := c.ListTools(ctx)
+ require.NoError(t, err)
+ require.Len(t, tools, 2)
+ for _, tool := range tools {
+ require.JSONEq(t, string(schema), string(tool.InputSchema))
+ }
+ mu.Lock()
+ listCount := 0
+ for _, method := range methods {
+ if method == "tools/list" {
+ listCount++
+ }
+ }
+ mu.Unlock()
+ // The SDK emits a cursor for a full page, including the last one;
+ // the third request reads the empty terminal page.
+ require.Equal(t, 3, listCount, "all raw directory pages use the negotiated protocol")
+ call, err := c.CallTool(ctx, "first", map[string]interface{}{"x": "value"})
+ require.NoError(t, err)
+ require.False(t, call.IsError)
+ require.Equal(t, "ok", call.Content[0].Text)
+ mu.Lock()
+ defer mu.Unlock()
+ require.Equal(t, "server/discover", methods[0])
+ if mode == "modern" {
+ require.NotContains(t, methods, "initialize")
+ require.Equal(t, 1, discoverCount)
+ } else {
+ require.Contains(t, methods, "initialize")
+ if mode == "legacy" {
+ require.Equal(t, 1, discoverCount, "method-not-found must fall back without retry")
+ } else {
+ require.Equal(t, 2, discoverCount, "transport failure gets exactly one retry")
+ }
+ }
+ })
+ }
+}
+
+func TestOutboundSSEProtocolNegotiation(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ for _, mode := range []string{
+ "modern", "transient-unavailable", "transient-unauthorized", "transient-timeout", "silent-legacy",
+ } {
+ t.Run(mode, func(t *testing.T) {
+ s := server.NewMCPServer("sse-peer", "1")
+ s.AddTool(sdk.Tool{Name: "echo", RawInputSchema: json.RawMessage(`{
+ "type":"object","properties":{"x":{"type":"string","x-mcp-header":"Value"}}
+ }`)}, func(context.Context, sdk.CallToolRequest) (*sdk.CallToolResult, error) {
+ return sdk.NewToolResultText("ok"), nil
+ })
+ sse := server.NewSSEServer(s)
+ var mu sync.Mutex
+ discoverCount, initializeCount := 0, 0
+ httpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method == http.MethodPost {
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ return
+ }
+ r.Body = io.NopCloser(bytes.NewReader(body))
+ var request struct {
+ Method string `json:"method"`
+ }
+ if json.Unmarshal(body, &request) != nil {
+ t.Error("invalid JSON request")
+ return
+ }
+ mu.Lock()
+ if request.Method == "server/discover" {
+ discoverCount++
+ }
+ if request.Method == "initialize" {
+ initializeCount++
+ }
+ probe := discoverCount
+ mu.Unlock()
+ if request.Method == "server/discover" {
+ if mode == "silent-legacy" || (mode == "transient-timeout" && probe == 1) {
+ <-r.Context().Done()
+ return
+ }
+ if probe == 1 && mode == "transient-unavailable" {
+ http.Error(w, "unavailable", http.StatusServiceUnavailable)
+ return
+ }
+ if probe == 1 && mode == "transient-unauthorized" {
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ }
+ }
+ if request.Method == "tools/call" && mode != "silent-legacy" &&
+ r.Header.Get("Mcp-Param-Value") != "value" {
+ t.Error("modern SSE call missing Mcp-Param-Value")
+ }
+ }
+ sse.ServeHTTP(w, r)
+ }))
+ defer httpServer.Close()
+ url := httpServer.URL + "/sse"
+ c, err := NewMCPClient(&ClientConfig{Service: &types.MCPService{
+ ID: "sse", Name: "sse", URL: &url, TransportType: types.MCPTransportSSE,
+ AdvancedConfig: &types.MCPAdvancedConfig{Timeout: 3},
+ }})
+ require.NoError(t, err)
+ defer func() { require.NoError(t, c.Disconnect()) }()
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+ require.NoError(t, c.Connect(ctx))
+ result, err := c.Initialize(ctx)
+ require.NoError(t, err)
+ wantVersion := sdk.LATEST_PROTOCOL_VERSION
+ if mode == "silent-legacy" {
+ wantVersion = sdk.LATEST_LEGACY_PROTOCOL_VERSION
+ }
+ require.Equal(t, wantVersion, result.ProtocolVersion)
+ require.Equal(t, wantVersion, c.(*mcpGoClient).client.ProtocolVersion())
+ tools, err := c.ListTools(ctx)
+ require.NoError(t, err)
+ require.Len(t, tools, 1)
+ call, err := c.CallTool(ctx, "echo", map[string]interface{}{"x": "value"})
+ require.NoError(t, err)
+ require.False(t, call.IsError)
+ require.Equal(t, "ok", call.Content[0].Text)
+ mu.Lock()
+ defer mu.Unlock()
+ switch mode {
+ case "modern":
+ require.Equal(t, 1, discoverCount)
+ require.Zero(t, initializeCount)
+ default:
+ // The re-probe uses its own SSE session and never initializes it.
+ require.Equal(t, 2, discoverCount)
+ require.Equal(t, 1, initializeCount)
+ }
+ })
+ }
+}
diff --git a/internal/mcp/client_session_test.go b/internal/mcp/client_session_test.go
index fbca0a9cc..b3c29c786 100644
--- a/internal/mcp/client_session_test.go
+++ b/internal/mcp/client_session_test.go
@@ -3,6 +3,8 @@ package mcp
import (
"context"
"encoding/json"
+ "errors"
+ "fmt"
"io"
"net/http"
"net/http/httptest"
@@ -11,9 +13,65 @@ import (
"github.com/Tencent/WeKnora/internal/types"
secutils "github.com/Tencent/WeKnora/internal/utils"
+ "github.com/mark3labs/mcp-go/client/transport"
+ sdk "github.com/mark3labs/mcp-go/mcp"
"github.com/stretchr/testify/require"
)
+func TestMCPClientProtocolSessionErrors(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ err error
+ wantConnected bool
+ legacy bool
+ }{
+ {"method-not-found", transport.ErrSessionTerminated, true, false},
+ {"wrapped-method-not-found", fmt.Errorf("request: %w", transport.ErrSessionTerminated), true, false},
+ {"expired-session", errors.New("request failed with status 400: Invalid session ID"), false, false},
+ {"missing-connection", errors.New("No active connection"), false, false},
+ {"legacy-session-gone", transport.ErrSessionTerminated, false, true},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ c := newProtocolTestClient(t, 3, func(
+ _ context.Context, request transport.JSONRPCRequest,
+ ) (*transport.JSONRPCResponse, error) {
+ if test.legacy {
+ if request.Method == "server/discover" {
+ return &transport.JSONRPCResponse{Error: &sdk.JSONRPCErrorDetails{
+ Code: -32601, Message: "Method not found",
+ }}, nil
+ }
+ require.Equal(t, "initialize", request.Method)
+ return &transport.JSONRPCResponse{Result: json.RawMessage(
+ `{"protocolVersion":"2025-11-25","capabilities":{},` +
+ `"serverInfo":{"name":"peer","version":"1"}}`,
+ )}, nil
+ }
+ require.Equal(t, "server/discover", request.Method)
+ return &transport.JSONRPCResponse{Result: json.RawMessage(
+ `{"capabilities":{},"protocolVersions":["2026-07-28"]}`,
+ )}, nil
+ })
+ result, err := c.Initialize(context.Background())
+ require.NoError(t, err)
+ wantVersion := sdk.LATEST_PROTOCOL_VERSION
+ if test.legacy {
+ wantVersion = sdk.LATEST_LEGACY_PROTOCOL_VERSION
+ }
+ require.Equal(t, wantVersion, result.ProtocolVersion)
+ c.toolSchemas = map[string]json.RawMessage{"echo": json.RawMessage(`{"type":"object"}`)}
+ c.checkErrorAndDisconnectIfNeeded(transport.NewError(test.err))
+ require.Equal(t, test.wantConnected, c.IsConnected())
+ require.Equal(t, test.wantConnected, c.initialized.Load())
+ if test.wantConnected {
+ require.Contains(t, c.toolSchemas, "echo")
+ } else {
+ require.Nil(t, c.toolSchemas)
+ }
+ })
+ }
+}
+
// expiringSessionServer is a Streamable HTTP MCP server on a session-based
// protocol version that forgets the session after initialization: the next
// request gets a 404, as after a server restart.
diff --git a/internal/mcp/client_tools_test.go b/internal/mcp/client_tools_test.go
index f075fd0dd..510ed964a 100644
--- a/internal/mcp/client_tools_test.go
+++ b/internal/mcp/client_tools_test.go
@@ -65,10 +65,13 @@ func TestRawToolsPaginationErrorsAndCancellation(t *testing.T) {
},
}
c := &mcpGoClient{client: client.NewClient(tpt)}
+ c.toolSchemas = map[string]json.RawMessage{"previous": json.RawMessage(`{"type":"object"}`)}
c.initialized.Store(true)
tools, err := c.ListTools(context.Background())
require.Error(t, err)
require.Nil(t, tools, "never publish a partial directory")
+ require.Contains(t, c.toolSchemas, "previous", "a failed refresh keeps the last complete header schema")
+ require.NotContains(t, c.toolSchemas, "first", "partial pages must not become call metadata")
require.Equal(t, 2, calls)
ctx, cancel := context.WithCancel(context.Background())
cancel()
diff --git a/internal/mcp/manager.go b/internal/mcp/manager.go
index 5d1e1fdcc..d0af134ea 100644
--- a/internal/mcp/manager.go
+++ b/internal/mcp/manager.go
@@ -245,6 +245,32 @@ func (m *MCPManager) CloseClient(serviceID string) error {
return nil
}
+// InvalidateToolSchemas drops the header-schema caches of every cached
+// connection for a service after listedBy completed a newer directory read.
+// Connections stay open; their next modern CallTool reloads the directory.
+// listedBy's own cache is current and is kept.
+func (m *MCPManager) InvalidateToolSchemas(serviceID string, listedBy MCPClient) {
+ m.clientsMu.RLock()
+ defer m.clientsMu.RUnlock()
+ for key, client := range m.clients {
+ if key != serviceID && !strings.HasPrefix(key, serviceID+"\x00") {
+ continue
+ }
+ if client == listedBy {
+ continue
+ }
+ if managed, ok := client.(*managedMCPClient); ok {
+ if managed.MCPClient == listedBy {
+ continue
+ }
+ client = managed.MCPClient
+ }
+ if cached, ok := client.(interface{ invalidateToolSchemas() }); ok {
+ cached.invalidateToolSchemas()
+ }
+ }
+}
+
// closeAllTimeout bounds CloseAll. Disconnecting a remote transport can mean
// a request to the server, and one that stopped answering must not hold up
// process exit.
diff --git a/internal/mcp/manager_startup_test.go b/internal/mcp/manager_startup_test.go
index 6bd1df912..97306f80d 100644
--- a/internal/mcp/manager_startup_test.go
+++ b/internal/mcp/manager_startup_test.go
@@ -33,7 +33,7 @@ func TestManagerConcurrentStartupCancellationAndConfigReplacement(t *testing.T)
Method string `json:"method"`
}
_ = json.Unmarshal(body, &request)
- if request.Method == "initialize" {
+ if request.Method == "initialize" || request.Method == "server/discover" {
if r.URL.Path == "/slow" {
slowInitializations.Add(1)
startOnce.Do(func() { close(started) })
diff --git a/internal/mcpserver/server_test.go b/internal/mcpserver/server_test.go
index 86f6f0b70..73545dc6e 100644
--- a/internal/mcpserver/server_test.go
+++ b/internal/mcpserver/server_test.go
@@ -155,14 +155,10 @@ func TestCallHiddenToolIsRefused(t *testing.T) {
"name": types.MCPEndpointToolDeleteDocument,
"arguments": map[string]any{"knowledge_id": "k-1"},
})
- result, _ := resp["result"].(map[string]any)
- if isErr, _ := result["isError"].(bool); !isErr {
- t.Fatalf("expected tool error, got %v", resp)
- }
- content, _ := result["content"].([]any)
- first, _ := content[0].(map[string]any)
- if !strings.Contains(first["text"].(string), "not enabled") {
- t.Fatalf("unexpected error text: %v", first["text"])
+ // Filtered tools are unavailable at SDK dispatch, before a handler runs.
+ err, _ := resp["error"].(map[string]any)
+ if err["code"] != float64(-32602) || resp["result"] != nil {
+ t.Fatalf("expected invalid-params protocol error, got %v", resp)
}
}
diff --git a/internal/router/router.go b/internal/router/router.go
index e346c2673..2d435c6fe 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -127,7 +127,7 @@ func NewRouter(params RouterParams) *gin.Engine {
"X-Embed-Session", "X-External-User-ID", "X-External-User-Token", "X-WeKnora-Desktop-Token",
// Streamable HTTP MCP clients running in a browser send these on
// the /mcp/:endpoint_id surface.
- "MCP-Protocol-Version", "Mcp-Session-Id", "Last-Event-ID",
+ "MCP-Protocol-Version", "Mcp-Method", "Mcp-Name", "Mcp-Session-Id", "Last-Event-ID",
},
ExposeHeaders: []string{"Content-Length", "Access-Control-Allow-Origin", "Mcp-Session-Id"},
AllowCredentials: true,
diff --git a/internal/router/routes_mcp_endpoint_test.go b/internal/router/routes_mcp_endpoint_test.go
index d1eea84d8..db28ba99f 100644
--- a/internal/router/routes_mcp_endpoint_test.go
+++ b/internal/router/routes_mcp_endpoint_test.go
@@ -1,14 +1,273 @@
package router
import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "strings"
"testing"
+ "github.com/Tencent/WeKnora/internal/application/service"
+ "github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/handler"
"github.com/Tencent/WeKnora/internal/mcpserver"
+ "github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/require"
)
+type protocolEndpointService struct{ interfaces.MCPEndpointService }
+
+func (*protocolEndpointService) Authenticate(_ context.Context, id, token string) (*types.MCPEndpoint, error) {
+ if id != "ep-1" || token != "fixture" {
+ return nil, service.ErrMCPEndpointTokenInvalid
+ }
+ return &types.MCPEndpoint{
+ ID: id, TenantID: 1, Enabled: true, RateLimitPerMinute: 100,
+ KnowledgeBaseIDs: types.StringArray{"kb-own"},
+ Tools: types.StringArray{
+ types.MCPEndpointToolListKnowledgeBases, types.MCPEndpointToolSearchKnowledge,
+ types.MCPEndpointToolWikiReadPage,
+ },
+ }, nil
+}
+
+type protocolTenantService struct{ interfaces.TenantService }
+
+func (*protocolTenantService) GetTenantByID(context.Context, uint64) (*types.Tenant, error) {
+ return &types.Tenant{ID: 1, Status: "active"}, nil
+}
+
+type protocolKBService struct {
+ interfaces.KnowledgeBaseService
+}
+
+func (*protocolKBService) GetKnowledgeBaseByIDOnly(_ context.Context, id string) (*types.KnowledgeBase, error) {
+ return &types.KnowledgeBase{
+ ID: id, TenantID: 1, Name: id,
+ IndexingStrategy: types.IndexingStrategy{KeywordEnabled: true, WikiEnabled: true},
+ }, nil
+}
+
+func (*protocolKBService) HybridSearch(ctx context.Context, id string, params types.SearchParams) (
+ []*types.SearchResult, error,
+) {
+ if types.MustTenantIDFromContext(ctx) != 1 || id != "kb-own" ||
+ params.QueryText != "fixture" || len(params.KnowledgeBaseIDs) != 1 || params.KnowledgeBaseIDs[0] != id {
+ return nil, fmt.Errorf("unexpected retrieval scope or query")
+ }
+ return []*types.SearchResult{{
+ ID: "chunk-1", KnowledgeBaseID: id,
+ KnowledgeID: "doc-1", Content: "retrieval fixture body", Score: 1,
+ }}, nil
+}
+
+func (s *protocolKBService) GetKnowledgeBasesByIDsOnly(ctx context.Context, ids []string) (
+ []*types.KnowledgeBase, error,
+) {
+ kbs := make([]*types.KnowledgeBase, 0, len(ids))
+ for _, id := range ids {
+ kb, err := s.GetKnowledgeBaseByIDOnly(ctx, id)
+ if err != nil {
+ return nil, err
+ }
+ kbs = append(kbs, kb)
+ }
+ return kbs, nil
+}
+
+func (*protocolKBService) ResolveEmbeddingModelKeys(context.Context, []*types.KnowledgeBase) map[string]string {
+ return nil // Keyword-only fixture does not call an embedding model.
+}
+
+type protocolWikiService struct{ interfaces.WikiPageService }
+
+func (*protocolWikiService) GetPageBySlug(ctx context.Context, id, slug string) (*types.WikiPage, error) {
+ if types.MustTenantIDFromContext(ctx) != 1 || id != "kb-own" || slug != "concept/fixture" {
+ return nil, fmt.Errorf("unexpected wiki scope or slug")
+ }
+ return &types.WikiPage{
+ ID: "page-1", KnowledgeBaseID: id, Slug: slug, Title: "Fixture",
+ Content: "wiki fixture body", Status: "published",
+ }, nil
+}
+
+func TestPublishedMCPRouteProtocolAndAuthorization(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ t.Setenv("LOCAL_STORAGE_BASE_DIR", t.TempDir())
+ srv := mcpserver.NewServer(&protocolKBService{}, nil, nil, &protocolWikiService{}, nil, nil, nil, nil,
+ nil, nil, nil, nil, nil, nil, nil, nil)
+ r := NewRouter(RouterParams{
+ Config: &config.Config{Tenant: &config.TenantConfig{}}, SystemHandler: &handler.SystemHandler{},
+ MCPServer: srv, MCPEndpointService: &protocolEndpointService{}, TenantService: &protocolTenantService{},
+ })
+ for _, version := range []string{"2025-11-25", "2026-07-28"} {
+ t.Run(version, func(t *testing.T) {
+ call := func(method, token, headerVersion string, params map[string]any) *httptest.ResponseRecorder {
+ t.Helper()
+ if version == "2026-07-28" {
+ if _, exists := params["_meta"]; !exists {
+ params["_meta"] = map[string]any{
+ "io.modelcontextprotocol/protocolVersion": version,
+ "io.modelcontextprotocol/clientCapabilities": map[string]any{},
+ }
+ }
+ }
+ body, err := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": method, "params": params})
+ require.NoError(t, err)
+ req := httptest.NewRequest(http.MethodPost, "/mcp/ep-1", bytes.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("Accept", "application/json, text/event-stream")
+ req.Header.Set("MCP-Protocol-Version", headerVersion)
+ if token != "" {
+ req.Header.Set("Authorization", "Bearer "+token)
+ }
+ if version == "2026-07-28" {
+ req.Header.Set("Mcp-Method", method)
+ if name, ok := params["name"].(string); ok {
+ req.Header.Set("Mcp-Name", name)
+ }
+ }
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, req)
+ if version == "2026-07-28" {
+ require.Empty(t, w.Header().Get("Mcp-Session-Id"))
+ }
+ return w
+ }
+ decode := func(w *httptest.ResponseRecorder) map[string]any {
+ t.Helper()
+ require.Contains(t, []int{http.StatusOK, http.StatusBadRequest}, w.Code, w.Body.String())
+ raw := w.Body.String()
+ for _, line := range strings.Split(raw, "\n") {
+ if strings.HasPrefix(line, "data:") {
+ raw = strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+ break
+ }
+ }
+ var response map[string]any
+ require.NoError(t, json.Unmarshal([]byte(raw), &response))
+ return response
+ }
+ if version == "2026-07-28" {
+ require.NotNil(t, decode(call("server/discover", "fixture", version, map[string]any{}))["result"])
+ } else {
+ params := map[string]any{
+ "protocolVersion": version, "capabilities": map[string]any{},
+ "clientInfo": map[string]any{"name": "fixture", "version": "1"},
+ }
+ initialized := decode(call("initialize", "fixture", version, params))
+ require.Equal(t, version, initialized["result"].(map[string]any)["protocolVersion"])
+ }
+ for _, token := range []string{"", "wrong"} {
+ require.Equal(t, http.StatusUnauthorized, call("tools/list", token, version, map[string]any{}).Code)
+ }
+ listed := decode(call("tools/list", "fixture", version, map[string]any{}))
+ require.Nil(t, listed["error"])
+ listResult := listed["result"].(map[string]any)
+ require.Len(t, listResult["tools"], 3)
+ if version == "2026-07-28" {
+ require.Equal(t, "complete", listResult["resultType"])
+ require.Equal(t, "private", listResult["cacheScope"])
+ require.Equal(t, float64(0), listResult["ttlMs"])
+ } else {
+ require.Nil(t, listResult["resultType"])
+ }
+ called := decode(call("tools/call", "fixture", version, map[string]any{
+ "name": types.MCPEndpointToolListKnowledgeBases, "arguments": map[string]any{},
+ }))
+ require.Nil(t, called["error"])
+ rows := called["result"].(map[string]any)["structuredContent"].(map[string]any)["knowledge_bases"].([]any)
+ require.Len(t, rows, 1)
+ require.Equal(t, "kb-own", rows[0].(map[string]any)["id"])
+ for _, tc := range []struct {
+ tool string
+ args map[string]any
+ body string
+ }{
+ {
+ types.MCPEndpointToolSearchKnowledge,
+ map[string]any{"query": "fixture", "mode": "keyword"},
+ "retrieval fixture body",
+ },
+ {
+ types.MCPEndpointToolWikiReadPage,
+ map[string]any{"slug": "concept/fixture", "knowledge_base_id": "kb-own"},
+ "wiki fixture body",
+ },
+ } {
+ response := decode(call("tools/call", "fixture", version,
+ map[string]any{"name": tc.tool, "arguments": tc.args}))
+ require.Nil(t, response["error"])
+ result := response["result"].(map[string]any)
+ require.NotEqual(t, true, result["isError"])
+ encoded, err := json.Marshal(result)
+ require.NoError(t, err)
+ require.Contains(t, string(encoded), tc.body)
+ if version == "2026-07-28" {
+ require.Equal(t, "complete", result["resultType"])
+ }
+ }
+ denied := decode(call("tools/call", "fixture", version, map[string]any{
+ "name": types.MCPEndpointToolSearchKnowledge,
+ "arguments": map[string]any{"query": "fixture", "knowledge_base_ids": []string{"kb-other"}},
+ }))
+ require.Equal(t, true, denied["result"].(map[string]any)["isError"])
+ hiddenResponse := call("tools/call", "fixture", version, map[string]any{
+ "name": types.MCPEndpointToolAsk, "arguments": map[string]any{"query": "fixture"},
+ })
+ if version == "2026-07-28" {
+ require.Equal(t, http.StatusBadRequest, hiddenResponse.Code)
+ } else {
+ require.Equal(t, http.StatusOK, hiddenResponse.Code)
+ }
+ hidden := decode(hiddenResponse)
+ require.Equal(t, float64(-32602), hidden["error"].(map[string]any)["code"])
+ if version == "2026-07-28" {
+ for _, header := range []string{"2025-11-25", "2099-01-01"} {
+ w := call("tools/list", "fixture", header, map[string]any{})
+ require.Equal(t, http.StatusBadRequest, w.Code, w.Body.String())
+ }
+ unknown := call("tools/list", "fixture", "2099-01-01", map[string]any{
+ "_meta": map[string]any{
+ "io.modelcontextprotocol/protocolVersion": "2099-01-01",
+ "io.modelcontextprotocol/clientCapabilities": map[string]any{},
+ },
+ })
+ require.Equal(t, http.StatusBadRequest, unknown.Code, unknown.Body.String())
+ }
+ })
+ }
+}
+
+func TestMCPModernHeadersPreflight(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ t.Setenv("LOCAL_STORAGE_BASE_DIR", t.TempDir())
+ r := NewRouter(RouterParams{
+ Config: &config.Config{Tenant: &config.TenantConfig{}}, SystemHandler: &handler.SystemHandler{},
+ })
+ req := httptest.NewRequest(http.MethodOptions, "/mcp/ep-1", nil)
+ req.Header.Set("Origin", "https://client.example")
+ req.Header.Set("Access-Control-Request-Method", "POST")
+ req.Header.Set("Access-Control-Request-Headers",
+ "authorization,content-type,mcp-protocol-version,mcp-method,mcp-name")
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, req)
+ if w.Code != http.StatusNoContent {
+ t.Fatalf("preflight status: %d", w.Code)
+ }
+ allowed := strings.ToLower(w.Header().Get("Access-Control-Allow-Headers"))
+ for _, name := range []string{"authorization", "content-type", "mcp-protocol-version", "mcp-method", "mcp-name"} {
+ if !strings.Contains(","+allowed+",", ","+name+",") {
+ t.Errorf("preflight does not allow %s", name)
+ }
+ }
+}
+
// TestMCPEndpointRoutesDeclareValidAPIKeyPolicies guards the startup
// self-check for the MCP endpoint management routes: every declared API-key
// policy must resolve to a registered route.
diff --git a/website-docs/03-features/08-mcp.md b/website-docs/03-features/08-mcp.md
index 7d35b6718..a907aa6bd 100644
--- a/website-docs/03-features/08-mcp.md
+++ b/website-docs/03-features/08-mcp.md
@@ -402,6 +402,16 @@ flowchart LR
### 内置 MCP Server 参考 {#第二部分-weknora-作为-mcp-server}
+#### 协议兼容
+
+内置 `/mcp/:endpoint_id` 同时支持 `2026-07-28` 与 `2025-11-25` 客户端,沿用同一个 URL、Bearer 令牌、工具白名单和知识库作用域。新版客户端通过 `server/discover` 发现能力,每个请求携带协议元数据与对应 HTTP 头;旧版客户端继续使用 `initialize`。浏览器预检允许 `Mcp-Method`、`Mcp-Name` 等协议请求头。新版发现及清单响应默认使用 `cacheScope=private`、`ttlMs=0`,不共享缓存受权限限制的目录。
+
+调用白名单以外的工具返回 JSON-RPC `-32602`,工具不会执行;这与旧 SDK 返回工具结果 `isError=true` 的错误形状不同。知识库越权仍由原有作用域检查拒绝。
+
+WeKnora 调用外部 MCP 服务时,由 `mcp-go v1.1.1` 按每个对端独立自动协商:先尝试新版发现,失败后尝试 legacy 初始化。忽略发现请求的旧服务最多增加约 5 秒探测等待;401/503 等探测失败也会尝试 legacy 初始化,两次失败则返回初始化错误。父请求取消或超时不会被标记为初始化成功。该协商不取决于调用 WeKnora 的客户端所用版本。
+
+外部工具目录保留完整 JSON Schema;新版工具调用会按 schema 的 `x-mcp-header` 标注生成 `Mcp-Param-*` 请求头。目录刷新失败时不会用部分结果替换上一次完整目录的参数头定义,断开连接时清除这些定义。
+
#### 数据模型与管理 API
`mcp_endpoints` 表(PostgreSQL 迁移 `000102_mcp_endpoints`,SQLite `000022_mcp_endpoints`)每行一个端点:`tenant_id`、`name`、`description`、`enabled`、`token_hash`(SHA-256)、`token_hint`(前缀展示用)、`knowledge_base_ids`(空数组表示空间内全部)、`tools`(白名单)、`default_agent_id`(空为内置快速问答)、`rate_limit_per_minute`(默认 60,上限 6000)、`last_used_at`。类型定义在 `internal/types/mcp_endpoint.go`,工具目录在 `internal/types/mcp_endpoint_tools.go`。