From 22ed337c20837bf7afdbca24818156df6195f63a Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 01:08:24 +1000 Subject: [PATCH] feat(tools): add per-server parallel_tool_calls to the MCP client MCPServer gains ParallelToolCalls (default false). The client's per-server callMu is now nil for a server that opted in, so CallTool stops serializing that server's calls and the caller's own concurrency decides; every other server keeps exactly one tools/call in flight. The flag is threaded from config through the provider constructor - the only place MCPServer configs become Client instances - into NewClient, in both the daemon and the agent worker. --- config.example.toml | 5 + internal/app/agentworker/mcp_providers.go | 2 +- internal/app/archied/main.go | 6 +- internal/config/config.go | 7 + internal/config/config_test.go | 41 ++++++ internal/tools/mcp/client.go | 22 ++- internal/tools/mcp/client_test.go | 4 +- internal/tools/mcp/parallel_test.go | 129 +++++++++++++++++- .../mcp/desktop_commander_integration_test.go | 2 +- internal/tools/provider/mcp/provider.go | 21 ++- internal/tools/provider/mcp/provider_test.go | 121 ++++++++++++++-- 11 files changed, 325 insertions(+), 35 deletions(-) diff --git a/config.example.toml b/config.example.toml index 4dc94ca29..25a9c2ae3 100644 --- a/config.example.toml +++ b/config.example.toml @@ -200,12 +200,17 @@ class = "ollama" # a Playwright/Puppeteer-based server fetching a browser binary from a CDN # via its postinstall script) -- consult that package's own env vars for # those. +# Most MCP servers are single-threaded and get one tools/call at a time. +# parallel_tool_calls = true (default false) drops that serialization for +# this server only, for a server whose own implementation handles +# concurrent requests. It never affects another configured server. # [[tools.mcp_servers]] # name = "desktop-commander" # transport = "stdio" # command = "npx" # args = ["-y", "@wonderwhy-er/desktop-commander@0.2.46", "--no-onboarding"] # work_dir = "/path/to/workspace" +# parallel_tool_calls = false # Workspace code-search index. Paths default under work_dir when unset. [indexing] diff --git a/internal/app/agentworker/mcp_providers.go b/internal/app/agentworker/mcp_providers.go index da98e684c..2d43ec376 100644 --- a/internal/app/agentworker/mcp_providers.go +++ b/internal/app/agentworker/mcp_providers.go @@ -89,7 +89,7 @@ func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, err if err != nil { return nil, transportType, err } - return mcptoolprovider.New(name, transport), transportType, nil + return mcptoolprovider.New(name, transport, server.ParallelToolCalls), transportType, nil } func mcpTransportForServer( diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index a139feb5e..a362f6902 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -221,7 +221,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide Dir: server.WorkDir, Env: npmCacheServerEnv(command, workDir), }) - return mcptoolprovider.New(name, transport), nil + return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil case "http", "streamablehttp": url := strings.TrimSpace(server.URL) @@ -232,7 +232,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide Endpoint: url, Headers: server.Headers, }) - return mcptoolprovider.New(name, transport), nil + return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil case "sse": sseEndpoint := strings.TrimSpace(server.SSEEndpoint) @@ -244,7 +244,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide MessageEndpoint: strings.TrimSpace(server.MessageEndpoint), Headers: server.Headers, }) - return mcptoolprovider.New(name, transport), nil + return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil default: return nil, fmt.Errorf("MCP transport %q is not supported", transportType) diff --git a/internal/config/config.go b/internal/config/config.go index 3e26e81da..99a1d3bbc 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -340,6 +340,13 @@ type MCPServer struct { // MessageEndpoint is the POST URL for client→server messages. When // empty, the client discovers it from the server's "endpoint" SSE event. MessageEndpoint string `toml:"message_endpoint" yaml:"message_endpoint" json:"message_endpoint,omitempty"` + + // ParallelToolCalls lifts the client's serialization of tools/call for + // this server only, letting concurrent callers overlap. Default false: + // one call in flight at a time, because most MCP servers are + // single-threaded processes that do not handle concurrent requests + // safely. Set it only for a server whose implementation does. + ParallelToolCalls bool `toml:"parallel_tool_calls" yaml:"parallel_tool_calls" json:"parallel_tool_calls"` } // ToolPolicy holds tool execution limits. diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 87aca01da..3f8cca567 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -76,6 +76,47 @@ work_dir = "/workspace" } } +func TestMCPServerParallelToolCallsDecodesFromTOML(t *testing.T) { + tests := []struct { + name string + server string + want bool + }{ + { + name: "absent key leaves the server serialized", + server: ` +[[tools.mcp_servers]] +name = "desktop-commander" +command = "npx" +`, + }, + { + name: "parallel_tool_calls opts the server in", + server: ` +[[tools.mcp_servers]] +name = "desktop-commander" +command = "npx" +parallel_tool_calls = true +`, + want: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var cfg Config + if _, err := toml.Decode(tt.server, &cfg); err != nil { + t.Fatal(err) + } + if len(cfg.Tools.MCPServers) != 1 { + t.Fatalf("MCPServers = %#v, want one server", cfg.Tools.MCPServers) + } + if got := cfg.Tools.MCPServers[0].ParallelToolCalls; got != tt.want { + t.Fatalf("ParallelToolCalls = %t, want %t", got, tt.want) + } + }) + } +} + func TestChatModelCatalogDecodesFromTOML(t *testing.T) { var cfg Config if _, err := toml.Decode(` diff --git a/internal/tools/mcp/client.go b/internal/tools/mcp/client.go index dce95aa3f..01be934fa 100644 --- a/internal/tools/mcp/client.go +++ b/internal/tools/mcp/client.go @@ -33,15 +33,23 @@ type Client struct { nextID atomic.Int64 // callMu serializes tools/call requests to this server. Most MCP // servers are single-threaded processes and don't expect or handle - // concurrent requests safely. + // concurrent requests safely, so serializing is the default. A server + // whose config declares it handles concurrent requests gets no callMu: + // nil means this server's calls are never held apart. callMu *sync.Mutex } // NewClient builds a Client over transport. serverName identifies this // MCP server in log/error messages; it need not match the server's own -// self-reported name. -func NewClient(transport Transport, serverName string) *Client { - return &Client{transport: transport, serverName: serverName, callMu: &sync.Mutex{}} +// self-reported name. parallelToolCalls drops the per-server serialization +// of tools/call: false (the default) keeps one call in flight at a time, +// true lets the caller's own concurrency through. +func NewClient(transport Transport, serverName string, parallelToolCalls bool) *Client { + c := &Client{transport: transport, serverName: serverName} + if !parallelToolCalls { + c.callMu = &sync.Mutex{} + } + return c } // InitializeResult is the server's response to initialize. @@ -155,8 +163,10 @@ func (c *Client) ListTools(ctx context.Context) ([]ToolSchema, error) { // reported via CallToolResult.IsError, not a Go error -- see // [CallToolResult]. func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (CallToolResult, error) { - c.callMu.Lock() - defer c.callMu.Unlock() + if c.callMu != nil { + c.callMu.Lock() + defer c.callMu.Unlock() + } params := map[string]any{"name": name, "arguments": arguments} var result CallToolResult diff --git a/internal/tools/mcp/client_test.go b/internal/tools/mcp/client_test.go index 4e58269df..81057e236 100644 --- a/internal/tools/mcp/client_test.go +++ b/internal/tools/mcp/client_test.go @@ -51,7 +51,7 @@ func (f *fakeSender) Notify(_ context.Context, body []byte) error { } func newTestClient(f *fakeSender) *Client { - return NewClient(f, "test-server") + return NewClient(f, "test-server", false) } func TestInitializeSendsInitializeThenInitializedNotification(t *testing.T) { @@ -157,7 +157,7 @@ func TestListToolsFollowsPaginationCursor(t *testing.T) { return page1, nil } return page2, nil - }), "test-server") + }), "test-server", false) toolList, err := c.ListTools(context.Background()) if err != nil { diff --git a/internal/tools/mcp/parallel_test.go b/internal/tools/mcp/parallel_test.go index 8142963a4..b6a060f6d 100644 --- a/internal/tools/mcp/parallel_test.go +++ b/internal/tools/mcp/parallel_test.go @@ -14,6 +14,11 @@ import ( // once (parallel) or one completes before the next starts (serialized). type blockingSender struct { release chan struct{} + // entered receives one token per Send that starts, before that Send + // blocks on release. A test counts the tokens to learn how many calls + // the client allowed to overlap; unlike a sampled maximum, a token is + // only ever sent by a call that really reached Send. + entered chan struct{} mu sync.Mutex inFlight int @@ -28,6 +33,9 @@ func (b *blockingSender) Send(_ context.Context, body []byte) ([]byte, error) { } b.mu.Unlock() + if b.entered != nil { + b.entered <- struct{}{} + } <-b.release b.mu.Lock() @@ -47,9 +55,122 @@ func (b *blockingSender) MaxInFlight() int { return b.maxInFlight } +// overlapWindow bounds how long a test gives calls to reach Send. A call +// that is genuinely allowed to overlap reaches Send microseconds after its +// goroutine starts, so a call still absent after this window is being held +// back by the client, not by the scheduler. +const overlapWindow = 500 * time.Millisecond + +// enteredCount reports how many of n calls reached Send within window. +func enteredCount(entered <-chan struct{}, n int, window time.Duration) int { + count := 0 + for range n { + select { + case <-entered: + count++ + case <-time.After(window): + return count + } + } + return count +} + +// TestCallToolParallelToolCallsControlsSameServerOverlap pins the per-server +// flag: a server that has not opted in keeps one tools/call in flight, and a +// server that opted in lets its calls overlap. +func TestCallToolParallelToolCallsControlsSameServerOverlap(t *testing.T) { + tests := []struct { + name string + parallelToolCalls bool + wantInFlight int + }{ + { + name: "server that has not opted in serializes tools/call", + wantInFlight: 1, + }, + { + name: "opted-in server overlaps tools/call", + parallelToolCalls: true, + wantInFlight: 2, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + b := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})} + c := NewClient(b, "test-server", tt.parallelToolCalls) + + errs := make([]error, 2) + started := make(chan struct{}, len(errs)) + var wg sync.WaitGroup + for i := range errs { + wg.Go(func() { + started <- struct{}{} + _, errs[i] = c.CallTool(context.Background(), "slow", nil) + }) + } + // Both callers are inside CallTool before either is measured, so + // the count is what the client allowed, not the scheduler's. + for range errs { + <-started + } + + if got := enteredCount(b.entered, len(errs), overlapWindow); got != tt.wantInFlight { + t.Fatalf("calls in flight at once = %d, want %d", got, tt.wantInFlight) + } + + close(b.release) + wg.Wait() + for i, err := range errs { + if err != nil { + t.Fatalf("call %d: %v", i, err) + } + } + }) + } +} + +// TestParallelToolCallsIsPerServer pins the isolation half of the flag: one +// server opting in must not un-serialize another server in the same process, +// even while the opted-in server's own calls are overlapping. +func TestParallelToolCallsIsPerServer(t *testing.T) { + optedIn := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})} + serialized := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})} + parallel := NewClient(optedIn, "opted-in", true) + sequential := NewClient(serialized, "default", false) + + call := func(c *Client) { + if _, err := c.CallTool(context.Background(), "slow", nil); err != nil { + t.Errorf("CallTool: %v", err) + } + } + + var parallelWG sync.WaitGroup + for range 2 { + parallelWG.Go(func() { call(parallel) }) + } + if got := enteredCount(optedIn.entered, 2, overlapWindow); got != 2 { + t.Fatalf("opted-in server calls in flight = %d, want 2", got) + } + + // The opted-in server's calls are still open when the other server is + // measured, so a leak of its parallelism would show up here. + var sequentialWG sync.WaitGroup + for range 2 { + sequentialWG.Go(func() { call(sequential) }) + } + if got := enteredCount(serialized.entered, 2, overlapWindow); got != 1 { + t.Fatalf("server that did not opt in calls in flight = %d, want 1: opting one server in must not free another server's calls", got) + } + + close(optedIn.release) + close(serialized.release) + parallelWG.Wait() + sequentialWG.Wait() +} + func TestCallToolSerializesByDefault(t *testing.T) { b := &blockingSender{release: make(chan struct{})} - c := NewClient(b, "test-server") + c := NewClient(b, "test-server", false) const n = 5 var wg sync.WaitGroup @@ -73,7 +194,7 @@ func TestCallToolSerializesByDefault(t *testing.T) { func TestCallToolSerializedStillCompletesAllCalls(t *testing.T) { b := &blockingSender{release: make(chan struct{})} close(b.release) // never actually blocks -- just verifying correctness, not timing - c := NewClient(b, "test-server") + c := NewClient(b, "test-server", false) const n = 10 var completed atomic.Int32 @@ -98,8 +219,8 @@ func TestCallToolSerializationDoesNotBlockDifferentClients(t *testing.T) { b1 := &blockingSender{release: make(chan struct{})} b2 := &blockingSender{release: make(chan struct{})} close(b2.release) // c2's own call should complete immediately, unblocked - c1 := NewClient(b1, "server-1") - c2 := NewClient(b2, "server-2") + c1 := NewClient(b1, "server-1", false) + c2 := NewClient(b2, "server-2", false) done := make(chan struct{}) go func() { diff --git a/internal/tools/provider/mcp/desktop_commander_integration_test.go b/internal/tools/provider/mcp/desktop_commander_integration_test.go index 53cf919ac..25494e92d 100644 --- a/internal/tools/provider/mcp/desktop_commander_integration_test.go +++ b/internal/tools/provider/mcp/desktop_commander_integration_test.go @@ -25,7 +25,7 @@ func TestDesktopCommanderClientCompatibility(t *testing.T) { }, Dir: "../../..", }) - provider := New("desktop-commander", transport) + provider := New("desktop-commander", transport, false) if err := provider.Start(ctx); err != nil { t.Fatalf("start Desktop Commander through MCP client: %v", err) } diff --git a/internal/tools/provider/mcp/provider.go b/internal/tools/provider/mcp/provider.go index 4f4e4441c..f81f1a7ab 100644 --- a/internal/tools/provider/mcp/provider.go +++ b/internal/tools/provider/mcp/provider.go @@ -39,6 +39,12 @@ type Provider struct { transport LifecycleTransport client *protocol.Client + // parallelToolCalls is the configured server's opt-in to concurrent + // tools/call. It is handed to the client Start builds: the client is + // what serializes calls, so the flag has to reach it or the server + // stays serialized. + parallelToolCalls bool + // mediaDir is the root directory binary content blocks (images, audio, // resource blobs) are written under, created lazily on the first // multimodal tool result. It is removed by Stop. @@ -48,12 +54,15 @@ type Provider struct { mediaCallSeq atomic.Int64 } -// New creates an MCP tool provider. -func New(name string, transport LifecycleTransport) *Provider { +// New creates an MCP tool provider. parallelToolCalls mirrors the +// configured server's own flag: false (the default) has the provider's +// client serialize tools/call, true lets them overlap. +func New(name string, transport LifecycleTransport, parallelToolCalls bool) *Provider { return &Provider{ - name: strings.TrimSpace(name), - segment: sanitizeToolSegment(name), - transport: transport, + name: strings.TrimSpace(name), + segment: sanitizeToolSegment(name), + transport: transport, + parallelToolCalls: parallelToolCalls, } } @@ -94,7 +103,7 @@ func (p *Provider) Start(ctx context.Context) error { if err := p.transport.Start(ctx); err != nil { return fmt.Errorf("start MCP server %q: %w", p.name, err) } - client := protocol.NewClient(p.transport, p.name) + client := protocol.NewClient(p.transport, p.name, p.parallelToolCalls) if _, err := client.Initialize(ctx); err != nil { cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout) stopErr := p.transport.Stop(cleanupCtx) diff --git a/internal/tools/provider/mcp/provider_test.go b/internal/tools/provider/mcp/provider_test.go index 74c8dbcbd..5b653688c 100644 --- a/internal/tools/provider/mcp/provider_test.go +++ b/internal/tools/provider/mcp/provider_test.go @@ -8,6 +8,7 @@ import ( "strings" "sync" "testing" + "time" "github.com/samcharles93/archie-core/internal/tools" protocol "github.com/samcharles93/archie-core/internal/tools/mcp" @@ -21,7 +22,7 @@ func TestProviderInitializesDiscoversAndCallsOriginalMCPTool(t *testing.T) { Description: "Search repositories", InputSchema: tools.JSONSchema{"type": "object"}, }} - provider := New("Git Hub/Prod", transport) + provider := New("Git Hub/Prod", transport, false) manifest := provider.Manifest() if manifest.ID != "mcp.git-hub-prod" { @@ -71,6 +72,83 @@ func TestProviderInitializesDiscoversAndCallsOriginalMCPTool(t *testing.T) { } } +// callOverlapWindow bounds how long a test gives tool calls to reach the +// transport. A call allowed to overlap gets there microseconds after its +// goroutine starts, so one still absent after this window is held back by +// the client, not by the scheduler. +const callOverlapWindow = 500 * time.Millisecond + +// reachedSend reports how many of n calls reached Send within window. +func reachedSend(entered <-chan struct{}, n int, window time.Duration) int { + count := 0 + for range n { + select { + case <-entered: + count++ + case <-time.After(window): + return count + } + } + return count +} + +// TestProviderParallelToolCallsReachTheMCPClient pins the wiring half of the +// per-server flag: the choice made at construction has to reach the client +// the provider builds in Start, or a server that opted in stays serialized +// with no other symptom. +func TestProviderParallelToolCallsReachTheMCPClient(t *testing.T) { + tests := []struct { + name string + parallelToolCalls bool + wantInFlight int + }{ + { + name: "provider for a server that has not opted in keeps one tool call in flight", + wantInFlight: 1, + }, + { + name: "provider for an opted-in server overlaps tool calls", + parallelToolCalls: true, + wantInFlight: 2, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + transport := newFakeTransport() + transport.listed = []protocol.ToolSchema{{Name: "slow"}} + transport.callEntered = make(chan struct{}, 2) + transport.callRelease = make(chan struct{}) + provider := New("slow-server", transport, tt.parallelToolCalls) + if err := provider.Start(context.Background()); err != nil { + t.Fatal(err) + } + entries, err := provider.Discover(context.Background()) + if err != nil { + t.Fatal(err) + } + if len(entries) != 1 { + t.Fatalf("Discover() count = %d, want 1", len(entries)) + } + + var wg sync.WaitGroup + for range 2 { + wg.Go(func() { + if _, err := entries[0].Handler(context.Background(), nil); err != nil { + t.Errorf("handler: %v", err) + } + }) + } + + if got := reachedSend(transport.callEntered, 2, callOverlapWindow); got != tt.wantInFlight { + t.Fatalf("tool calls in flight at once = %d, want %d", got, tt.wantInFlight) + } + + close(transport.callRelease) + wg.Wait() + }) + } +} + func TestProviderSurfacesMCPToolLevelErrors(t *testing.T) { transport := newFakeTransport() transport.listed = []protocol.ToolSchema{{Name: "fails"}} @@ -78,7 +156,7 @@ func TestProviderSurfacesMCPToolLevelErrors(t *testing.T) { Content: []protocol.ContentBlock{{Type: "text", Text: "denied"}}, IsError: true, } - provider := New("errors", transport) + provider := New("errors", transport, false) if err := provider.Start(context.Background()); err != nil { t.Fatal(err) } @@ -104,7 +182,7 @@ func TestProviderPreservesResourceTextAndMultimodalResults(t *testing.T) { {Type: "resource", Resource: &protocol.ResourceContent{Text: " resource context"}}, {Type: "image", Data: "aW1hZ2U=", MimeType: "image/png"}, }} - provider := New("media", transport) + provider := New("media", transport, false) if err := provider.Start(context.Background()); err != nil { t.Fatal(err) } @@ -135,7 +213,7 @@ func TestProviderWritesBinaryContentToDeliverableMediaRefs(t *testing.T) { {Type: "audio", Data: "YXVkaW8=", MimeType: "audio/wav"}, {Type: "resource", Resource: &protocol.ResourceContent{MimeType: "application/pdf", Blob: "cGRm"}}, }} - provider := New("media", transport) + provider := New("media", transport, false) if err := provider.Start(context.Background()); err != nil { t.Fatal(err) } @@ -214,7 +292,7 @@ func TestProviderStartFailureStopsTransport(t *testing.T) { transport := newFakeTransport() transport.startErr = tt.startErr transport.sendErr = tt.sendErr - provider := New("failure", transport) + provider := New("failure", transport, false) if err := provider.Start(context.Background()); err == nil { t.Fatal("Start() succeeded") } @@ -237,7 +315,7 @@ func TestProviderRejectsInvalidConfiguration(t *testing.T) { } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - provider := New(tt.server, tt.transport) + provider := New(tt.server, tt.transport, false) if err := provider.Start(context.Background()); err == nil { t.Fatal("Start() succeeded") } @@ -246,7 +324,7 @@ func TestProviderRejectsInvalidConfiguration(t *testing.T) { } func TestProviderSatisfiesEngine(t *testing.T) { - var _ toolprovider.Engine = New("compile", newFakeTransport()) + var _ toolprovider.Engine = New("compile", newFakeTransport(), false) } // Compile-time checks: HTTP and SSE transports satisfy LifecycleTransport. @@ -293,6 +371,13 @@ type fakeTransport struct { notifyMethods []string calledName string calledArgs map[string]any + + // callEntered receives one token per tools/call that reaches Send, and + // the call then blocks until callRelease is closed. Set both before + // Start to hold tool calls open and observe how many the client let + // overlap. + callEntered chan struct{} + callRelease chan struct{} } func newFakeTransport() *fakeTransport { @@ -332,11 +417,6 @@ func (t *fakeTransport) State() protocol.TransportState { } func (t *fakeTransport) Send(_ context.Context, body []byte) ([]byte, error) { - t.mu.Lock() - defer t.mu.Unlock() - if t.sendErr != nil { - return nil, t.sendErr - } var request struct { ID json.RawMessage `json:"id"` Method string `json:"method"` @@ -345,6 +425,23 @@ func (t *fakeTransport) Send(_ context.Context, body []byte) ([]byte, error) { if err := json.Unmarshal(body, &request); err != nil { return nil, err } + + // Outside the lock: holding it here would serialize the calls this hook + // exists to observe, making a parallel client look serialized. + if request.Method == "tools/call" { + if t.callEntered != nil { + t.callEntered <- struct{}{} + } + if t.callRelease != nil { + <-t.callRelease + } + } + + t.mu.Lock() + defer t.mu.Unlock() + if t.sendErr != nil { + return nil, t.sendErr + } var result any switch request.Method { case "initialize":