From 5177dc391bcc24f9bb8d7872a0c7e8a19dc88fba Mon Sep 17 00:00:00 2001 From: Virgil Date: Mon, 30 Mar 2026 07:52:58 +0000 Subject: [PATCH] docs(mcp): refresh AX migration notes and options references --- docs/architecture.md | 51 ++++++++++++++++++++++---------------------- docs/development.md | 12 +++++++---- pkg/mcp/mcp.go | 2 +- 3 files changed, 34 insertions(+), 31 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index a08808b..f784c80 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -19,14 +19,18 @@ slice of `ToolRecord` metadata that powers the REST bridge. ```go svc, err := mcp.New( - mcp.WithWorkspaceRoot("/home/user/project"), - mcp.WithSubsystem(mcp.NewMLSubsystem(mlService)), - mcp.WithProcessService(processService), - mcp.WithWSHub(wsHub), + mcp.Options{ + WorkspaceRoot: "/home/user/project", + ProcessService: processService, + WSHub: wsHub, + Subsystems: []mcp.Subsystem{ + &MySubsystem{}, + }, + }, ) ``` -Options follow the functional-options pattern. `WithWorkspaceRoot` creates a +Options are provided via the `mcp.Options` DTO. `WorkspaceRoot` creates a sandboxed `io.Medium` that confines all file operations to a single directory tree. Passing an empty string disables sandboxing (not recommended for untrusted clients). @@ -71,7 +75,7 @@ The service registers the following tools at startup: | **ws** | `ws_start`, `ws_info` | `tools_ws.go` | Process and WebSocket tools are conditionally registered -- they require -`WithProcessService` and `WithWSHub` respectively. +`ProcessService` and `WSHub` in `Options` respectively. ### Subsystem interface @@ -93,17 +97,22 @@ type SubsystemWithShutdown interface { } ``` -Two subsystems ship with this repo: +Three subsystems ship with this repo: -#### ML subsystem (`tools_ml.go`) +#### Agentic subsystem (`pkg/mcp/agentic/`) -`MLSubsystem` wraps a `go-ml.Service` and exposes five tools: +`agentic` tools prepare workspaces, dispatch agents, and track execution +status for issue-driven task workflows. -- `ml_generate` -- text generation via any registered inference backend. -- `ml_score` -- heuristic and semantic scoring of prompt/response pairs. -- `ml_probe` -- capability probes (predefined prompts run through the model). -- `ml_status` -- training and generation progress from InfluxDB. -- `ml_backends` -- lists registered inference backends and their availability. +#### Brain subsystem (`pkg/mcp/brain/`) + +Proxies OpenBrain knowledge-store operations to the Laravel backend via the IDE +bridge. Four tools: + +- `brain_remember` -- store a memory (decision, observation, bug, etc.). +- `brain_recall` -- semantic search across stored memories. +- `brain_forget` -- permanently delete a memory. +- `brain_list` -- list memories with filtering (no vector search). #### IDE subsystem (`pkg/mcp/ide/`) @@ -120,16 +129,6 @@ The IDE bridge (`Bridge`) maintains a persistent WebSocket connection to the Laravel backend with exponential-backoff reconnection. Messages are forwarded from Laravel to a local `ws.Hub` for real-time streaming to the IDE frontend. -#### Brain subsystem (`pkg/mcp/brain/`) - -Proxies OpenBrain knowledge-store operations to the Laravel backend via the -IDE bridge. Four tools: - -- `brain_remember` -- store a memory (decision, observation, bug, etc.). -- `brain_recall` -- semantic search across stored memories. -- `brain_forget` -- permanently delete a memory. -- `brain_list` -- list memories with filtering (no vector search). - ### Transports The Go server supports three transports, all using line-delimited JSON-RPC: @@ -141,8 +140,8 @@ The Go server supports three transports, all using line-delimited JSON-RPC: | **Unix** | `ServeUnix(ctx, path)` | caller-specified socket path | TCP binds to `127.0.0.1` by default when the host component is empty. Binding -to `0.0.0.0` emits a security warning. Each accepted connection spawns a -fresh `mcp.Server` instance with its own tool set. +to `0.0.0.0` emits a security warning. Each accepted connection becomes a +session on the shared `mcp.Server`. ### REST bridge diff --git a/docs/development.md b/docs/development.md index 03d34fb..3424254 100644 --- a/docs/development.md +++ b/docs/development.md @@ -93,7 +93,7 @@ Key test files: | `transport_tcp_test.go` | TCP transport, loopback default, `0.0.0.0` warning | | `transport_e2e_test.go` | End-to-end TCP client/server round-trip | | `tools_metrics_test.go` | Duration parsing, metrics record/query | -| `tools_ml_test.go` | ML subsystem tool registration | +| `brain/brain_test.go` | Brain subsystem registration and bridge-nil handling | | `tools_process_test.go` | Process start/stop/kill/list/output/input | | `tools_process_ci_test.go` | CI-safe process tests (no external binaries) | | `tools_rag_test.go` | RAG query/ingest/collections | @@ -170,17 +170,17 @@ core/mcp/ | +-- mcp/ | +-- mcp.go # Service, file tools, Run() | +-- registry.go # ToolRecord, addToolRecorded, schema extraction -| +-- subsystem.go # Subsystem interface, WithSubsystem option +| +-- subsystem.go # Subsystem interface, Options-based registration | +-- bridge.go # BridgeToAPI (MCP-to-REST adapter) | +-- transport_stdio.go | +-- transport_tcp.go | +-- transport_unix.go | +-- tools_metrics.go # Metrics record/query -| +-- tools_ml.go # MLSubsystem (generate, score, probe, status, backends) | +-- tools_process.go # Process management tools | +-- tools_rag.go # RAG query/ingest/collections | +-- tools_webview.go # Chrome DevTools automation | +-- tools_ws.go # WebSocket server tools +| +-- agentic/ | +-- brain/ | | +-- brain.go # Brain subsystem | | +-- tools.go # remember/recall/forget/list tools @@ -321,7 +321,11 @@ func (s *Subsystem) RegisterTools(server *mcp.Server) { 2. Register when creating the service: ```go -mcp.New(mcp.WithSubsystem(&mysubsystem.Subsystem{})) +mcp.New(mcp.Options{ + Subsystems: []mcp.Subsystem{ + &mysubsystem.Subsystem{}, + }, +}) ``` ## Adding a new PHP tool diff --git a/pkg/mcp/mcp.go b/pkg/mcp/mcp.go index 56694d6..785fe9c 100644 --- a/pkg/mcp/mcp.go +++ b/pkg/mcp/mcp.go @@ -31,7 +31,7 @@ type Service struct { server *mcp.Server workspaceRoot string // Root directory for file operations (empty = unrestricted) medium io.Medium // Filesystem medium for sandboxed operations - subsystems []Subsystem // Additional subsystems registered via WithSubsystem + subsystems []Subsystem // Additional subsystems registered via Options.Subsystems logger *log.Logger // Logger for tool execution auditing processService *process.Service // Process management service (optional) wsHub *ws.Hub // WebSocket hub for real-time streaming (optional)