feat: expose MCP tools on demand #12
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
sam/brainless!12
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/lazy-mcp-tools"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Adds MCP tool calling to brainless, and exposes tool schemas only when the model asks for them, so a prompt carries the
toolsstub plus whatever the turn actually loaded instead of every connected server's full catalog.How
internal/config: optionalmcpServersmap inbrainless.json.transport: "stdio"(command/args/env) andtransport: "http"(url/headers) are separate config shapes, decoded by a transport discriminator.internal/harness: connects to the config-file servers plus the servers an ACP session declares inNewSessionRequest.McpServers, lists their tools once per session, and closes the connections when the session changes (internal/harness/mcp.go).toolsstub is exposed up front. It returns a compact one-line catalog of every available tool and loads the ones named in itsloadargument (internal/harness/tools.go).selectorModel.GenerateContentcallspruneToolsbefore each model call, which removes every unloaded tool fromreq.Toolsandreq.Config.Tools(internal/harness/registry.go,internal/harness/mcp.go).tool_call/tool_call_updatenotifications.Tests
TestMCPHelperProcess+TestACPToolLoadOnDemand: the test binary spawns itself as a real stdio MCP server and drives a full ACP turn, asserting that request 0 declares onlytools, request 1 declaresechoaftertools { load: ["echo"] },echoexecutes, the client receives the tool-call updates, and a second turn hasechoevicted.TestMCPToolsCatalogAndVisibility: catalog, load, unknown names, reset.mcpServersparsing and rejection cases.gofmt,go vet,go test ./...and the race detector are clean.Open item
golangci-lintreports onegosecG204 atinternal/harness/mcp.goforexec.Commandon the stdio transport, which is inherent to launching a client-supplied MCP server. It needs a//nolint:gosecor a linter exclusion.Not in scope
session/request_permissionis not bridged; tool calls run without a confirmation prompt.sseandacpMCP transports are not implemented (unsupported servers are logged and skipped).@ -0,0 +414,4 @@func (h *Harness) startMCP(ctx context.Context, servers []acp.McpServer) {all := slices.Concat(h.mcpServers, mcpServersFromACP(ctx, servers))if previous := h.mcp.Swap(newMCPTools(ctx, all)); previous != nil {Fixed in
ebf072f.NewSession/LoadSession/ResumeSessionnow take a turn lock, so replacing and closing the MCP catalog waits for any in-flight prompt turn to finish; a turn can no longer call tools over a connection another request closed. AddedTestSessionChangeWaitsForTurn, which fails (in 0.02s) when the lock is removed and passes with it.Canceldoes not take the lock — the ACP transport cancels the turn context directly, so cancellation cannot deadlock.Documented in the README MCP section: a client-declared stdio server is launched as a subprocess with no confirmation step, so it is safe only when the ACP client is trusted (Paseo spawns brainless as its own child). Kept client-declared stdio because the ACP spec requires every agent to support it; the README recommends restricting stdio to the config allowlist for untrusted clients. The gosec G204 site is unchanged by design — it needs a
//nolint:gosecthat only the repo owner may add.Fixed in
ebf072f: MCP HTTP connection setup and response headers are now bounded by dial/TLS and response-header timeouts. Deliberately nothttp.Client.Timeout, which caps the entire request and would abort a slow tool call or a long-lived server stream.Fixed in
ebf072f: renamed toTestLoadMCPServersandTestLoadRejectsBadMCPServers.Fixed in
ebf072f. The comment now reads: a nil catalog hides every tool, so the model only sees tools once a session has started.Promptalso builds a catalog from the config-file servers when none exists, so a prompt on a persisted session after a restart is no longer left with zero tools.@ -210,2 +210,4 @@}}func TestLoadMCPerservers(t *testing.T) {🟡 SUGGESTION — typo in the test name:
TestLoadMCPerservers(andTestLoadRejectsBadMCPerservers) reads as “MCPerservers”; should be “MCPservers”. Test names surface in failure output, so worth fixing.@ -0,0 +49,4 @@func httpTransport(url string, headers map[string]string) *mcp.StreamableClientTransport {return &mcp.StreamableClientTransport{Endpoint: url,HTTPClient: &http.Client{Transport: headerRoundTripper{headers: headers}},🟡 SUGGESTION —
httpTransportcreates&http.Client{Transport: ...}with noTimeout. A remote MCP server that accepts the connection but never responds blocksConnect/CallTooluntil the request context is cancelled; during a turn the ADK agent context may not be bounded, so a hung endpoint can stall the whole turn. Add aTimeout(e.g.&http.Client{Timeout: 30 * time.Second, Transport: headerRoundTripper{...}}).@ -0,0 +104,4 @@case srv.Stdio != nil:out = append(out, mcpServer{name: srv.Stdio.Name,transport: stdioTransport(srv.Stdio.Command, srv.Stdio.Args, envMap(srv.Stdio.Env)),🟠 IMPORTANT — trust boundary:
mcpServersFromACPbuildsstdioTransport(srv.Stdio.Command, ...)from a wire-supplied field, andstdioTransportruns it viaexec.Command(line 38). Sincesession/request_permissionis not bridged (out of scope here), any client that can reach the ACP endpoint and sendsession/newwith anmcpServersentry gets arbitrary command execution in the brainless process immediately on session start — no model mediation, no confirmation. This widens the boundary beyond prompt-only control.If the ACP client (Paseo) is fully trusted and unreachable by others, this is acceptable; otherwise it is RCE. Fix options: restrict client-declared stdio
commandto a config-file allowlist (use ACP servers only forhttp), gate it behind a config flag, or document the trust assumption in the README next to the example. This is also the gosec G204 site you flagged — a scoped//nolint:gosecnaming the trust boundary is fine, but the boundary itself should be deliberate.@ -0,0 +414,4 @@func (h *Harness) startMCP(ctx context.Context, servers []acp.McpServer) {all := slices.Concat(h.mcpServers, mcpServersFromACP(ctx, servers))if previous := h.mcp.Swap(newMCPTools(ctx, all)); previous != nil {🟠 IMPORTANT — concurrency/lifecycle race:
startMCPdoesh.mcp.Swap(newMCPTools(...))thenprevious.close(), which callssession.Close()on every MCP ClientSession in the replaced catalog. MeanwhilePrompt(harness.go:321) runsh.runner.Run(...)for the whole turn with no lock held, andmcpTool.Run(~mcp.go:290) callst.session.CallToolon exactly those sessions.h.muguards onlyconn/session/cwd, not the catalog or the turn lifecycle. So if the client starts/loads/resumes another session while a turn is in flight (e.g.session/cancelthen an immediate new session — note the existingponytail:comment admits a canceled turn's model call can still be in flight), the running turn's MCP tool call hits a closed connection and errors, andpruneTools(registry.go:257) reads whichever catalog is current mid-turn, so visibility flips mid-turn.Condition to fail: any NewSession/LoadSession/ResumeSession arriving while a Prompt turn is mid-flight.
Fix: synchronize session changes against running turns — hold
h.mu(or a dedicated turn lock) across therunner.Runloop, or refcount the catalog and deferclose()until no active turn references it.@ -217,2 +218,4 @@reg *Registrysel *selection// mcp is the harness's active-session tool catalog; when nil (as in unit// tests) no tool pruning happens.🟡 SUGGESTION — the comment “when nil (as in unit tests) no tool pruning happens” is misleading. The guard only skips when the
m.mcppointer itself is nil (unit tests). In productionm.mcpis always non-nil (&harness.mcp), sopruneTools(req, m.mcp.Load())always runs; when the loaded catalog is nil (nostartMCPyet in this process)pruneToolsprunes all tools, including thetoolsstub — the opposite of “no pruning”. Practical edge:Prompton a persisted session id without a preceding NewSession/LoadSession/ResumeSession in-process (e.g. resuming directly after a restart, catalog never rebuilt) silently leaves the model with zero tools. Recommend rewording the comment to match behavior and/or callingstartMCPfromPromptwhen the catalog is nil.Code review — PR #12 (feat: expose MCP tools on demand)
Reviewed against the samber/cc-skills-golang skill set (code style, naming, docs, error handling, safety, concurrency, security, dependencies, testing, performance, observability, modernize).
Verdict: solid, well-tested PR; no BLOCKING issues found. Two IMPORTANT items should be addressed before merge, plus a few suggestions. Posted as a COMMENT review (the review token is the PR author, which Forgejo does not allow to request changes on its own PR).
What's good
UnmarshalJSONconfig decoding and table-driven rejection tests are clean and idiomatic.toolsstub, andpruneToolsimplement the on-demand design correctly; the e2e test genuinely drives the real stdio transport via the self-spawning helper process and asserts the load/evict round-trip.go.sumcommitted; only new direct dep is the officialmodelcontextprotocol/go-sdk v1.7.0— actively maintained, no known CVEs, noreplacedirectives.newMCPTools(a bad server is logged and skipped) is a nice touch.🟠 IMPORTANT (inline)
startMCPswaps andclose()s the previous session's MCP client sessions with no synchronization against an in-flightPromptturn, which may still be calling tools on those sessions (the existingponytail:comment even acknowledges a canceled turn's model call outlives the turn).h.mudoes not cover the catalog or turn lifecycle. Fix: serialize session changes against running turns, or refcount the catalog and defer close until the last turn referencing it ends.commandruns viaexec.Commandwith no permission bridge, so any client able to sendsession/newgets arbitrary command execution on session start. Acceptable only if the ACP client is fully trusted; otherwise restrict to a config-file allowlist or gate it.🟡 SUGGESTION (inline)
http.Clientfor the http transport has noTimeout; a hung endpoint can stall a turn indefinitely.TestLoadMCPerservers→TestLoadMCPservers).pruneToolspruning all tools when the catalog is nil; also worth covering the resume-after-restart path where the catalog is never rebuilt and the model gets zero tools.Review responses — all five addressed in
ebf072fstartMCPcloses sessions under a running turn)NewSession/LoadSession/ResumeSessiontake a turn lock, so the catalog swap andclose()wait for any in-flight prompt turn. NewTestSessionChangeWaitsForTurnfails in 0.02s with the lock removed and passes with it.Canceldoes not take the lock (the ACP transport cancels the turn context directly), so cancellation cannot deadlock.http.Client.Timeout(which would abort slow tool calls or a long-lived server stream).TestLoadMCPServers,TestLoadRejectsBadMCPServers.mcpcomment / zero tools after restartPromptnow builds a catalog from the config-file servers when none exists.gofmt,go vet,go test ./..., and the race detector are clean.golangci-lintstill reports the single knowngosecG204 atinternal/harness/mcp.go(theexec.Commandsite covered by item 2); the repo owner needs to add the//nolint:gosecor a linter exclusion.The review threads could not be marked resolved through the API — this Forgejo version exposes no resolve-conversation route (
/repos/{owner}/{repo}/pulls/{index}/reviews/{id}/comments/{comment}has only get/delete). They need resolving in the UI.Review summary
Solid, well-scoped PR. The lazy-tool design is clean: a
toolsstub up front,pruneToolsfiltering packed schemas per round, andturnMuserializing session changes against in-flight turns so the MCP catalog is never closed under a running turn. Concurrency handling (atomic pointer swap + mutex, no lock-order cycle betweenturnMuandmu) is sound, and the tests are genuinely good — the self-spawning stdio helper, the scripted model server, and the end-to-end turn assertions cover the design well. The README trust-boundary section is exactly the right call.Two IMPORTANT issues (no BLOCKING ones found):
turnMu— a hung client-supplied or config stdio server wedges the entire agent (all prompts + session changes block forever). HTTP is bounded by the dial/header timeouts; stdio is not.Plus two minor suggestions (header leak on redirects, warn log missing server name). Recommend addressing at least the two IMPORTANT items before merge.
@ -0,0 +196,4 @@for _, srv := range servers {client := mcp.NewClient(&mcp.Implementation{Name: appName, Version: "0.0.1"}, nil)session, err := client.Connect(ctx, srv.transport, nil)Fixed in
feaf951. Two changes:context.WithTimeout(ctx, mcpConnectTimeout)(15s), so a server that starts but never answers is skipped instead of blocking. The go-sdk'sCommandTransport.Connectdoes not bind the session to the passed context (its listen loops usecontext.Background()), so the deadline only bounds the handshake — verified by the existing stdio e2e test still passing.startMCPnow builds the catalog before takingturnMu, so even a slow-but-successful connect cannot block session changes; only the swap and close are serialized.Regression test
TestNewMCPToolsBoundsHungServeruses a transport that accepts and never answers: 0.2s with the bound, 10.0s and failing without it. ThePromptfallback still builds underturnMu, but it is now bounded by the same timeout.Fixed in
feaf951by implementing the documented contract rather than weakening the docs.mergeServersdrops any config-file server whose name a session server declares, so only the session server is connected and its tools win; the README and theFile.MCPServerscomment are now accurate. Covered byTestMergeServersSessionOverridesConfig, which asserts the survivingsharedentry carries the session-declared endpoint.Fixed in
feaf951. The MCP HTTP client now setsCheckRedirectto refuse a redirect to a different host (same-host redirects still follow).CheckRedirectruns before the nextRoundTrip, so the configured headers are never re-injected on a cross-origin hop.Fixed in
feaf951. The warning now carriesserverandtransportattributes, resolved from whichever variant the client declared (acpServerIdentity), so a skippedsse/acpentry says which server it was and what it asked for.@ -0,0 +83,4 @@base http.RoundTripper}func (h headerRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {🟡 SUGGESTION — configured headers (incl.
Authorization) are applied to every request the RoundTripper sees, including redirect hops.http.Clientfollows 3xx redirects by default, and eachRoundTripclones and re-injects the header set, so if the MCP endpoint redirects (e.g. to another origin) the auth header goes along. Fails when: a configuredhttpserver issues a redirect. Fix: scope header injection to the original host — e.g. compareclone.URL.Hostagainst the transport's configured endpoint and skip headers on other hosts, or setCheckRedirectto refuse cross-host redirects.@ -0,0 +145,4 @@transport: httpTransport(srv.Http.Url, headerMap(srv.Http.Headers)),})default:mcpLogger().WarnContext(ctx, "ignoring unsupported mcp transport (only stdio and http are supported)")🟡 SUGGESTION — unsupported-transport warning omits the offending server. The
WarnContexthere says only that an unsupported transport was ignored, with no server name or transport value, so a client that sends ansse/acpentry is hard to diagnose in logs. Fix: add the server name and the transport to the structured log, e.g.slog.String("server", srv.Name)and the transport identifier.@ -0,0 +196,4 @@for _, srv := range servers {client := mcp.NewClient(&mcp.Implementation{Name: appName, Version: "0.0.1"}, nil)session, err := client.Connect(ctx, srv.transport, nil)🟠 IMPORTANT — stdio MCP connect is unbounded and runs under
turnMu.startMCPholdsturnMuwhile callingnewMCPTools, andclient.Connectdoes the subprocess spawn +initializehandshake synchronously.mcp.CommandTransport.Connectstarts the process with no timeout, and the handshake blocks until the peer answers or the request context is cancelled. HTTP is bounded bymcpDialTimeout/mcpHeaderTimeout(10s/30s); stdio has nothing.Fails when: a
stdioserver's process starts but never answersinitialize(hung/misbehaving command, e.g. a client-supplied server that waits on input).Connectblocks,turnMuis held, and everyPromptand session change (New/Load/Resume) blocks indefinitely — the whole agent wedges. This same unbounded connect is also hit from thePromptfallbackh.setMCP(ctx, nil)on a resumed-after-restart session.Fix: bound the connect/handshake with a deadline (e.g. wrap in
context.WithTimeout(ctx, mcpDialTimeout)per server) and/or connect/build the catalog outside the critical section so a slow connect can't holdturnMu. Note the SDK reuses the passed ctx for the handshake, so a per-server timeout is straightforward.@ -0,0 +455,4 @@// setMCP replaces the active catalog, closing the previous one. Callers must// hold turnMu.func (h *Harness) setMCP(ctx context.Context, servers []acp.McpServer) {all := slices.Concat(h.mcpServers, mcpServersFromACP(ctx, servers))🟠 IMPORTANT — documented 'session server overrides config-file server' is not implemented.
setMCPconcatenates config servers first, then ACP servers, andnewMCPToolsregisters tools first-wins (// first server with a given tool name wins). So for a server with the same display name in both config and the ACPmcpServers, the config server is connected first and its tools win — the opposite of what the README ('A session server with the same name overrides the config-file one') and theFile.MCPServerscomment promise. Both servers are also connected (two subprocesses for same-named stdio servers).Fails when: a client declares a server name that also exists in
brainless.json— the operator expects the client's config to take effect, but the config-file one is used.Fix: either implement the override (dedup by server name before connecting, dropping the config entry when a session server shares the name) or fix the docs/comments to state that config wins.
Second review round — all four addressed in
feaf951turnMucontext.WithTimeout(ctx, mcpConnectTimeout)(15s) around connect + listing, and the catalog is now built before takingturnMu, so neither a hung nor a slow server can block session changes. NewTestNewMCPToolsBoundsHungServertakes 10.0s and fails without the bound, 0.2s with it.mergeServersdrops the config-file entry when a session server shares its name, so only the session server connects. NewTestMergeServersSessionOverridesConfig.CheckRedirectnow refuses cross-host redirects.serverandtransportattributes.gofmt,go vet,go test ./..., and the race detector are clean.golangci-lintstill reports only the knowngosecG204 atinternal/harness/mcp.go— that one needs the repo owner's//nolint:gosecor a linter exclusion, since it is the deliberate stdio launch site documented under the README trust boundary.I have not re-triggered the review; the PR is ready for another look whenever you want to label it.