commit 26674a500a818d272b2d5bd0609bbfc51a7b3f5b Author: Virgil Date: Wed Mar 11 12:14:37 2026 +0000 Add wiki pages diff --git a/Go-Architecture.md b/Go-Architecture.md new file mode 100644 index 0000000..af8384d --- /dev/null +++ b/Go-Architecture.md @@ -0,0 +1,129 @@ +# Go Architecture + +Module: `forge.lthn.ai/core/mcp` + +## Dependencies + +Direct: `core/cli`, `core/go`, `go-ai`, `go-api`, `go-i18n`, `go-inference`, `go-io`, `go-log`, `go-ml`, `go-process`, `go-rag`, `go-webview`, `go-ws`, `gin-gonic/gin`, `gorilla/websocket`, `modelcontextprotocol/go-sdk`, `testify`. + +## pkg/mcp — MCP Service + +### Service + +```go +type Service struct { + server *mcp.Server + workspaceRoot string + medium io.Medium + subsystems []Subsystem + logger *log.Logger + processService *process.Service + wsHub *ws.Hub + tools []ToolRecord +} +``` + +Created via `New(opts ...Option) (*Service, error)`. Defaults to CWD with sandboxed filesystem. + +### Options + +- `WithWorkspaceRoot(root)` — restrict file ops to directory (empty = unrestricted). +- `WithSubsystem(sub)` — register additional tool provider. +- `WithProcessService(ps)` — enable process management tools. +- `WithWSHub(hub)` — enable WebSocket streaming tools. + +### Transport + +- `Run(ctx)` — stdio transport (default), or TCP when `MCP_ADDR` env is set. +- `ServeTCP(ctx, addr)` — TCP transport. + +### Subsystem Interface + +```go +type Subsystem interface { + Name() string + RegisterTools(server *mcp.Server) +} + +type SubsystemWithShutdown interface { + Subsystem + Shutdown(ctx context.Context) error +} +``` + +Subsystems register tools during `New()`. The `MLSubsystem` is the primary example. + +### Tool Registry + +`ToolRecord` captures metadata for each registered tool: + +```go +type ToolRecord struct { + Name string + Description string + Group string + InputSchema map[string]any // JSON Schema from struct reflection + OutputSchema map[string]any + RESTHandler RESTHandler +} +``` + +`addToolRecorded[In, Out]()` registers tools with both the MCP server and the parallel registry. The `RESTHandler` closure unmarshals JSON to the correct input type, enabling the MCP-to-REST bridge. + +### MCP-to-REST Bridge + +`BridgeToAPI(svc, bridge)` populates a `go-api.ToolBridge` from recorded tools. Each tool becomes a POST endpoint with standard `api.Response` envelope. JSON parse errors return 400; tool errors return 500. + +## Tool Implementations + +### Files (built-in) + +10 tools for sandboxed filesystem operations. All paths validated against workspace root via `io.Medium`. Input/Output types: `ReadFileInput/Output`, `WriteFileInput/Output`, `EditDiffInput/Output`, etc. + +### Process Management + +6 tools wrapping `go-process.Service`. Requires `WithProcessService()`. Security-logged tool executions. Types: `ProcessStartInput/Output`, `ProcessListOutput` with `ProcessInfo` structs. + +### RAG + +3 tools wrapping `go-rag`. Defaults: collection=`hostuk-docs`, topK=5. +- `rag_query` — semantic search via `rag.QueryDocs()`. +- `rag_ingest` — ingest file or directory via `rag.IngestSingleFile()`/`rag.IngestDirectory()`. +- `rag_collections` — list Qdrant collections with optional stats. + +### ML (Subsystem) + +`MLSubsystem` implements `Subsystem`. Wraps `go-ml.Service`. + +5 tools: +- `ml_generate` — text generation via `ml.Service.Generate()` routing through `inference.TextModel`. +- `ml_score` — heuristic + semantic scoring. Suites: `heuristic`, `semantic`, `content`. +- `ml_probe` — capability probes by category. +- `ml_status` — InfluxDB training/generation status. +- `ml_backends` — lists inference backends from `inference.List()`. + +### Metrics + +2 tools for AI/security event tracking. Events stored in daily JSONL files via `go-ai.Record()`. +- `metrics_record` — record event (type, agent_id, repo, data). +- `metrics_query` — query events with time range (e.g. `7d`, `24h`), aggregated by type/repo/agent. + +### Webview + +10 tools for Chrome DevTools Protocol automation via `go-webview`. Requires `webview_connect` first. +- Navigation, clicking, typing, DOM queries, console capture, JS evaluation, screenshots, wait-for-selector. + +### WebSocket + +2 tools for real-time streaming. Requires `WithWSHub()`. +- `ws_start` — start HTTP server with WebSocket endpoint. +- `ws_info` — hub statistics (clients, channels). +- `ProcessEventCallback` — forwards process output/status to WebSocket subscribers. + +## CLI Entry Points + +| Path | Description | +|------|-------------| +| `cmd/core-mcp/` | Standalone `core-mcp` binary | +| `cmd/mcpcmd/` | Subcommand registration for `core` CLI | +| `cmd/brain-seed/` | Brain seeding utility | diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..f60f2e0 --- /dev/null +++ b/Home.md @@ -0,0 +1,33 @@ +# MCP + +Module: `forge.lthn.ai/core/mcp` +Composer: `lthn/mcp` +Binary: `core-mcp` + +Model Context Protocol server exposing tools for file operations, process management, ML inference, RAG vector queries, webview automation, WebSocket streaming, and metrics. The Go side implements the MCP server with a subsystem plugin architecture and MCP-to-REST bridge. The PHP side provides a Laravel MCP module with tool registration, context services, and admin UI. + +## Architecture + +The Go `Service` wraps `modelcontextprotocol/go-sdk/mcp.Server` and adds: +- Sandboxed filesystem via `go-io.Medium` +- Subsystem plugin system (`Subsystem` interface) for extending tool sets +- Tool registry with JSON Schema extraction and REST bridge generation +- Transport: stdio (default) or TCP (when `MCP_ADDR` is set) + +## Tool Groups + +| Group | Tools | Source | +|-------|-------|--------| +| files | file_read, file_write, file_delete, file_rename, file_exists, file_edit, dir_list, dir_create | mcp.go (built-in) | +| language | lang_detect, lang_list | mcp.go (built-in) | +| process | process_start, process_stop, process_kill, process_list, process_output, process_input | tools_process.go | +| rag | rag_query, rag_ingest, rag_collections | tools_rag.go | +| ml | ml_generate, ml_score, ml_probe, ml_status, ml_backends | tools_ml.go (MLSubsystem) | +| metrics | metrics_record, metrics_query | tools_metrics.go | +| webview | webview_connect/disconnect, navigate, click, type, query, console, eval, screenshot, wait | tools_webview.go | +| ws | ws_start, ws_info | tools_ws.go | + +## Topic Pages + +- [Go-Architecture](Go-Architecture) — Go service, subsystem API, transport, bridge +- [PHP-Package](PHP-Package) — Laravel MCP module diff --git a/PHP-Package.md b/PHP-Package.md new file mode 100644 index 0000000..8beaff2 --- /dev/null +++ b/PHP-Package.md @@ -0,0 +1,58 @@ +# PHP Package + +Composer: `lthn/mcp` +Provider: `Core\Front\Mcp\Boot` + +## Namespaces + +| Namespace | Description | +|-----------|-------------| +| `Core\Mcp\` | Core MCP services and types | +| `Core\Website\Mcp\` | Website-facing MCP endpoints | +| `Core\Front\Mcp\` | Front-end Boot provider | + +## Structure + +``` +src/php/ + src/ + Mcp/ + Boot.php + Console/ + Context/ + Controllers/ + Database/ + Dependencies/ + DTO/ + Events/ + Exceptions/ + Lang/ + Listeners/ + Middleware/ + Migrations/ + Models/ + Resources/ + Routes/ + Services/ + Tests/ + Tools/ + View/ + Website/Mcp/ + Front/Mcp/ +``` + +## Key Directories + +- **Tools/** — MCP tool handler implementations for the Laravel MCP endpoint. +- **Services/** — MCP service layer (tool registry, execution, context management). +- **Controllers/** — HTTP controllers for MCP endpoints. +- **Routes/** — API and web route definitions. +- **Models/** — Eloquent models for MCP-related data. +- **Context/** — Context providers for MCP tool execution. +- **DTO/** — Data transfer objects for MCP requests/responses. +- **Middleware/** — Request middleware for MCP endpoints. +- **Events/** / **Listeners/** — Event-driven MCP hooks. + +## Dependencies + +PHP: `lthn/php`.