Help us shape the future of Go! Take the 2026 Go Developer Survey

mcpserver

package
v1.9.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mcpserver exposes Gopherstack's admin APIs as Model Context Protocol tools.

Index

Constants

This section is empty.

Variables

View Source
var ErrBackend = errors.New("gopherstack admin API error")

ErrBackend is returned when the Gopherstack admin API rejects a call.

Functions

func Auth

func Auth(token string, next http.Handler) http.Handler

Auth guards next with a bearer token, or with a loopback-only check when token is empty.

func New

func New(opts Options) *mcp.Server

New builds an MCP server whose tools call the admin API reachable through opts.Doer.

func NewHTTPHandler

func NewHTTPHandler(opts Options, token string) http.Handler

NewHTTPHandler serves the streamable-HTTP MCP transport behind Auth.

With a non-empty token every request must carry it as a Bearer credential. Without one, only loopback clients are accepted.

func ServeStdio

func ServeStdio(ctx context.Context, s *mcp.Server, t mcp.Transport) error

ServeStdio serves s over t until the client disconnects or ctx ends.

Types

type DataOutput

type DataOutput struct {
	Data any `json:"data"`
}

DataOutput wraps a JSON document returned by the admin API.

type Doer

type Doer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer executes an HTTP request against a Gopherstack instance.

func HandlerDoer

func HandlerDoer(h http.Handler) Doer

HandlerDoer returns a Doer that dispatches requests straight into h.

type FaultError

type FaultError struct {
	Code       string `json:"code"       jsonschema:"AWS error code, e.g. ThrottlingException"`
	StatusCode int    `json:"statusCode" jsonschema:"HTTP status code, e.g. 429"`
}

FaultError is the error a fault rule injects.

type FaultRule

type FaultRule struct {
	Error       *FaultError `json:"error,omitempty"       jsonschema:"injected error (default 503 ServiceUnavailable)"`
	Probability *float64    `json:"probability,omitempty" jsonschema:"firing probability 0..1 (default 1)"`
	Service     string      `json:"service,omitempty"     jsonschema:"service name to match, e.g. dynamodb"`
	Region      string      `json:"region,omitempty"      jsonschema:"region to match"`
	Operation   string      `json:"operation,omitempty"   jsonschema:"operation name to match, e.g. PutItem"`
}

FaultRule is one chaos fault; omitted match fields match everything.

type FaultsClearInput

type FaultsClearInput struct{}

FaultsClearInput is the (empty) input of chaos_clear_faults.

type FaultsListInput

type FaultsListInput struct{}

FaultsListInput is the (empty) input of chaos_list_faults.

type FaultsOutput

type FaultsOutput struct {
	Rules []FaultRule `json:"rules"`
}

FaultsOutput lists the active chaos fault rules.

type FaultsSetInput

type FaultsSetInput struct {
	Rules  []FaultRule `json:"rules"            jsonschema:"fault rules; evaluated in order, first match wins"`
	Append bool        `json:"append,omitempty" jsonschema:"append to existing rules instead of replacing them"`
}

FaultsSetInput sets chaos fault rules.

type HealthInput

type HealthInput struct{}

HealthInput is the (empty) input of gopherstack_health.

type HealthOutput

type HealthOutput struct {
	Status        string   `json:"status"`
	Version       string   `json:"version"`
	Services      []string `json:"services"`
	Disabled      []string `json:"disabled,omitempty"`
	UptimeSeconds int64    `json:"uptime_seconds"`
	Goroutines    int      `json:"goroutines"`
}

HealthOutput reports the running instance's identity and enabled services.

type IAMDenialsInput

type IAMDenialsInput struct {
	Service   string `json:"service,omitempty"   jsonschema:"only this service"`
	Principal string `json:"principal,omitempty" jsonschema:"only this principal ARN"`
	Since     string `json:"since,omitempty"     jsonschema:"RFC3339 time or a duration such as 5m"`
	Limit     int    `json:"limit,omitempty"     jsonschema:"max events, 1-500 (default 50)"`
}

IAMDenialsInput filters IAM policy-evaluation denials.

type IAMDenialsOutput

type IAMDenialsOutput struct {
	Events  []map[string]any `json:"events"`
	Dropped int64            `json:"dropped"`
}

IAMDenialsOutput lists denied evaluations from the IAM policy stream.

type InitHooksInput

type InitHooksInput struct{}

InitHooksInput is the (empty) input of init_hooks_list.

type InitHooksRunInput

type InitHooksRunInput struct {
	Stage  string `json:"stage"            jsonschema:"BOOT, START, READY or SHUTDOWN"`
	Script string `json:"script,omitempty" jsonschema:"script file name from init_hooks_list (default: whole stage)"`
}

InitHooksRunInput selects registered init hook scripts to run.

type Options

type Options struct {
	Doer    Doer
	BaseURL string
	Version string
	// ReadOnly omits every tool that can change state.
	ReadOnly bool
}

Options configures a Gopherstack MCP server.

func InProcessOptions

func InProcessOptions(admin http.Handler, version string) Options

InProcessOptions returns Options for a server mounted inside the Gopherstack process.

type ResetInput

type ResetInput struct {
	Service string `json:"service,omitempty" jsonschema:"only reset this service (default: every service)"`
}

ResetInput scopes a state reset.

type SnapshotDeleteInput

type SnapshotDeleteInput struct {
	Name    string `json:"name"              jsonschema:"snapshot name"`
	Version string `json:"version,omitempty" jsonschema:"version to delete (default: all versions)"`
}

SnapshotDeleteInput selects a snapshot (version) to delete.

type SnapshotListInput

type SnapshotListInput struct{}

SnapshotListInput is the (empty) input of snapshot_list.

type SnapshotLoadInput

type SnapshotLoadInput struct {
	Name     string   `json:"name"               jsonschema:"snapshot name"`
	Version  string   `json:"version,omitempty"  jsonschema:"version number or 'latest' (default latest)"`
	Strategy string   `json:"strategy,omitempty" jsonschema:"overwrite (default) or service-merge"`
	Services []string `json:"services,omitempty" jsonschema:"only load these services (default: all in the snapshot)"`
	Merge    bool     `json:"merge,omitempty"    jsonschema:"merge into existing state instead of replacing it"`
}

SnapshotLoadInput selects a snapshot version to restore.

type SnapshotSaveInput

type SnapshotSaveInput struct {
	Name     string   `json:"name"               jsonschema:"snapshot name (a new version is created if it exists)"`
	Message  string   `json:"message,omitempty"  jsonschema:"optional version message"`
	Services []string `json:"services,omitempty" jsonschema:"only save these services (default: all)"`
}

SnapshotSaveInput names a snapshot to save.

type StatusOutput

type StatusOutput struct {
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

StatusOutput confirms a state-changing operation.

type Trace

type Trace struct {
	Timestamp    time.Time `json:"timestamp"`
	ID           string    `json:"id"`
	Method       string    `json:"method"`
	Path         string    `json:"path"`
	Query        string    `json:"query,omitempty"`
	Service      string    `json:"service,omitempty"`
	Operation    string    `json:"operation,omitempty"`
	ErrorCode    string    `json:"error_code,omitempty"`
	ErrorMessage string    `json:"error_message,omitempty"`
	Status       int       `json:"status"`
	DurationMS   int64     `json:"duration_ms"`
}

Trace is a redacted summary of one captured request (no headers or bodies).

type TracesInput

type TracesInput struct {
	Service   string `json:"service,omitempty"   jsonschema:"only this service, e.g. s3"`
	Operation string `json:"operation,omitempty" jsonschema:"only this operation name, e.g. PutObject (case-insensitive)"`
	Status    string `json:"status,omitempty"    jsonschema:"status code like 500, class like 4xx, or 'failed' (>=400)"`
	Limit     int    `json:"limit,omitempty"     jsonschema:"max traces to return, 1-100 (default 20)"`
}

TracesInput filters recent request traces.

type TracesOutput

type TracesOutput struct {
	Traces []Trace `json:"traces"`
}

TracesOutput lists traces, newest first.

Jump to

Keyboard shortcuts

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