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",
}
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 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) 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.