Add wiki pages
Virgil
commit
26674a500a
3 changed files with 220 additions and 0 deletions
129
Go-Architecture.md
Normal file
129
Go-Architecture.md
Normal file
|
|
@ -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 |
|
||||
33
Home.md
Normal file
33
Home.md
Normal file
|
|
@ -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
|
||||
58
PHP-Package.md
Normal file
58
PHP-Package.md
Normal file
|
|
@ -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`.
|
||||
Loading…
Add table
Reference in a new issue