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 <wizardchen@tencent.com>
main
Perfecto 2026-10-10 15:15:06 +08:00 committed by GitHub
parent d6269994b3
commit 03e2c47aec
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
16 changed files with 1580 additions and 47 deletions

2
go.mod
View File

@ -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

4
go.sum
View File

@ -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=

View File

@ -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 {

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -0,0 +1,222 @@
package mcp
import (
"bytes"
"context"
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"sync"
"testing"
"time"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/utils"
sdk "github.com/mark3labs/mcp-go/mcp"
"github.com/mark3labs/mcp-go/server"
"github.com/stretchr/testify/require"
)
// Directory refreshes use a temporary client, while Agent calls may only have
// the persisted tool definition. Neither that refresh nor a retired connection
// can populate the schema cache of the connection that actually calls the tool.
func TestCallToolParamHeadersWithoutConnectionDiscovery(t *testing.T) {
utils.SetSSRFWhitelistFromRaw("127.0.0.1")
t.Cleanup(utils.ResetSSRFWhitelistForTest)
for _, mode := range []string{"modern", "legacy"} {
for _, scenario := range []string{"persisted directory", "reconnected"} {
t.Run(mode+"/"+scenario, func(t *testing.T) {
peer := newParamHeaderPeer(t, mode == "legacy")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
manager := NewMCPManager(nil)
defer manager.CloseAll()
var directoryClient MCPClient
var err error
if scenario == "persisted directory" {
directoryClient, err = NewMCPClient(&ClientConfig{Service: peer.service})
require.NoError(t, err)
require.NoError(t, directoryClient.Connect(ctx))
_, err = directoryClient.Initialize(ctx)
} else {
directoryClient, err = manager.GetOrCreateClient(ctx, peer.service)
}
require.NoError(t, err)
tools, err := directoryClient.ListTools(ctx)
require.NoError(t, err)
require.Len(t, tools, 2)
require.Equal(t, "echo", tools[1].Name)
if scenario == "persisted directory" {
require.NoError(t, directoryClient.Disconnect())
} else {
require.NoError(t, manager.CloseClient(peer.service.ID))
}
c, err := manager.GetOrCreateClient(ctx, peer.service)
require.NoError(t, err)
beforeLists, _ := peer.counts()
for _, value := range []string{"first", "second"} {
// Use the saved definition without listing tools on this client.
result, err := c.CallTool(ctx, tools[1].Name, map[string]interface{}{"value": value})
require.NoError(t, err)
require.False(t, result.IsError)
require.Equal(t, "ok", result.Content[0].Text)
}
afterLists, headers := peer.counts()
if mode == "modern" {
require.Equal(t, []string{"first", "second"}, headers)
// Two tools plus the empty terminal page. A second call must
// reuse the complete cache instead of listing again.
require.Equal(t, 3, afterLists-beforeLists)
} else {
require.Equal(t, []string{"", ""}, headers)
require.Equal(t, beforeLists, afterLists, "legacy calls need no header discovery")
}
})
}
}
}
func TestCallToolParamHeadersDiscoveryFailure(t *testing.T) {
utils.SetSSRFWhitelistFromRaw("127.0.0.1")
t.Cleanup(utils.ResetSSRFWhitelistForTest)
peer := newParamHeaderPeer(t, false)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
manager := NewMCPManager(nil)
defer manager.CloseAll()
c, err := manager.GetOrCreateClient(ctx, peer.service)
require.NoError(t, err)
peer.mu.Lock()
peer.failPage = true
peer.mu.Unlock()
_, err = c.CallTool(ctx, "echo", map[string]interface{}{"value": "first"})
require.ErrorContains(t, err, "directory unavailable")
lists, headers := peer.counts()
require.Equal(t, 2, lists)
require.Empty(t, headers, "do not execute with missing or partial call metadata")
rawClient := c.(*managedMCPClient).MCPClient.(*mcpGoClient)
rawClient.metadataMu.RLock()
emptyCache := len(rawClient.toolSchemas) == 0
rawClient.metadataMu.RUnlock()
require.True(t, emptyCache, "a failed paginated discovery must not cache its first page")
peer.mu.Lock()
peer.failPage = false
peer.mu.Unlock()
result, err := c.CallTool(ctx, "echo", map[string]interface{}{"value": "retry"})
require.NoError(t, err)
require.False(t, result.IsError)
lists, headers = peer.counts()
require.Equal(t, 5, lists)
require.Equal(t, []string{"retry"}, headers)
}
func TestCallToolParamHeadersDiscoveryStopsBeforeExecution(t *testing.T) {
utils.SetSSRFWhitelistFromRaw("127.0.0.1")
t.Cleanup(utils.ResetSSRFWhitelistForTest)
for _, scenario := range []string{"cancelled", "missing tool"} {
t.Run(scenario, func(t *testing.T) {
peer := newParamHeaderPeer(t, false)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
manager := NewMCPManager(nil)
defer manager.CloseAll()
c, err := manager.GetOrCreateClient(ctx, peer.service)
require.NoError(t, err)
name := "missing"
if scenario == "cancelled" {
name = "echo"
cancel()
}
_, err = c.CallTool(ctx, name, map[string]interface{}{"value": "unused"})
lists, headers := peer.counts()
if scenario == "cancelled" {
require.ErrorIs(t, err, context.Canceled)
require.Zero(t, lists)
} else {
require.ErrorContains(t, err, `tool "missing" not found`)
require.Equal(t, 3, lists)
}
require.Empty(t, headers, "do not execute without a resolved schema")
})
}
}
type paramHeaderPeer struct {
service *types.MCPService
mu sync.Mutex
lists int
headers []string
failPage bool
}
func (p *paramHeaderPeer) counts() (int, []string) {
p.mu.Lock()
defer p.mu.Unlock()
return p.lists, append([]string(nil), p.headers...)
}
func newParamHeaderPeer(t *testing.T, legacy bool) *paramHeaderPeer {
t.Helper()
p := &paramHeaderPeer{}
s := server.NewMCPServer("param-headers", "1", server.WithPaginationLimit(1))
for _, name := range []string{"alpha", "echo"} {
s.AddTool(sdk.Tool{Name: name, RawInputSchema: json.RawMessage(`{
"type":"object","properties":{"value":{"type":"string","x-mcp-header":"Value"}}
}`)}, func(context.Context, sdk.CallToolRequest) (*sdk.CallToolResult, error) {
return sdk.NewToolResultText("ok"), nil
})
}
handler := server.NewStreamableHTTPServer(s, server.WithStateLess(true))
httpServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method == http.MethodPost {
body, err := io.ReadAll(r.Body)
if err != nil {
t.Error(err)
return
}
r.Body = io.NopCloser(bytes.NewReader(body))
var request struct {
ID json.RawMessage `json:"id"`
Method string `json:"method"`
Params struct {
Cursor string `json:"cursor"`
} `json:"params"`
}
if err := json.Unmarshal(body, &request); err != nil {
t.Error(err)
return
}
p.mu.Lock()
if request.Method == "tools/list" {
p.lists++
}
if request.Method == "tools/call" {
p.headers = append(p.headers, r.Header.Get("Mcp-Param-Value"))
}
failPage := p.failPage && request.Method == "tools/list" && request.Params.Cursor != ""
p.mu.Unlock()
if (legacy && request.Method == "server/discover") || failPage {
code, message := -32601, "Method not found"
if failPage {
code, message = -32603, "directory unavailable"
}
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{
"jsonrpc": "2.0", "id": request.ID,
"error": map[string]any{"code": code, "message": message},
})
return
}
}
handler.ServeHTTP(w, r)
}))
t.Cleanup(httpServer.Close)
p.service = &types.MCPService{
ID: "param-headers", Name: "param-headers", Enabled: true,
URL: &httpServer.URL, TransportType: types.MCPTransportHTTPStreamable,
}
return p
}

View File

@ -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)
}
})
}
}

View File

@ -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.

View File

@ -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()

View File

@ -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.

View File

@ -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) })

View File

@ -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)
}
}

View File

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

View File

@ -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.

View File

@ -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`。