Documentation
¶
Overview ¶
Package mcpserver assembles the MCP server behind `hey mcp`: hey's tool catalog derived from hey-sdk's model exports, dispatched through the CLI's authenticated SDK client.
The generic machinery — joining behavior-model.json with openapi.json, rendering domain gateway tools, action dispatch, read-only filtering, the in-band describe action — lives in the shared toolkit at github.com/basecamp/mcp. This package supplies the product half: the curated DomainSpecs mapping hey-sdk tags to domains, the vendored model snapshot under model/ (synced by scripts/sync-mcp-model.sh, provenance recorded), and the dispatcher that turns catalog operations into hey-sdk requests.
Index ¶
Constants ¶
const Name = "hey-cli"
Name identifies the server in the MCP initialize handshake. The version is the CLI's own: `hey mcp` is the CLI serving MCP, not a separate product.
Variables ¶
var DomainSpecs = []catalog.DomainSpec{ { Key: "boxes", Tags: []string{"Boxes"}, Blurb: "HEY mail boxes: the Imbox, Feed, Paper Trail, Reply Later, Set Aside and Bubble Up stacks, box groups and designations, and incremental posting changes.", }, { Key: "search", Tags: []string{"Search"}, Blurb: "Search HEY mail: advanced search with the same refinements the search page offers.", }, { Key: "threads", Tags: []string{"Topics", "Entries", "Messages"}, Blurb: "HEY email threads: topics and their entries, full message content, replies and forwards, drafts, and triage (trash, spam, restore, move).", }, { Key: "contacts", Tags: []string{"Contacts"}, Blurb: "HEY contacts and the Screener: contact records and notes, bundling, and clearance (screening) decisions.", }, { Key: "todos", Tags: []string{"Calendar Todos"}, Blurb: "HEY Calendar todos: create, update, complete, uncomplete, and delete. Read existing todos through the calendar domain's get_calendar_recordings.", }, { Key: "calendar", Tags: []string{"Calendars"}, Blurb: "HEY Calendars: list calendars, read their recordings (todos and events — the todo read path), and toggle calendar visibility.", }, { Key: "identity", Tags: []string{"Identity"}, Blurb: "Your HEY identity: accounts, senders, and preferences — the acting_sender_id and acting_user_id lookups that replies and contact writes ask for.", }, }
DomainSpecs curates which slice of the hey-sdk surface each domain gateway tool exposes, in tool display order. Tags are hey-sdk's OpenAPI tags (each operation carries exactly one); a spec may merge several tags into one tool. This mapping is the only hand-maintained part of the catalog — everything else derives from the SDK model via the toolkit.
The first release serves five domains covering everyday mail and task work: boxes, search, threads, contacts, todos. Tags left unmapped are reported in Catalog.Unmapped and pinned by tests, so growing the surface is a one-line change here plus a snapshot refresh.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API interface {
Get(ctx context.Context, path string) (*hey.Response, error)
Post(ctx context.Context, path string, body any) (*hey.Response, error)
Put(ctx context.Context, path string, body any) (*hey.Response, error)
Patch(ctx context.Context, path string, body any) (*hey.Response, error)
Delete(ctx context.Context, path string) (*hey.Response, error)
}
API is the slice of the hey-sdk client the dispatcher drives. *hey.Client satisfies it; the client carries auth, account scoping, retry, and base URL resolution, so the dispatcher only assembles paths and bodies. Retry policy is the implementation's to choose per verb — the CLI wires reads through a retrying client and every mutation through one that never retries, because a retried PUT can deliver a message twice.
type Config ¶
type Config struct {
// ReadOnly drops every write action from the catalog and refuses write
// dispatch outright.
ReadOnly bool
// Domains narrows the served domains by key ("boxes", "search", ...).
// Empty means all. Unknown keys are a startup error — fail closed.
Domains []string
}
Config selects the served tool surface.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps the toolkit gateway serving hey's derived catalog, dispatching through the CLI's authenticated SDK client.
func New ¶
New derives the catalog and hands it to the gateway, which applies the config's domain and read-only filters. Tool calls dispatch through api.
func (*Server) BuildMCPServer ¶
BuildMCPServer constructs the SDK MCP server with one gateway tool per served domain.
Source Files