From 03e2c47aecbf60120820216baaa8abb2e98844f7 Mon Sep 17 00:00:00 2001 From: Perfecto Date: Sat, 10 Oct 2026 15:15:06 +0800 Subject: [PATCH] feat(mcp): support 2026-07-28 alongside legacy clients (#4095) * feat(mcp): support modern and legacy protocol connections * fix(mcp): preserve annotated headers on modern tool calls * fix(mcp): load parameter header schemas before tool calls * fix(mcp): keep a working legacy session when discovery retry fails Modern method-level 404s stay connected, while an expired SSE session still disconnects. A transient discover failure retries once, and a failed retry keeps the handshake that already succeeded. * fix(mcp): wrap protocol negotiation lines for the linter golangci-lint rejects lines longer than 120 characters. * fix(mcp): retry protocol discovery without dropping the live session A second initialize on the same transport clears a stateful legacy session when discover returns 404. Probe on a separate connection, and drop cached parameter headers after another client refreshes the directory. --------- Co-authored-by: wizardchen --- go.mod | 2 +- go.sum | 4 +- internal/application/service/mcp_metadata.go | 3 + .../application/service/mcp_metadata_test.go | 92 +++ internal/application/service/mcp_service.go | 2 + internal/mcp/client.go | 249 ++++++- internal/mcp/client_param_headers_test.go | 222 ++++++ internal/mcp/client_protocol_test.go | 681 ++++++++++++++++++ internal/mcp/client_session_test.go | 58 ++ internal/mcp/client_tools_test.go | 3 + internal/mcp/manager.go | 26 + internal/mcp/manager_startup_test.go | 2 +- internal/mcpserver/server_test.go | 12 +- internal/router/router.go | 2 +- internal/router/routes_mcp_endpoint_test.go | 259 +++++++ website-docs/03-features/08-mcp.md | 10 + 16 files changed, 1580 insertions(+), 47 deletions(-) create mode 100644 internal/mcp/client_param_headers_test.go create mode 100644 internal/mcp/client_protocol_test.go diff --git a/go.mod b/go.mod index 7ce2b564..446d0663 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 528734cf..de97b765 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 7a34298d..3478d1da 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 2ffba28a..a9ef9621 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 a595c0d2..0516349a 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 c490af99..29553aa3 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") } - 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 := []transport.ClientOption{ + transport.WithHTTPClient(httpClient), + transport.WithHeaders(headers), } + if useOAuth { + 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") } - 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 := []transport.StreamableHTTPCOption{ + transport.WithHTTPBasicClient(httpClient), + transport.WithHTTPHeaders(headers), } + if useOAuth { + 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 00000000..6afd75ef --- /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.go new file mode 100644 index 00000000..8436f993 --- /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 fbca0a9c..b3c29c78 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 f075fd0d..510ed964 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 5d1e1fdc..d0af134e 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 6bd1df91..97306f80 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 86f6f0b7..73545dc6 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 e346c267..2d435c6f 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 d1eea84d..db28ba99 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 7d35b671..a907aa6b 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`。