Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(mcp): support 2026-07-28 alongside legacy clients (#4095)
Perfecto03e2c47aecbf
diff --git a/go.mod b/go.modindex 7ce2b564e..446d06638 100644--- a/go.mod+++ b/go.mod@@ -34,7 +34,7 @@ require (github.com/joho/godotenv v1.5.1github.com/ks3sdklib/aws-sdk-go v1.11.0github.com/larksuite/oapi-sdk-go/v3 v3.9.7- github.com/mark3labs/mcp-go v0.52.0+ github.com/mark3labs/mcp-go v1.1.1github.com/matiasinsaurralde/go-e2b v0.1.1-0.20260808041540-fdc08ceaa1c1github.com/milvus-io/milvus/client/v2 v2.6.4github.com/minio/minio-go/v7 v7.1.0diff --git a/go.sum b/go.sumindex 528734cfd..de97b765a 100644--- a/go.sum+++ b/go.sum@@ -2231,8 +2231,8 @@ github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPgithub.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.goindex 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 = 30logged := 0for i, tool := range listed {diff --git a/internal/application/service/mcp_metadata_test.go b/internal/application/service/mcp_metadata_test.goindex 2ffba28a0..a9ef9621f 100644--- a/internal/application/service/mcp_metadata_test.go+++ b/internal/application/service/mcp_metadata_test.go@@ -1,10 +1,14 @@package serviceimport (+ "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.goindex 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.goindex 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.MCPServiceclient *client.Client+ discovery *discoverTransportoauth *oauthRuntimeconnected atomic.Boolinitialized atomic.BoolmetadataMu sync.RWMutexinstructions 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.HTTPConnectionswitch 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.Errorif !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 clientif 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, errorif 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[stringArguments: 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.gonew file mode 100644index 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 := ¶mHeaderPeer{}+ 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.gonew file mode 100644index 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.goindex fbca0a9cc..b3c29c786 100644--- a/internal/mcp/client_session_test.go+++ b/internal/mcp/client_session_test.go@@ -3,6 +3,8 @@ package mcpimport ("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.goindex 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.goindex 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.goindex 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.goindex 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.goindex 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.goindex d1eea84d8..db28ba99f 100644--- a/internal/router/routes_mcp_endpoint_test.go+++ b/internal/router/routes_mcp_endpoint_test.go@@ -1,14 +1,273 @@package routerimport (+ "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.mdindex 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`。