plugin

Documentation

Overview

Package plugin is OK's MCP client. It connects to external MCP servers and adapts their tools to the tool.Tool interface, so the agent treats plugin tools and built-ins uniformly. The wire protocol is JSON-RPC 2.0 in every case; only the transport differs (stdio subprocess, Streamable HTTP, or the legacy HTTP+SSE). A transport interface hides that difference so the MCP-level logic — handshake, tools/list, tools/call — is written once.

Package registry provides a universal plugin registry: agents can discover, download, install, and manage MCP plugin servers at runtime without recompilation. This makes the agent truly universal — any capability can be added on demand.

Registry layout (~/.ok/plugins/):

plugins/
  index.json          — cached registry index
  installed.json      — local install manifest
  <name>/             — one directory per plugin
    plugin.json       — manifest (name, version, entrypoint, tools, prompts)
    ...               — plugin files

Usage from the agent:

/plugin install <name-or-url>   — install a plugin
/plugin list                    — list installed
/plugin search <query>          — search registry
/plugin remove <name>           — uninstall
/plugin update <name>           — update to latest

Index

• Constants
• func RegisterTransport(kind string, fn TransportFactory)
• func RegistryDir() string
• func RemovePlugin(name string) error
• type Client
• type HealthResult
• type Host
  • func NewHost() *Host
  • func StartAll(ctx context.Context, specs []Spec) (*Host, []tool.Tool, error)
  • func (h *Host) Add(ctx context.Context, s Spec) ([]tool.Tool, error)
  • func (h *Host) Close()
  • func (h *Host) HealthCheck(ctx context.Context) []HealthResult
  • func (h *Host) Prompts() []Prompt
  • func (h *Host) ReadResource(ctx context.Context, server, uri string) (string, error)
  • func (h *Host) Remove(name string) (toolPrefix string, found bool)
  • func (h *Host) Resources() []Resource
  • func (h *Host) ServerNames() []string
  • func (h *Host) Servers() []ServerStatus
• type InstalledManifest
  • func ListInstalled() (*InstalledManifest, error)
• type InstalledPlugin
  • func InstallPlugin(nameOrURL string) (*InstalledPlugin, error)
• type Prompt
  • func (p Prompt) Get(ctx context.Context, args map[string]string) (string, error)
• type PromptArg
• type RegistryEntry
  • func SearchRegistry(query string) []RegistryEntry
• type RegistryIndex
  • func BuiltinPluginIndex() RegistryIndex
• type Resource
• type ServerStatus
• type Spec
• type TransportFactory

Constants

const DefaultRegistryURL = "https://plugins.ok.sh/index.json"

DefaultRegistryURL is the official OK plugin registry.

const ProtocolVersion = "2024-11-05"

ProtocolVersion is the MCP revision OK advertises during initialize. Exported so external commands (e.g. ok-plugin-example) can reference the single source of truth.

Functions

func RegisterTransport

func RegisterTransport(kind string, fn TransportFactory)

RegisterTransport registers a transport factory under the given type name. Called from init() in transport implementation packages. A duplicate panics at init time — that is a compile-time wiring mistake.

func RegistryDir

func RegistryDir() string

RegistryDir returns the plugin registry directory.

func RemovePlugin

func RemovePlugin(name string) error

RemovePlugin uninstalls a plugin by name.

Types

type Client

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

Client is one MCP server connection: a name plus the transport carrying its JSON-RPC. The MCP-level methods (initialize, listTools, …) are transport- agnostic — they go through t.

type HealthResult

type HealthResult struct {
	Name  string
	Err   string // empty when healthy
	Tools int
	Alive bool
}

HealthResult reports the outcome of pinging one server.

type Host

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

Host owns the running plugin connections and closes them together. It also aggregates the prompts and resources discovered across servers, which the chat UI surfaces (prompts as slash commands, resources as @-references). Safe for concurrent use.

func NewHost

func NewHost() *Host

NewHost returns an empty Host. Boot always constructs one — even with no plugins configured — so servers can be hot-added later via Add (the `/mcp add` command), which keeps the controller's host pointer stable for the session.

func StartAll

func StartAll(ctx context.Context, specs []Spec) (*Host, []tool.Tool, error)

StartAll connects every plugin, performs the MCP handshake, and returns the union of their tools (namespaced "mcp__<server>__<tool>"). On any failure it tears down everything started so far. The caller must Close the Host.

For stdio plugins, subprocess lifetime is bound to ctx (via exec.CommandContext): canceling ctx kills the children and unblocks reads.

func (*Host) Add

func (h *Host) Add(ctx context.Context, s Spec) ([]tool.Tool, error)

Add connects one server live: it performs the MCP handshake, discovers the server's tools (and prompts/resources when advertised), appends it to the host, and returns its namespaced tools for the caller to register. ctx bounds a stdio child's lifetime, so pass the session-scoped context — not a per-turn one — or the subprocess dies when that turn ends. Errors if the name is taken.

func (*Host) Close

func (h *Host) Close()

Close terminates all plugin connections.

func (*Host) HealthCheck

func (h *Host) HealthCheck(ctx context.Context) []HealthResult

HealthCheck pings every connected server and returns results. Unhealthy servers are not automatically restarted — callers decide policy.

func (*Host) Prompts

func (h *Host) Prompts() []Prompt

Prompts returns a copy of every MCP prompt discovered across connected servers.

func (*Host) ReadResource

func (h *Host) ReadResource(ctx context.Context, server, uri string) (string, error)

ReadResource reads a resource uri from the named server. It is how the chat UI resolves an @server:uri reference — the uri need not be one listed by resources/list (servers may expose templated uris), so we read it directly.

func (*Host) Remove

func (h *Host) Remove(name string) (toolPrefix string, found bool)

Remove disconnects the named server and drops its prompts/resources, returning the namespaced tool-name prefix ("mcp__<server>__") the caller unregisters from the tool registry, and whether the server was connected.

func (*Host) Resources

func (h *Host) Resources() []Resource

Resources returns a copy of every MCP resource discovered across connected servers.

func (*Host) ServerNames

func (h *Host) ServerNames() []string

ServerNames returns the connected servers' names, in connection order.

func (*Host) Servers

func (h *Host) Servers() []ServerStatus

Servers returns a status summary per connected server, in connection order.

type InstalledManifest

type InstalledManifest struct {
	Plugins []InstalledPlugin `json:"plugins"`
}

InstalledManifest tracks what's installed locally.

func ListInstalled

func ListInstalled() (*InstalledManifest, error)

ListInstalled returns all locally installed plugins.

type InstalledPlugin

type InstalledPlugin struct {
	Name    string   `json:"name"`
	Version string   `json:"version"`
	Path    string   `json:"path"`
	Tools   []string `json:"tools"`
	Prompts []string `json:"prompts"`
	Running bool     `json:"running"`
}

InstalledPlugin describes a locally installed plugin.

func InstallPlugin

func InstallPlugin(nameOrURL string) (*InstalledPlugin, error)

InstallPlugin downloads and installs a plugin by name or URL. Returns the installed plugin info.

type Prompt

type Prompt struct {
	Name        string      // "mcp__<server>__<prompt>" — the slash-command body
	Server      string      // owning server name
	Raw         string      // original prompt name for prompts/get
	Description string      // human-readable summary
	Args        []PromptArg // declared arguments, in order
	// contains filtered or unexported fields
}

Prompt is an MCP prompt exposed by a server. It surfaces in the chat TUI as a slash command "/mcp__<server>__<prompt>"; running it fetches the rendered prompt and sends it to the model as a turn.

func (Prompt) Get

func (p Prompt) Get(ctx context.Context, args map[string]string) (string, error)

Get fetches the prompt with the given arguments and flattens its returned messages into a single text block to send to the model.

type PromptArg

type PromptArg struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
}

PromptArg is one declared prompt argument. OK maps space-separated positional command arguments onto these in order, matching Claude Code.

type RegistryEntry

type RegistryEntry struct {
	Name         string   `json:"name"`
	Description  string   `json:"description"`
	Version      string   `json:"version"`
	URL          string   `json:"url"`      // download URL (tar.gz)
	Homepage     string   `json:"homepage"` // docs/source
	Tags         []string `json:"tags"`     // email, browser, database, gaming, etc.
	MinOKVersion string   `json:"min_ok_version"`
}

RegistryEntry describes one available plugin in the registry.

func SearchRegistry

func SearchRegistry(query string) []RegistryEntry

SearchRegistry searches the plugin index for matching tags/names.

type RegistryIndex

type RegistryIndex struct {
	Version string          `json:"version"`
	Plugins []RegistryEntry `json:"plugins"`
}

RegistryIndex is the cached manifest from the official plugin registry.

func BuiltinPluginIndex

func BuiltinPluginIndex() RegistryIndex

BuiltinPluginIndex returns a hardcoded index of trusted plugins that ship with OK. This index is embedded so the agent can self-bootstrap without network access on first run. Tier 1: Official OK v4 MCP plugins (bundled, always available). Tier 2: Curated third-party plugins (install on demand).

type Resource

type Resource struct {
	Server      string // owning server name
	URI         string // canonical resource uri
	Name        string // human-readable label
	Description string
	MimeType    string
}

Resource is an MCP resource a server exposes. In chat it is referenced as "@<server>:<uri>" (e.g. "@docs:file://README.md"); the referenced content is fetched and prepended to the message sent to the model.

type ServerStatus

type ServerStatus struct {
	Name      string
	Transport string
	Tools     int
	Prompts   int
	Resources int
	Healthy   bool // false when the last health check failed
}

ServerStatus summarizes one connected server for the /mcp command.

type Spec

type Spec struct {
	Name    string
	Type    string
	Command string
	Args    []string
	Env     map[string]string
	URL     string
	Headers map[string]string
	// Dir, when set, is the working directory of a stdio subprocess. Empty means
	// inherit ok's cwd (the default for user-configured plugins). It exists
	// for cwd-aware servers like CodeGraph, which detect the project from the
	// directory they are launched in — they must be pinned to the project root.
	Dir string
}

Spec declares an external MCP server. Type selects the transport: "stdio" (default) runs Command/Args/Env as a subprocess; "http" / "streamable-http" and "sse" connect to URL with optional static Headers.

type TransportFactory

type TransportFactory func(ctx context.Context, s Spec) (transport, error)

TransportFactory creates a transport from a Spec. RegisterTransport allows third-party transport implementations to register without modifying newTransport's switch statement.