mcp

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

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

View Source
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

func IsLoopbackHost(host string) bool

IsLoopbackHost reports whether host is localhost or a loopback IP.

func RunCLI

func RunCLI(ctx context.Context, exePath string, args ...string) ([]byte, error)

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

func (s *Server) HTTPHandler(token string, allowOrigin string) http.Handler

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

func (s *Server) Register(t Tool)

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

func (s *Server) Serve(ctx context.Context, r io.Reader, w io.Writer) error

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

func NewTools(exePath string) []Tool

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL