Documentation
¶
Overview ¶
Package mcp implements FR-MCP-01/02/03's agent-native layer: a hand-rolled JSON-RPC 2.0 server speaking the Model Context Protocol over stdio (no third-party SDK — see go.mod's dependency-pinning history for why this project prefers stdlib-only solutions). It knows nothing about scenarios, protocols, or the engine itself: every tool it registers is a thin wrapper that shells out to the compiled vegaload binary (see exec.go's RunCLI) and parses that command's own -output json result, per AGENTS.md's module-boundary rule — "the MCP layer must not call core-engine functions directly" and "every MCP tool maps to the same underlying CLI command a human can run directly."
Index ¶
Constants ¶
This section is empty.
Variables ¶
var CoreToolNames = []string{
"create_scenario",
"run_test",
"get_results",
"suggest_thresholds",
"diagnose_failure",
"compare_reports",
"generate_from_spec",
"validate_scenario",
}
CoreToolNames are the tools every VegaLoad MCP server must expose (FR-MCP-03). `vegaload doctor` checks a host's live server against this list; a test keeps it in step with NewTools.
Functions ¶
func IsLoopbackHost ¶ added in v0.5.0
IsLoopbackHost reports whether host is localhost or a loopback IP.
func RunCLI ¶
RunCLI runs the vegaload binary at exePath with args and returns its stdout. This is the only way any tool in this package touches vegaload's actual behavior: it shells out to the same binary a human would run from their own shell, which is what structurally guarantees AGENTS.md's module-boundary rule ("the MCP layer must not call core-engine functions directly") rather than relying on code-review discipline to keep it true. exePath is resolved once at server startup (cmd/vegaload/mcp.go calls os.Executable()) and threaded through every tool's closure — this function takes it as a parameter, rather than calling os.Executable() itself, purely so tests can point it at a stand-in script instead of the real binary.
A non-zero exit is reported as an error that includes stderr, since every vegaload subcommand writes its own error messages there.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server dispatches JSON-RPC 2.0 requests read from a stdio transport to registered Tools. It has no fields beyond the tool registry: it holds no run state of its own, since every tool call is a fresh subprocess invocation of the vegaload binary (RunCLI) that does its own bookkeeping (audit log, report files) exactly as a human-run CLI command would.
func NewServer ¶
func NewServer() *Server
NewServer returns a Server with no tools registered; call Register for each tool before Serve.
func (*Server) HTTPHandler ¶ added in v0.5.0
HTTPHandler returns an http.Handler that serves this MCP server over HTTP (FR-MCP-02's optional HTTP/SSE transport). It offers two ways in:
- POST /mcp takes one JSON-RPC message and answers with the JSON-RPC response in the body (202 with no body for a notification). This is the simple path for scripts and for clients that do not need a stream.
- GET /sse opens a Server-Sent Events stream, the transport of MCP protocol version 2024-11-05. The first event, "endpoint", names the URL to POST messages to (/message?sessionId=...). Each response is sent back on the stream as a "message" event.
When token is not empty, every request must carry "Authorization: Bearer <token>". Requests with an Origin header that is not a loopback host are refused unless allowOrigin matches it, so a web page in the user's browser cannot reach a local server (DNS rebinding).
func (*Server) Register ¶
Register adds t to the server's tool set. Registering two tools with the same Name replaces the earlier one, which is useful for tests but not expected in normal use (cmd/vegaload/mcp.go registers each real tool name exactly once).
func (*Server) Serve ¶
Serve reads newline-delimited JSON-RPC 2.0 messages from r and writes responses to w — MCP's stdio transport, which (unlike LSP) uses a bare newline as the message delimiter rather than Content-Length framing. It runs until r is exhausted (EOF, the normal way an MCP client ends the session by closing the subprocess's stdin) or ctx is done.
type Tool ¶
type Tool struct {
Name string
Description string
InputSchema map[string]any
Handler func(ctx context.Context, arguments json.RawMessage) (any, error)
}
Tool is one MCP tool: a name and JSON-schema-shaped description an MCP client (Cursor, Claude Code, any other MCP host) shows an LLM, and a Handler that does the actual work when the LLM calls it. Handler receives the call's "arguments" object exactly as the client sent it (unparsed, so each tool decides its own shape) and returns any value JSON-encodable as the tool's result, or an error — which the server reports back as a tool-level failure (isError: true), not a transport-level JSON-RPC error, since a bad or failing run is a perfectly normal thing for an agent to see and react to.
func NewTools ¶
NewTools returns FR-MCP-03's tool set, each one a thin wrapper around RunCLI(ctx, exePath, ...) — the exact args a human would type at their own shell. exePath is resolved once by the caller (normally os.Executable(), done in cmd/vegaload/mcp.go) and closed over by every handler below.