mcp

Documentation

Overview

Package mcp is the AvianSuite MCP server for a Stellar Jay store. It gives agents a small set of outcome-named tools (record, correct and retract facts, read an entity, list and undo changes, checkpoints) over the HTTP API, and it applies the write rules from llm.md so agents do not have to.

The same server runs locally over stdio (cmd/stellarjay-mcp) and hosted over Streamable HTTP (HTTPHandler), where the host decides which store and token each request uses.

Index

• Constants
• Variables
• func WithActor(ctx context.Context, actor string) context.Context
• func WithReadOnly(ctx context.Context, reason string) context.Context
• func WithReceipts(ctx context.Context, receipt func(hash string) string) context.Context
• func WithStoreURL(ctx context.Context, url string) context.Context
• type HTTPOptions
• type RPCError
• type Request
• type Response
• type Server
  • func NewServer() *Server
  • func (s *Server) HTTPHandler(opts HTTPOptions) http.Handler
  • func (s *Server) Handle(ctx context.Context, c *client.Client, req Request) *Response
  • func (s *Server) ServeStdio(ctx context.Context, c *client.Client, in io.Reader, out io.Writer) error

Constants

const (
	// ServerName is the MCP serverInfo name. Agents repeat it, so it is the
	// product name rather than the store's.
	ServerName  = "aviansuite"
	ServerTitle = "AvianSuite"
	// Description is what directories and clients show for the server.
	Description = "" /* 143-byte string literal not displayed */

)

Variables

var ErrUnauthorized = errors.New("unauthorized")

ErrUnauthorized is returned by a ClientFor hook when the request carries no usable credential. HTTPHandler answers it with 401.

var Version = "0.6.0"

Version is reported in serverInfo. Builds may override it.

Functions

func WithActor

func WithActor(ctx context.Context, actor string) context.Context

WithActor sets the actor name this connection's writes are attributed to, which the status tool reports so an agent knows what to pass to undo_changes and list_changes.

func WithReadOnly

func WithReadOnly(ctx context.Context, reason string) context.Context

WithReadOnly makes every write tool refuse with reason, for example when a hosted workspace has expired or is over its storage limit. Reads and undo dry runs still work.

func WithReceipts

func WithReceipts(ctx context.Context, receipt func(hash string) string) context.Context

WithReceipts adds a receipt link to every write result. receipt maps an event hash to a page where a person can see the change and undo it.

func WithStoreURL

func WithStoreURL(ctx context.Context, url string) context.Context

WithStoreURL sets the store address the status tool reports, for example when the client talks to the store over an internal address that agents cannot reach. An empty url leaves the store out of status.

Types

type HTTPOptions

type HTTPOptions struct {
	// ClientFor resolves the store and token for a request, usually from its
	// bearer token. Return ErrUnauthorized (or wrap it) for a 401.
	ClientFor func(*http.Request) (*client.Client, error)
	// WWWAuthenticate is sent with 401 responses, for example
	// `Bearer resource_metadata="https://.../.well-known/oauth-protected-resource"`.
	WWWAuthenticate string
	// WWWAuthenticateFor, when set, builds the 401 challenge per request, for
	// servers reachable under more than one host name.
	WWWAuthenticateFor func(*http.Request) string
	// ContextFor, when set, can add per-request settings such as WithReadOnly
	// and WithReceipts. It runs after ClientFor succeeds.
	ContextFor func(*http.Request, context.Context) context.Context
}

HTTPOptions configure HTTPHandler.

type RPCError

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

RPCError is a JSON-RPC error object.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitempty"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request is a JSON-RPC 2.0 request or notification.

type Response

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"`
	Result  any             `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
}

Response is a JSON-RPC 2.0 response.

type Server

type Server struct {

	// OnInitialize, when set, is told which MCP client connected, from the
	// initialize request's clientInfo.
	OnInitialize func(ctx context.Context, clientName, clientVersion string)
	// contains filtered or unexported fields
}

Server answers MCP JSON-RPC messages for one store at a time.

func NewServer

func NewServer() *Server

NewServer returns a server with the AvianSuite tools.

func (*Server) HTTPHandler

func (s *Server) HTTPHandler(opts HTTPOptions) http.Handler

HTTPHandler serves the MCP Streamable HTTP transport with JSON responses. Each POST carries one JSON-RPC message.

func (*Server) Handle

func (s *Server) Handle(ctx context.Context, c *client.Client, req Request) *Response

Handle answers one request against the store behind c. It returns nil for notifications, which get no response.

func (*Server) ServeStdio

func (s *Server) ServeStdio(ctx context.Context, c *client.Client, in io.Reader, out io.Writer) error

ServeStdio reads newline-delimited JSON-RPC from in and writes responses to out until in ends.