appserver

package
v0.7.7 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package appserver is Agentry's catalogue of application servers: for each application a QuickAgent may use on the person's own computer, the MCP server Agentry has vetted for it, pinned to one exact release, with every tool a run may call given a class.

A release names an entry by its id in capabilities.desktop.servers and never names a command: Agentry Desktop launches the entry's pinned server as the person (or connects to the loopback address the application serves), and the run reaches it through the desktop link, one runner-owned server of the run's gateway catalog per entry. Each call is answered by the tool's class: read and act run and are logged, exec (code or commands the application interprets) asks the person first. The classes are the catalogue's, never the server's own tool annotations, which an untrusted server sets as it likes.

An installed server runs on the person's computer with that computer's network and files, which no run can hold. So an entry lists the hosts the server is known to reach and which tools reach them; the consent names them, the scanner counts them as it counts a declared server's egress, and the receipt says they were outside the run.

The catalogue is embedded data (catalogue.yaml), released with the core and compiled into every client that imports this package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attachment

type Attachment string

Attachment is how Agentry Desktop reaches an installed server.

const (
	// AttachmentStdio is a server Agentry Desktop launches, speaking MCP
	// over its standard input and output.
	AttachmentStdio Attachment = "stdio"
	// AttachmentLoopbackHTTP is a server the application runs inside
	// itself on a loopback address, which Agentry Desktop connects to.
	AttachmentLoopbackHTTP Attachment = "loopback-http"
)

The attachments.

type Catalogue

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

Catalogue is a validated catalogue.

func Builtin

func Builtin() Catalogue

Builtin is the catalogue released with this build.

func Parse

func Parse(data []byte) (Catalogue, error)

Parse reads and validates a catalogue. It refuses unknown fields, a catalogue without a version, a repeated or malformed id, an entry without an application, a platform or a step, a server without an exact version, a source that is not https, a launch that does not hold the pin, an attachment other than stdio or loopback-http, a stdio server of the application's own, a loopback address that is not loopback or not on the listener's port, a port out of range, a tool of no class or one outside the closed set, a tool listed twice or both given and withheld, and an egress host that is not a DNS name.

func (Catalogue) All

func (c Catalogue) All() []Server

All is every entry, in the catalogue's order.

func (Catalogue) Lookup

func (c Catalogue) Lookup(id string) (Server, bool)

Lookup is the entry with this id.

func (Catalogue) Version

func (c Catalogue) Version() int

Version is the catalogue's version, raised on every change to it.

type Class

type Class string

Class is how a tool is answered.

const (
	// ClassRead reads the application's state.
	ClassRead Class = "read"
	// ClassAct changes the application's state or works inside it.
	ClassAct Class = "act"
	// ClassExec runs code or commands the application interprets: each
	// call asks the person first.
	ClassExec Class = "exec"
)

The classes, a closed set.

func Classes

func Classes() []Class

Classes returns every class, in a fixed order.

type Ecosystem

type Ecosystem string

Ecosystem is the package registry an installed server is published in.

const (
	EcosystemPyPI Ecosystem = "pypi"
	EcosystemNPM  Ecosystem = "npm"
	// EcosystemApplication is a server the application ships itself, as a
	// plugin released with it: its name is the plugin's and its version the
	// application's release that brought it. No package registry holds it,
	// so there is nothing to launch and no advisory database to look it up
	// in; only a loopback-http entry may name it.
	EcosystemApplication Ecosystem = "application"
)

The ecosystems an entry may pin.

type Launch

type Launch struct {
	// Command is the program and its arguments; one of them holds the
	// pinned version.
	Command []string `yaml:"command" json:"command"`
	// Env is set for the server's process.
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
}

Launch is a stdio server's command line and environment.

type Listener

type Listener struct {
	Port int `yaml:"port" json:"port"`
}

Listener is where the application listens for its server.

type Package

type Package struct {
	Ecosystem Ecosystem `yaml:"ecosystem" json:"ecosystem"`
	Name      string    `yaml:"name" json:"name"`
	// Version is exact: a newer release is not vetted until it is listed.
	Version string `yaml:"version" json:"version"`
	// Source is the server's source repository, https.
	Source string `yaml:"source" json:"source"`
}

Package is an installed server's pin.

func (Package) Ref

func (p Package) Ref() string

Ref is the pin as ecosystem:name@version.

type Server

type Server struct {
	// ID names it in capabilities.desktop.servers: lowercase letters,
	// digits and single hyphens.
	ID string `yaml:"id" json:"id"`
	// Application is the application's name, as people know it.
	Application string `yaml:"application" json:"application"`
	// Platforms are the operating systems it is offered on.
	Platforms []string `yaml:"platforms" json:"platforms"`
	// Package is the installed server, pinned to one exact release.
	Package Package `yaml:"server" json:"server"`
	// Attachment is how Agentry Desktop reaches the server.
	Attachment Attachment `yaml:"attachment" json:"attachment"`
	// Launch is the command line of a stdio server.
	Launch *Launch `yaml:"launch,omitempty" json:"launch,omitempty"`
	// Endpoint is a loopback-http server's address.
	Endpoint string `yaml:"endpoint,omitempty" json:"endpoint,omitempty"`
	// Listener is the loopback port the application listens on, checked
	// before a run starts.
	Listener Listener `yaml:"listener" json:"listener"`
	// Tools are every tool a run may call, in the catalogue's order.
	Tools []Tool `yaml:"tools" json:"tools"`
	// Withheld are tools the server offers that no run is given.
	Withheld []string `yaml:"withheld,omitempty" json:"withheld,omitempty"`
	// Egress are the hosts the server or the application's add-on is
	// known to reach from the person's computer.
	Egress []string `yaml:"egress,omitempty" json:"egress,omitempty"`
	// Steps are what the person does once before the first run.
	Steps []string `yaml:"steps" json:"steps"`
}

Server is one catalogue entry: an application and its vetted installed server.

func (Server) Offers

func (s Server) Offers(name string) bool

Offers reports whether the server offers a tool of this name, given to a run or withheld.

func (Server) Tool

func (s Server) Tool(name string) (Tool, bool)

Tool returns the entry's tool of this name.

func (Server) ToolNames

func (s Server) ToolNames() []string

ToolNames are the entry's tools, in the catalogue's order.

type Tool

type Tool struct {
	Name  string `yaml:"name" json:"name"`
	Class Class  `yaml:"class" json:"class"`
	// Egress marks a tool that reaches the entry's hosts.
	Egress bool `yaml:"egress,omitempty" json:"egress,omitempty"`
}

Tool is one tool a run may call.

Jump to

Keyboard shortcuts

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