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

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

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:

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