Connector actions and lookups now declare privilege change and secret access, and an MCP server declares both per installation. Chat withholds and refuses any tool that has either effect or declared nothing, in judgement and at execution, so an approval cannot convert the refusal. Workflows and the dashboard are unchanged.
548 lines
17 KiB
Go
548 lines
17 KiB
Go
package connectors
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json/jsontext"
|
|
json "encoding/json/v2"
|
|
"errors"
|
|
"fmt"
|
|
"log/slog"
|
|
"maps"
|
|
"net/http"
|
|
"slices"
|
|
"strings"
|
|
"sync"
|
|
"time"
|
|
"unicode/utf8"
|
|
|
|
"github.com/google/jsonschema-go/jsonschema"
|
|
sdk "github.com/modelcontextprotocol/go-sdk/mcp"
|
|
|
|
"github.com/samcharles93/archie-core/internal/platform/auditjson"
|
|
"github.com/samcharles93/archie-core/modules/connectors/internal/egress"
|
|
"github.com/samcharles93/archie-core/modules/connectors/internal/host"
|
|
)
|
|
|
|
// Bounds on one MCP server. A server is a tool source like a connector, so the
|
|
// same rules hold: a call has a deadline, a result has a size, and a tool the
|
|
// acceptance doesn't name is never offered.
|
|
const (
|
|
// mcpConnectTimeout bounds the handshake and the tool listing.
|
|
mcpConnectTimeout = 30 * time.Second
|
|
// mcpCallTimeout bounds one tool call.
|
|
mcpCallTimeout = 60 * time.Second
|
|
// mcpPingInterval is how often a live session is checked, so a server that
|
|
// stopped answering is reported by readiness.
|
|
mcpPingInterval = 30 * time.Second
|
|
// mcpResultLimit caps the text one tool result hands back to the agent.
|
|
mcpResultLimit = 32 << 10
|
|
// mcpToolLimit caps how many tools one server may list.
|
|
mcpToolLimit = 200
|
|
// mcpBackoffMin and mcpBackoffMax bound the restart delay.
|
|
mcpBackoffMin = time.Second
|
|
mcpBackoffMax = time.Minute
|
|
)
|
|
|
|
// ServerSpec is one accepted MCP server: how it is reached, the environment or
|
|
// headers its credentials resolve into, and the tools its acceptance permits.
|
|
type ServerSpec struct {
|
|
Name string
|
|
// Path and SHA256 identify a stdio server's binary; URL is an HTTP server's
|
|
// endpoint. Which one the acceptance set picks the transport.
|
|
Path string
|
|
SHA256 string
|
|
URL string
|
|
Args []string
|
|
// Env names host environment variables the server may see.
|
|
Env []string
|
|
// Settings are handed to a stdio server as its environment, since MCP has
|
|
// no configuration channel of its own.
|
|
Settings []string
|
|
// Egress is the accepted host list. A stdio server reaches only these.
|
|
Egress []string
|
|
// SecretEnv is a stdio server's credential-derived environment, and
|
|
// SecretHeaders an HTTP server's credential-derived headers.
|
|
SecretEnv []string
|
|
SecretHeaders map[string]string
|
|
// Tools are the tools the acceptance permits.
|
|
Tools []ToolDecl
|
|
// Privileged is what the operator declared about the whole server: every
|
|
// tool it offers carries it.
|
|
Privileged PrivilegedEffects
|
|
}
|
|
|
|
// ToolDecl is one tool an acceptance permits: a lookup, or an action with the
|
|
// effect it declares.
|
|
type ToolDecl struct {
|
|
Name string `json:"name"`
|
|
// Kind is KindLookup or KindAction.
|
|
Kind string `json:"kind"`
|
|
// ReadOnly, Reversibility and Summary are an action's effect.
|
|
ReadOnly bool `json:"read_only,omitzero"`
|
|
Reversibility string `json:"reversibility,omitzero"`
|
|
Summary string `json:"summary,omitzero"`
|
|
}
|
|
|
|
// effect is what the declaration says the tool does. Its reversibility and
|
|
// summary are kept for judgement, which is what runs an action. privileged is
|
|
// the server's declaration, which the tool inherits.
|
|
func (d ToolDecl) effect(privileged PrivilegedEffects) Effect {
|
|
r, _ := reversibility(d.Reversibility)
|
|
return Effect{ReadOnly: d.Kind == KindLookup || d.ReadOnly, Reversibility: r, Summary: d.Summary, Privileged: privileged}
|
|
}
|
|
|
|
// mcpTool is one declared tool as the server lists it.
|
|
type mcpTool struct {
|
|
kind string
|
|
effect Effect
|
|
description string
|
|
input *jsonschema.Resolved
|
|
schema jsontext.Value
|
|
}
|
|
|
|
// Server is one accepted MCP server: the process or endpoint its acceptance
|
|
// names, and the declared subset of the tools that server offers.
|
|
type Server struct {
|
|
name string
|
|
spec ServerSpec
|
|
log *slog.Logger
|
|
procs *host.Host
|
|
// dial connects, initialises a session and returns the release that ends
|
|
// it. It is a field so a test can speak to an in-memory server.
|
|
dial func(context.Context) (*sdk.ClientSession, func(), error)
|
|
|
|
mu sync.Mutex
|
|
session *sdk.ClientSession
|
|
release func()
|
|
tools map[string]mcpTool
|
|
lastErr error
|
|
}
|
|
|
|
// NewServer returns an MCP server that connects when it is first used and
|
|
// reconnects when its process or endpoint fails.
|
|
func (h *Host) NewServer(spec ServerSpec) *Server {
|
|
s := &Server{
|
|
name: spec.Name, spec: spec, log: h.log, procs: h.procs,
|
|
tools: map[string]mcpTool{},
|
|
}
|
|
s.dial = s.connect
|
|
return s
|
|
}
|
|
|
|
// SettingsSchema names the environment settings the acceptance gave a stdio
|
|
// server. MCP has no configuration channel, so the keys are the declaration.
|
|
func (s *Server) SettingsSchema() []Setting {
|
|
out := make([]Setting, 0, len(s.spec.Settings))
|
|
for _, kv := range s.spec.Settings {
|
|
key, _, _ := strings.Cut(kv, "=")
|
|
out = append(out, Setting{Key: key, Label: key})
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Declarations lists the tools the acceptance permits, in name order.
|
|
func (s *Server) Declarations() []Declaration {
|
|
s.mu.Lock()
|
|
defer s.mu.Unlock()
|
|
out := make([]Declaration, 0, len(s.tools))
|
|
for _, name := range slices.Sorted(maps.Keys(s.tools)) {
|
|
t := s.tools[name]
|
|
out = append(out, Declaration{
|
|
Connector: s.name, Kind: t.kind, Name: name,
|
|
Description: t.description, Schema: t.schema, ReadOnly: t.effect.ReadOnly, Privileged: t.effect.Privileged,
|
|
})
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Lookup calls one declared lookup and returns the result verbatim. found is
|
|
// false when the server answered with nothing.
|
|
func (s *Server) Lookup(ctx context.Context, name string, input jsontext.Value) (string, bool, error) {
|
|
return s.call(ctx, name, KindLookup, input)
|
|
}
|
|
|
|
// Resolve returns a declared action's effect as its acceptance states it. An
|
|
// MCP server can't name the target an action touches, so the target is left
|
|
// unknown, which judgement treats as missing evidence.
|
|
func (s *Server) Resolve(_ context.Context, name string, input jsontext.Value) (Resolution, error) {
|
|
t, err := s.tool(name, KindAction)
|
|
if err != nil {
|
|
return Resolution{}, err
|
|
}
|
|
if err := validate(t.input, input); err != nil {
|
|
return Resolution{}, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, err)
|
|
}
|
|
return Resolution{Effect: t.effect}, nil
|
|
}
|
|
|
|
// Invoke calls one declared action and returns the result verbatim. It runs
|
|
// only what judgement allowed.
|
|
func (s *Server) Invoke(ctx context.Context, inv Invocation) (string, error) {
|
|
out, _, err := s.call(ctx, inv.Action, KindAction, inv.Input)
|
|
return out, err
|
|
}
|
|
|
|
func (s *Server) call(ctx context.Context, name, kind string, input jsontext.Value) (string, bool, error) {
|
|
t, err := s.tool(name, kind)
|
|
if err != nil {
|
|
return "", false, err
|
|
}
|
|
if err := validate(t.input, input); err != nil {
|
|
return "", false, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, err)
|
|
}
|
|
args, err := arguments(input)
|
|
if err != nil {
|
|
return "", false, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, err)
|
|
}
|
|
cs, err := s.live(ctx)
|
|
if err != nil {
|
|
return "", false, fmt.Errorf("mcp server %q: %w", s.name, err)
|
|
}
|
|
request := auditjson.FromValue(map[string]any{"tool": name, "arguments": args})
|
|
ctx, cancel := context.WithTimeout(ctx, mcpCallTimeout)
|
|
defer cancel()
|
|
res, err := cs.CallTool(ctx, &sdk.CallToolParams{Name: name, Arguments: args})
|
|
if err != nil {
|
|
s.drop(cs, fmt.Errorf("tool %q: %w", name, err))
|
|
record(ctx, Call{Connector: s.name, Method: kind, Request: request, Error: err.Error()})
|
|
return "", false, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, err)
|
|
}
|
|
// A tool that answered with an error fails this call, not the run: the
|
|
// message is the server's own, so a bad query reads as a bad query.
|
|
out := capResult(render(res))
|
|
record(ctx, Call{Connector: s.name, Method: kind, Request: request, Response: auditjson.FromValue(map[string]any{
|
|
"output": out, "is_error": res.IsError,
|
|
})})
|
|
if res.IsError {
|
|
return "", false, fmt.Errorf("mcp server %q: tool %q: %s", s.name, name, out)
|
|
}
|
|
if out == "" {
|
|
return "", false, nil
|
|
}
|
|
return out, true, nil
|
|
}
|
|
|
|
// tool returns one declared tool, refusing a name the acceptance doesn't
|
|
// declare and a tool called through the wrong side of the contract.
|
|
func (s *Server) tool(name, kind string) (mcpTool, error) {
|
|
s.mu.Lock()
|
|
defer s.mu.Unlock()
|
|
t, ok := s.tools[name]
|
|
if !ok {
|
|
return mcpTool{}, fmt.Errorf("mcp server %q: tool %q: %w", s.name, name, ErrUnknownName)
|
|
}
|
|
if t.kind != kind {
|
|
return mcpTool{}, fmt.Errorf("mcp server %q: tool %q is a %s: %w", s.name, name, t.kind, ErrUnknownName)
|
|
}
|
|
return t, nil
|
|
}
|
|
|
|
// live returns the current session, connecting once when there is none.
|
|
func (s *Server) live(ctx context.Context) (*sdk.ClientSession, error) {
|
|
s.mu.Lock()
|
|
defer s.mu.Unlock()
|
|
if s.session != nil {
|
|
return s.session, nil
|
|
}
|
|
cs, release, tools, err := s.open(ctx)
|
|
if err != nil {
|
|
s.lastErr = err
|
|
return nil, err
|
|
}
|
|
s.session, s.release, s.tools, s.lastErr = cs, release, tools, nil
|
|
return cs, nil
|
|
}
|
|
|
|
// open connects and matches the server's tool list to the acceptance.
|
|
func (s *Server) open(ctx context.Context) (*sdk.ClientSession, func(), map[string]mcpTool, error) {
|
|
ctx, cancel := context.WithTimeout(ctx, mcpConnectTimeout)
|
|
defer cancel()
|
|
cs, release, err := s.dial(ctx)
|
|
if err != nil {
|
|
return nil, nil, nil, err
|
|
}
|
|
tools, err := s.declared(ctx, cs)
|
|
if err != nil {
|
|
release()
|
|
_ = cs.Close()
|
|
return nil, nil, nil, err
|
|
}
|
|
return cs, release, tools, nil
|
|
}
|
|
|
|
// Connect opens the first session, so an acceptance that can't work is
|
|
// reported to the operator when it is made.
|
|
func (s *Server) Connect(ctx context.Context) error {
|
|
_, err := s.live(ctx)
|
|
return err
|
|
}
|
|
|
|
// declared matches the server's tool list to the acceptance: a permitted tool
|
|
// takes the server's description and input schema, and a permitted tool the
|
|
// server doesn't list is an error rather than a silently missing one.
|
|
func (s *Server) declared(ctx context.Context, cs *sdk.ClientSession) (map[string]mcpTool, error) {
|
|
listed, err := listTools(ctx, cs)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("mcp server %q: %w", s.name, err)
|
|
}
|
|
out := make(map[string]mcpTool, len(s.spec.Tools))
|
|
var missing []string
|
|
for _, d := range s.spec.Tools {
|
|
t, ok := listed[d.Name]
|
|
if !ok {
|
|
missing = append(missing, d.Name)
|
|
continue
|
|
}
|
|
schema, resolved, err := compileTool(t)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("mcp server %q: tool %q: %w", s.name, d.Name, err)
|
|
}
|
|
out[d.Name] = mcpTool{
|
|
kind: d.Kind, effect: d.effect(s.spec.Privileged), description: t.Description,
|
|
input: resolved, schema: schema,
|
|
}
|
|
}
|
|
if len(missing) > 0 {
|
|
return nil, fmt.Errorf("mcp server %q doesn't list the declared tool %s", s.name, strings.Join(missing, ", "))
|
|
}
|
|
return out, nil
|
|
}
|
|
|
|
// Supervise keeps the server answering, restarting it with backoff when it
|
|
// fails to start, exits or stops answering, until ctx ends.
|
|
func (s *Server) Supervise(ctx context.Context) {
|
|
log := s.log.With("server", s.name)
|
|
backoff := mcpBackoffMin
|
|
for {
|
|
cs, err := s.live(ctx)
|
|
if err != nil {
|
|
log.ErrorContext(ctx, "mcp server down", "error", err, "retry_in", backoff)
|
|
if !sleep(ctx, backoff) {
|
|
return
|
|
}
|
|
backoff = min(2*backoff, mcpBackoffMax)
|
|
continue
|
|
}
|
|
backoff = mcpBackoffMin
|
|
if !s.watch(ctx, cs) {
|
|
return
|
|
}
|
|
}
|
|
}
|
|
|
|
// watch pings the session until it fails or ctx ends, and reports whether the
|
|
// server should be reconnected.
|
|
func (s *Server) watch(ctx context.Context, cs *sdk.ClientSession) bool {
|
|
ticker := time.NewTicker(mcpPingInterval)
|
|
defer ticker.Stop()
|
|
for {
|
|
select {
|
|
case <-ctx.Done():
|
|
return false
|
|
case <-ticker.C:
|
|
pingCtx, cancel := context.WithTimeout(ctx, mcpCallTimeout)
|
|
err := cs.Ping(pingCtx, nil)
|
|
cancel()
|
|
if err != nil {
|
|
s.drop(cs, fmt.Errorf("ping: %w", err))
|
|
return true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// drop ends a session the server has left behind, so the next call reconnects.
|
|
func (s *Server) drop(cs *sdk.ClientSession, reason error) {
|
|
s.mu.Lock()
|
|
defer s.mu.Unlock()
|
|
if s.session != cs {
|
|
return
|
|
}
|
|
s.session, s.lastErr = nil, reason
|
|
if s.release != nil {
|
|
s.release()
|
|
s.release = nil
|
|
}
|
|
_ = cs.Close()
|
|
}
|
|
|
|
// Ready reports why the server isn't answering, or nil.
|
|
func (s *Server) Ready() error {
|
|
s.mu.Lock()
|
|
defer s.mu.Unlock()
|
|
if s.session != nil {
|
|
return nil
|
|
}
|
|
if s.lastErr == nil {
|
|
return errors.New("mcp server not connected")
|
|
}
|
|
return s.lastErr
|
|
}
|
|
|
|
// Close ends the server's session.
|
|
func (s *Server) Close() {
|
|
s.mu.Lock()
|
|
cs, release := s.session, s.release
|
|
s.session, s.release = nil, nil
|
|
s.mu.Unlock()
|
|
if release != nil {
|
|
release()
|
|
}
|
|
if cs != nil {
|
|
_ = cs.Close()
|
|
}
|
|
}
|
|
|
|
// connect opens the transport the acceptance names and initialises a session.
|
|
func (s *Server) connect(ctx context.Context) (*sdk.ClientSession, func(), error) {
|
|
client := sdk.NewClient(&sdk.Implementation{Name: "archie-core", Version: "1.0.0"}, nil)
|
|
if s.spec.URL != "" {
|
|
transport := &sdk.StreamableClientTransport{
|
|
Endpoint: s.spec.URL, HTTPClient: s.httpClient(), DisableStandaloneSSE: true,
|
|
}
|
|
cs, err := client.Connect(ctx, transport, nil)
|
|
if err != nil {
|
|
return nil, nil, err
|
|
}
|
|
return cs, func() { _ = cs.Close() }, nil
|
|
}
|
|
cmd, release, err := s.procs.Command(ctx, host.Spec{
|
|
Name: s.spec.Name, Path: s.spec.Path, SHA256: s.spec.SHA256, Env: s.spec.Env, Egress: s.spec.Egress,
|
|
}, s.spec.Args, append(slices.Clone(s.spec.Settings), s.spec.SecretEnv...))
|
|
if err != nil {
|
|
return nil, nil, err
|
|
}
|
|
cs, err := client.Connect(ctx, &sdk.CommandTransport{Command: cmd}, nil)
|
|
if err != nil {
|
|
release()
|
|
return nil, nil, err
|
|
}
|
|
return cs, release, nil
|
|
}
|
|
|
|
// httpClient dials only the hosts the acceptance names, and sends that
|
|
// server's own credentials and no other's.
|
|
func (s *Server) httpClient() *http.Client {
|
|
transport := &http.Transport{
|
|
DialContext: egress.Dialer(s.spec.Egress),
|
|
TLSHandshakeTimeout: 10 * time.Second,
|
|
MaxIdleConnsPerHost: 2,
|
|
}
|
|
return &http.Client{Transport: &headerTransport{base: transport, headers: s.spec.SecretHeaders}}
|
|
}
|
|
|
|
// headerTransport sets the credentials an HTTP server is called with.
|
|
type headerTransport struct {
|
|
base http.RoundTripper
|
|
headers map[string]string
|
|
}
|
|
|
|
func (h *headerTransport) RoundTrip(r *http.Request) (*http.Response, error) {
|
|
r = r.Clone(r.Context())
|
|
for name, value := range h.headers {
|
|
r.Header.Set(name, value)
|
|
}
|
|
return h.base.RoundTrip(r)
|
|
}
|
|
|
|
// listTools reads every page of a server's tool list.
|
|
func listTools(ctx context.Context, cs *sdk.ClientSession) (map[string]*sdk.Tool, error) {
|
|
out := map[string]*sdk.Tool{}
|
|
params := &sdk.ListToolsParams{}
|
|
for {
|
|
res, err := cs.ListTools(ctx, params)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("list tools: %w", err)
|
|
}
|
|
for _, t := range res.Tools {
|
|
if len(out) >= mcpToolLimit {
|
|
return nil, fmt.Errorf("the server lists more than %d tools", mcpToolLimit)
|
|
}
|
|
out[t.Name] = t
|
|
}
|
|
if res.NextCursor == "" {
|
|
return out, nil
|
|
}
|
|
params.Cursor = res.NextCursor
|
|
}
|
|
}
|
|
|
|
// compileTool compiles a listed tool's input schema, and keeps the schema as
|
|
// the agent is shown it.
|
|
func compileTool(t *sdk.Tool) (jsontext.Value, *jsonschema.Resolved, error) {
|
|
raw, err := json.Marshal(t.InputSchema)
|
|
if err != nil {
|
|
return nil, nil, fmt.Errorf("input schema: %w", err)
|
|
}
|
|
if len(raw) == 0 || string(raw) == "null" {
|
|
// A tool that takes no arguments still has to carry a schema a model
|
|
// API accepts.
|
|
raw = []byte(`{"type":"object"}`)
|
|
}
|
|
resolved, err := compile(raw)
|
|
if err != nil {
|
|
return nil, nil, err
|
|
}
|
|
return jsontext.Value(raw), resolved, nil
|
|
}
|
|
|
|
// arguments turns a call's input into the arguments a tool call carries.
|
|
func arguments(input jsontext.Value) (map[string]any, error) {
|
|
if len(input) == 0 {
|
|
return map[string]any{}, nil
|
|
}
|
|
var args map[string]any
|
|
if err := json.Unmarshal(input, &args); err != nil {
|
|
return nil, fmt.Errorf("arguments: %w", err)
|
|
}
|
|
return args, nil
|
|
}
|
|
|
|
// render turns a tool result into the text the agent is given: text blocks
|
|
// verbatim, and any other block as the JSON the server sent.
|
|
func render(res *sdk.CallToolResult) string {
|
|
var b strings.Builder
|
|
for _, c := range res.Content {
|
|
if text, ok := c.(*sdk.TextContent); ok {
|
|
b.WriteString(text.Text)
|
|
continue
|
|
}
|
|
raw, err := c.MarshalJSON()
|
|
if err != nil {
|
|
continue
|
|
}
|
|
b.Write(raw)
|
|
}
|
|
if b.Len() == 0 && res.StructuredContent != nil {
|
|
if raw, err := json.Marshal(res.StructuredContent); err == nil {
|
|
b.Write(raw)
|
|
}
|
|
}
|
|
return b.String()
|
|
}
|
|
|
|
// capResult holds a result to mcpResultLimit bytes, on a character boundary,
|
|
// and says what it dropped.
|
|
func capResult(out string) string {
|
|
if len(out) <= mcpResultLimit {
|
|
return out
|
|
}
|
|
kept := mcpResultLimit
|
|
for kept > 0 && !utf8.RuneStart(out[kept]) {
|
|
kept--
|
|
}
|
|
return out[:kept] + fmt.Sprintf("\n[truncated: %d bytes dropped, a result is capped at %d]", len(out)-kept, mcpResultLimit)
|
|
}
|
|
|
|
// sleep waits out a backoff, reporting false when ctx ended first.
|
|
func sleep(ctx context.Context, d time.Duration) bool {
|
|
timer := time.NewTimer(d)
|
|
defer timer.Stop()
|
|
select {
|
|
case <-ctx.Done():
|
|
return false
|
|
case <-timer.C:
|
|
return true
|
|
}
|
|
}
|