mcp

package
v0.3.3 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: GPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package mcp serves Ether's tool catalogue over MCP streamable HTTP at /ether/mcp (SPEC §5.12), plus the console pairing API that mints MCP grants. It is a thin adapter over internal/agent/tools: the catalogue decides what a principal may see, writes come back as pending approvals in WS4's agent store, and only mapped error messages reach a client.

The official github.com/modelcontextprotocol/go-sdk was evaluated (v1.8.0: pure Go, Apache-2.0/MIT transition licence) and rejected for this surface: it pulls OAuth/JWT/x-tools weight Ether does not need, and the catalogue already owns validation, visibility and audit. This is the minimal stateless JSON-RPC surface instead, mirroring appkit-mcp.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApprovalStore

type ApprovalStore interface {
	CreateApproval(ctx context.Context, a agent.Approval) (agent.Approval, error)
}

ApprovalStore is the slice of WS4's agent.Store MCP writes need.

type AuditEvent

type AuditEvent struct {
	Tool      string
	ViewerID  int64
	Scopes    []string
	Status    string // ok, proposal, secret_request, error, denied
	Error     string // mapped message only
	Duration  time.Duration
	RequestID string
}

AuditEvent is one tools/call, for the audit sink.

type Options

type Options struct {
	Catalogue *tools.Catalogue
	// Approvals receives write proposals. Nil means write tools answer
	// with an error result instead of a pending approval.
	Approvals ApprovalStore
	// OnApproval is called after a write proposal is stored, so the app
	// can notify the console stream (admin.StreamAgentApproval).
	OnApproval func(ctx context.Context, a agent.Approval)
	// Authenticate resolves a bearer token to a principal (surface "mcp").
	Authenticate func(ctx context.Context, token string) (tools.Principal, error)
	Resources    []Resource
	Version      string
	Logger       *slog.Logger
	// AllowedHosts and AllowedOrigins extend the boundary allowlists.
	AllowedHosts   []string
	AllowedOrigins []string
	Audit          func(ctx context.Context, e AuditEvent)
	ToolTimeout    time.Duration // default 30s
	Now            func() time.Time
}

Options configures the MCP server.

type Pairing

type Pairing struct {
	// contains filtered or unexported fields
}

Pairing serves the owner console and OAuth routes.

func NewPairing

func NewPairing(opts PairingOptions) (*Pairing, error)

NewPairing builds the pairing service.

func (*Pairing) Authenticate

func (p *Pairing) Authenticate(ctx context.Context, credential string) (tools.Principal, error)

Authenticate accepts only scoped grant credentials, never pairing codes.

func (*Pairing) Handler

func (p *Pairing) Handler() http.Handler

Handler serves the console routes, mounted by the app under /api/agent/mcp (owner-authenticated by the admin API):

GET    /authorization   -> pending request details
POST   /authorization   -> approve or deny
GET    /clients         -> {clients: [...]}
DELETE /clients/{id}    -> 204

func (*Pairing) OAuthHandler

func (p *Pairing) OAuthHandler() http.Handler

type PairingOptions

type PairingOptions struct {
	DB     *sql.DB
	Grants *identity.Grants
	// Authorize returns the owner viewer id for a console request. The app
	// implements it from the admin API's owner check.
	Authorize    func(ctx context.Context) (int64, error)
	Logger       *slog.Logger
	AllowedHosts []string
	Now          func() time.Time
}

PairingOptions configures the pairing service.

type Resource

type Resource struct {
	URI         string
	Name        string
	Description string
	MIMEType    string
	Text        string
}

Resource is one static MCP resource.

func DefaultResources

func DefaultResources(manifestSchema string) []Resource

DefaultResources returns the built-in resources. manifestSchema is the plugin manifest JSON Schema text when the plugin host provides a custom override; when empty, the built-in EPP/1 JSON Schema is served.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the MCP endpoint. It is safe for concurrent use.

func New

func New(opts Options) (*Server, error)

New builds an MCP server.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler serves the MCP endpoint. Mount it LAN-only, like the console.

Jump to

Keyboard shortcuts

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