refactor: split internal/mcpserver/mcpserver.go into topical files (pure declaration moves)

bare_http_client_allowlist_test.go

@@ -46,7 +46,7 @@ var bareClientAllowlist = map[string]struct {
 	"internal/llamaclient/lanes.go:Client.WithRemoteLanes":       {1, "configured: remote lanes from config"},
 	"internal/llamaclient/lanes.go:FleetLaneGates":               {1, "configured: fleet nodes from delegate_remotes (lane gates)"},
 	"internal/llamaclient/lanes.go:LocalSwapBusy":                {1, "configured: the local llama-swap /running"},
-	"internal/mcpserver/mcpserver.go:localSeatView":              {1, "configured: the local llama-swap (status view)"},
+	"internal/mcpserver/mcpserver_status.go:localSeatView":       {1, "configured: the local llama-swap (status view)"},
 	"internal/mediacap/routeneeds.go:LiveNodeChecker":            {1, "configured: fleet nodes from delegate_remotes (media route readiness)"},
 	"internal/modelaffinity/seatyield.go:<file-scope>":           {1, "configured: the local llama-swap /running and slots (the seat yield after a lease claim)"},
 	"internal/modelaffinity/upstream.go:upstreamResident":        {1, "configured: the local llama-swap /running (the upstream fence)"},

changes/unreleased/refactor-split-mcpserver-file.md

@@ -0,0 +1,5 @@
+### Changed - `internal/mcpserver/mcpserver.go` is split into topical files of the same package
+
+- **What changed.** The 5273-line `mcpserver.go` is now nine files by pure declaration moves: `mcpserver.go` keeps the server, construction, registration and result helpers; `mcpserver_status.go`, `mcpserver_text.go`, `mcpserver_media.go`, `mcpserver_agentrun.go`, `mcpserver_ask.go`, `mcpserver_review.go`, `mcpserver_delegate.go` and `mcpserver_research.go` hold the tool families. No declaration was renamed, edited or reordered inside a body; behaviour is identical.
+- **Why.** One file of 5273 lines hid the tool families from each other and made every change a merge hazard; the package now reads as a set of named parts, and `docs/systems/mcp-server.md` names them.
+- **Check.** Ran the declaration census (`census.go`, which hashes every declaration with comments stripped) on the package before and after: 319 declarations each and an empty diff. `go build ./...`, `go vet ./internal/mcpserver` and gofmt are clean.

docs/systems/mcp-server.md

@@ -1502,8 +1502,15 @@ keep the stamp and say so, a path that is gone is stale without a comparison, an
 
 ## Source map
 
-- [`internal/mcpserver/mcpserver.go`](../../internal/mcpserver/mcpserver.go) — registration and
-  handlers
+- [`internal/mcpserver/mcpserver.go`](../../internal/mcpserver/mcpserver.go) — server construction, session registration, tool registration and the result helpers
+- [`internal/mcpserver/mcpserver_status.go`](../../internal/mcpserver/mcpserver_status.go) — `offload_status` and its local, media, remote, KV-cache, fleet and seat views
+- [`internal/mcpserver/mcpserver_text.go`](../../internal/mcpserver/mcpserver_text.go) — the text and vision handlers and the route schema fragments
+- [`internal/mcpserver/mcpserver_media.go`](../../internal/mcpserver/mcpserver_media.go) — the media handlers (video, transcription, image, graph, SVG, audio, composition)
+- [`internal/mcpserver/mcpserver_agentrun.go`](../../internal/mcpserver/mcpserver_agentrun.go) — `offload_browse`, `offload_nim` and `offload_agent_run` with its admission and result-shaping helpers
+- [`internal/mcpserver/mcpserver_ask.go`](../../internal/mcpserver/mcpserver_ask.go) — `offload_ask`, its grading and its retry
+- [`internal/mcpserver/mcpserver_review.go`](../../internal/mcpserver/mcpserver_review.go) — `offload_review_diff` and the fleet dispatch and payload helpers
+- [`internal/mcpserver/mcpserver_delegate.go`](../../internal/mcpserver/mcpserver_delegate.go) — `offload_agent_delegate`, `offload_agent_rig` and the call deadline
+- [`internal/mcpserver/mcpserver_research.go`](../../internal/mcpserver/mcpserver_research.go) — `offload_research` and its wire types
 - [`internal/mcpserver/reviewdiffio.go`](../../internal/mcpserver/reviewdiffio.go) — the file seam of
   `offload_review_diff`'s `diff_path` branch (working directory, absolute path, confined read), so the refusals behind
   those calls are tested

internal/mcpserver/agentrun_wallgate_defers_test.go

@@ -277,14 +277,27 @@ func TestAgentRunUnknownProfileDeferCarriesTheSizing(t *testing.T) {
 // inside deferSized, which stamps the numbers on whatever deferral it is handed, and
 // once for the answer.
 func TestEveryAgentRunDeferralPastTheWallGateGoesThroughTheSizingStamp(t *testing.T) {
-	src, err := os.ReadFile("mcpserver.go")
+	// mcpserver.go was split into mcpserver_*.go by topic; search every one of them.
+	files, err := filepath.Glob("mcpserver*.go")
 	if err != nil {
-		t.Fatalf("read source: %v", err)
+		t.Fatalf("glob source: %v", err)
 	}
-	text := strings.ReplaceAll(string(src), "\r\n", "\n")
+	var all strings.Builder
+	for _, file := range files {
+		if strings.HasSuffix(file, "_test.go") {
+			continue
+		}
+		src, err := os.ReadFile(file)
+		if err != nil {
+			t.Fatalf("read source: %v", err)
+		}
+		all.Write(src)
+		all.WriteString("\n")
+	}
+	text := strings.ReplaceAll(all.String(), "\r\n", "\n")
 	start := strings.Index(text, "func (s *Server) handleAgentRun(")
 	if start < 0 {
-		t.Fatal("handleAgentRun not found in mcpserver.go")
+		t.Fatal("handleAgentRun not found in mcpserver*.go")
 	}
 	body := text[start:]
 	if end := strings.Index(body, "\n}\n"); end > 0 {

internal/mcpserver/door_test.go

@@ -14,6 +14,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -81,23 +82,33 @@ func TestSummarizeToolStampsItsDoor(t *testing.T) {
 // and nothing about that failure is visible in a passing test suite — which is
 // exactly how all 558 of them accumulated. So the source is the fixture.
 func TestEveryToolHandlerRequestCarriesADoor(t *testing.T) {
-	src, err := os.ReadFile("mcpserver.go")
+	// mcpserver.go was split into mcpserver_*.go by topic; scan every one of them.
+	files, err := filepath.Glob("mcpserver*.go")
 	if err != nil {
-		t.Fatalf("read source: %v", err)
+		t.Fatalf("glob source: %v", err)
 	}
-	lines := strings.Split(string(src), "\n")
 	found := 0
-	for i, ln := range lines {
-		if !strings.Contains(ln, "core.Request{") {
+	for _, file := range files {
+		if strings.HasSuffix(file, "_test.go") {
 			continue
 		}
-		found++
-		// A multi-line literal puts the fields on the following lines; a
-		// one-liner puts them here. Either way the door must be within the
-		// literal's first few lines.
-		window := strings.Join(lines[i:min(i+9, len(lines))], "\n")
-		if !strings.Contains(window, `Door: "offload_`) && !strings.Contains(window, `Door:  "offload_`) {
-			t.Errorf("mcpserver.go:%d builds a core.Request with no MCP-tool Door: %s", i+1, strings.TrimSpace(ln))
+		src, err := os.ReadFile(file)
+		if err != nil {
+			t.Fatalf("read source: %v", err)
+		}
+		lines := strings.Split(string(src), "\n")
+		for i, ln := range lines {
+			if !strings.Contains(ln, "core.Request{") {
+				continue
+			}
+			found++
+			// A multi-line literal puts the fields on the following lines; a
+			// one-liner puts them here. Either way the door must be within the
+			// literal's first few lines.
+			window := strings.Join(lines[i:min(i+9, len(lines))], "\n")
+			if !strings.Contains(window, `Door: "offload_`) && !strings.Contains(window, `Door:  "offload_`) {
+				t.Errorf("%s:%d builds a core.Request with no MCP-tool Door: %s", file, i+1, strings.TrimSpace(ln))
+			}
 		}
 	}
 	if found == 0 {