Files
sam 8c267b6edd feat: record skipped dispatches and approver ids
- store trigger dispatches as started or skipped, with a JSON reason surfaced in the API and UI
- persist the answering account's identity id beside its display name for approvals and judgements
- save connector acceptances and their declarations in one transaction so a refused change stores nothing
2026-11-22 23:24:30 +11:00

273 lines
9.3 KiB
Go

package connectors
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"maps"
"net/http"
"net/url"
"regexp"
"slices"
"github.com/danielgtaylor/huma/v2"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/modules/connectors/internal/store"
)
// envSettingName is the shape of a setting's name: a stdio server's settings
// are its environment.
var envSettingName = regexp.MustCompile(`^[A-Z_][A-Z0-9_]*$`)
type mcpInput struct {
Name string `path:"name" doc:"Lowercase letters, digits and hyphens"`
Body mcpRequest
}
// mcpRequest is one acceptance of an MCP server.
type mcpRequest struct {
// URL reaches an HTTP server; Path and SHA256 name a stdio server's binary.
// Setting one of the two picks the transport.
URL string `json:"url,omitzero"`
Path string `json:"path,omitzero"`
SHA256 string `json:"sha256,omitzero"`
// Args are a stdio server's arguments.
Args []string `json:"args,omitzero"`
// Env names host environment variables the server may see.
Env []string `json:"env,omitzero"`
// Settings are handed to a stdio server as its environment.
Settings map[string]string `json:"settings,omitzero"`
// Egress is the accepted host list: everything the server may reach.
Egress []string `json:"egress,omitzero"`
// Credentials maps each slot the server's credentials are read from to a
// credential by name.
Credentials map[string]string `json:"credentials,omitzero"`
// Tools are the tools the server may offer, and nothing else is offered.
Tools []ToolDecl `json:"tools,omitzero"`
// Effects declares whether the server's tools change privileges or access
// secrets. A server that declares nothing is not offered to chat.
Effects *ServerEffects `json:"effects,omitzero" doc:"Whether the server's tools change privileges or access secrets. Chat offers a server only when this is declared and both are false."`
}
// ServerEffects is an operator's declaration of the privileged effects of an
// MCP server's tools.
type ServerEffects struct {
PrivilegeChange bool `json:"privilege_change" doc:"The tools grant roles, change identities or policies, or change control-plane settings"`
SecretAccess bool `json:"secret_access" doc:"The tools read, export or reveal secrets"`
}
// privileged is the declaration as tools carry it; nil is not declared.
func (e *ServerEffects) privileged() PrivilegedEffects {
if e == nil {
return PrivilegedEffects{}
}
return PrivilegedEffects{Declared: true, PrivilegeChange: e.PrivilegeChange, SecretAccess: e.SecretAccess}
}
// check refuses an acceptance that couldn't work, before anything is stored.
func (r mcpRequest) check() error {
if err := r.checkTransport(); err != nil {
return err
}
for _, name := range slices.Sorted(maps.Keys(r.Settings)) {
if !envSettingName.MatchString(name) {
return fmt.Errorf("setting %q isn't an environment variable name", name)
}
}
return r.checkTools()
}
// checkTransport refuses an acceptance that names no transport, both of them,
// or a field the transport it named has no use for.
func (r mcpRequest) checkTransport() error {
stdio, exchange := r.Path != "" || r.SHA256 != "", r.URL != ""
switch {
case stdio && exchange:
return errors.New("an MCP server is reached over stdio or HTTP, not both")
case !stdio && !exchange:
return errors.New("an MCP server needs a path and its sha256 (stdio), or a url (HTTP)")
}
if stdio {
if r.Path == "" || r.SHA256 == "" {
return errors.New("a stdio MCP server needs its binary's path and sha256")
}
return nil
}
if len(r.Args) > 0 || len(r.Settings) > 0 {
return errors.New("an HTTP MCP server takes no arguments or settings: both belong to a stdio server")
}
u, err := url.Parse(r.URL)
if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") {
return fmt.Errorf("url %q needs an http or https scheme and a host", r.URL)
}
return nil
}
// checkTools refuses an acceptance that declares nothing to offer, or a
// declaration that can't be judged: an action without the effect it claims.
func (r mcpRequest) checkTools() error {
if len(r.Tools) == 0 {
return errors.New("an MCP server offers only the tools its acceptance declares, and this one declares none")
}
seen := make(map[string]bool, len(r.Tools))
for _, t := range r.Tools {
if t.Name == "" {
return errors.New("a declared tool needs a name")
}
if seen[t.Name] {
return fmt.Errorf("tool %q is declared twice", t.Name)
}
seen[t.Name] = true
switch t.Kind {
case KindLookup:
case KindAction:
if t.Summary == "" {
return fmt.Errorf("action %q needs a summary of its effect", t.Name)
}
if _, ok := reversibility(t.Reversibility); !ok {
return fmt.Errorf("action %q: reversibility %q isn't one of auto, recoverable, irreversible", t.Name, t.Reversibility)
}
default:
return fmt.Errorf("tool %q is a %q, want %q or %q", t.Name, t.Kind, KindLookup, KindAction)
}
}
return nil
}
// reversibility reads an action declaration's reversibility. Judgement reads
// it; nothing runs an action until judgement exists.
func reversibility(name string) (Reversibility, bool) {
switch name {
case "":
return ReversibilityUnspecified, true
case "auto":
return UndoneAutomatically, true
case "recoverable":
return Recoverable, true
case "irreversible":
return Irreversible, true
}
return ReversibilityUnspecified, false
}
// acceptServer stores an MCP server's acceptance and starts it. A server that
// doesn't come up is still accepted: it is reported by readiness and retried
// with backoff, so a restart fixes it without another acceptance.
func (m *Module) acceptServer(ctx context.Context, in *mcpInput) (*httpapi.Reply[packageState], error) {
name, req := in.Name, in.Body
if !validName.MatchString(name) {
return nil, huma.NewError(http.StatusBadRequest, "an MCP server needs a lowercase name")
}
if err := req.check(); err != nil {
return nil, huma.NewError(http.StatusBadRequest, err.Error())
}
a, err := req.accepted(m.orgID, name)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, err.Error())
}
if err := m.store.Save(ctx, a, nil); err != nil {
return nil, huma.NewError(http.StatusInternalServerError, err.Error())
}
if err := m.launch(context.WithoutCancel(ctx), a); err != nil {
return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error())
}
if err := m.checkAccepted(a); err != nil {
_, _ = m.store.Delete(context.WithoutCancel(ctx), m.orgID, name)
m.release(name)
m.mu.Lock()
delete(m.failed, name)
m.mu.Unlock()
return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error())
}
return httpapi.OK(packageState{Name: name, State: "running"}), nil
}
// accepted is the row an acceptance stores.
func (r mcpRequest) accepted(orgID, name string) (store.Accepted, error) {
settings, err := json.Marshal(r.Settings, json.FormatNilMapAsNull(false))
if err != nil {
return store.Accepted{}, err
}
slots, err := json.Marshal(r.Credentials, json.FormatNilMapAsNull(false))
if err != nil {
return store.Accepted{}, err
}
tools, err := json.Marshal(r.Tools)
if err != nil {
return store.Accepted{}, err
}
var effects jsontext.Value
if r.Effects != nil {
if effects, err = json.Marshal(r.Effects); err != nil {
return store.Accepted{}, err
}
}
return store.Accepted{
OrgID: orgID, Name: name, Contract: store.ContractMCP,
Path: r.Path, SHA256: r.SHA256, URL: r.URL, Args: r.Args,
Env: r.Env, Egress: r.Egress, Settings: settings, Credentials: slots, Tools: tools, Effects: effects,
Enabled: true,
}, nil
}
// startServer runs one accepted MCP server. Its supervisor keeps it answering,
// reconnecting with backoff, until the module closes or the server is accepted
// again.
func (m *Module) startServer(ctx context.Context, a store.Accepted) error {
spec, err := m.serverSpec(ctx, a)
if err != nil {
return m.fail(ctx, a.Name, err)
}
base, stop := context.WithCancel(context.WithoutCancel(ctx))
s := m.host.NewServer(spec)
m.mu.Lock()
m.servers[a.Name], m.stops[a.Name] = s, stop
delete(m.failed, a.Name)
m.mu.Unlock()
go s.Supervise(base)
if err := s.Connect(ctx); err != nil {
m.log.ErrorContext(ctx, "mcp server failed to start", "server", a.Name, "error", err)
return err
}
m.log.InfoContext(ctx, "mcp server started", "server", a.Name)
return nil
}
// serverSpec is what a stored acceptance says a running server must be.
func (m *Module) serverSpec(ctx context.Context, a store.Accepted) (ServerSpec, error) {
spec := ServerSpec{
Name: a.Name, Path: a.Path, SHA256: a.SHA256, URL: a.URL,
Args: a.Args, Egress: a.Egress,
}
if len(a.Settings) > 0 {
var settings map[string]string
if err := json.Unmarshal(a.Settings, &settings); err != nil {
return ServerSpec{}, fmt.Errorf("settings: %w", err)
}
for _, name := range slices.Sorted(maps.Keys(settings)) {
spec.Settings = append(spec.Settings, name+"="+settings[name])
}
}
if len(a.Tools) > 0 {
if err := json.Unmarshal(a.Tools, &spec.Tools); err != nil {
return ServerSpec{}, fmt.Errorf("tools: %w", err)
}
}
if len(a.Effects) > 0 {
var effects ServerEffects
if err := json.Unmarshal(a.Effects, &effects); err != nil {
return ServerSpec{}, fmt.Errorf("effects: %w", err)
}
spec.Privileged = effects.privileged()
}
env, headers, err := m.mcpCredentials(ctx, a, spec.URL != "")
if err != nil {
return ServerSpec{}, err
}
spec.SecretEnv, spec.SecretHeaders = env, headers
return spec, nil
}