- 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
273 lines
9.3 KiB
Go
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
|
|
}
|