🤖 mcp

amadan.net/rastrillo/rastrillo/mcp

An app's operations as MCP tools, behind the JSON API's gate. MCP is the guide: mounting, connecting a client, and writing descriptors by hand.

New and Config

func New(config Config, descriptors ...op.Descriptor) (http.Handler, error)

type Config struct {
	Gate          api.Gate
	Ctx           func(*http.Request) *rastrillo.Ctx
	Authorize     func(ctx context.Context, actor rastrillo.Actor, operation rastrillo.Operation) error
	Guard         op.ResponseGuard
	Guarded       bool
	Name, Version string
	Instructions  string
	MaxResult     int
}

New builds the MCP endpoint, with one tool per descriptor. Mount it at /api/v1/mcp.

Gate is the API tree's, from api.Config.Gate(). Ctx builds the app's Ctx for a request, and MCP sets Actor and Authorize on a copy of it. Authorize is required: pass op.DefaultPolicy to keep the default. Guard checks what an answer discloses as it goes out, and Guarded requires one. Name and Version are the server's in the MCP handshake. Instructions follows the framework's own instructions to the agent. MaxResult caps one tool result in bytes; zero or less means 2 MiB.

New returns an error when:

• Ctx or Authorize is nil, or Gate.Validate fails;
• Guard is set and Gate.Verify isn't an api.Rechecker;
• Guarded is set and there is no Guard, or no Rechecker;
• a descriptor has an empty ID, an invalid Access, an Input that isn't an object schema, a Result that is neither an object schema nor exactly {"type":"null"}, or a nil Invoke;
• a descriptor fails op.CheckFlags;
• a tool name doesn't match ^[a-z][a-z0-9_]{0,63}$, or two descriptors have the same tool name;
• the SDK refuses a tool.

The handler runs every request behind Gate.Wrap, so a missing or bad token gets the API's 401 or 503, and every answer has Cache-Control: no-store. Then:

• It answers only POST. Any other method, GET included, is 405 with Allow: POST. A batch is 400, and subscriptions/listen is 404, each with a JSON-RPC error.
• Send Accept: application/json, text/event-stream and Content-Type: application/json with each POST. Without Accept, the SDK returns a plain-text 400. Without Content-Type, it returns a plain-text 415. These are not JSON-RPC errors.
• A message whose id is a number is refused unless the number is a plain integer, with no fraction or exponent, within ±9007199254740991. The SDK would round any other number, and the answer would carry a different id. The refusal is 400 with JSON-RPC error -32600 and a null id, and nothing runs. A string id is never refused.
• Each request gets its own stateless server, which answers plain JSON and never advertises list changes.
• tools/list shows only the tools Gate.Admit and op.Check allow the caller, without the agent-session check, which a list never needs. Only op.Forbidden or op.NotFound hides a tool. Any other error fails the list as a JSON-RPC internal error, with a ref in its data.
• A tool call runs Gate.Admit and op.Check before Invoke, so a hand-written Invoke that skips op.Check is still checked. A refusal is a tool error holding the API's error envelope, from api.Refusal. A panic in a call is an internal tool error with a ref. So is a result that isn't an object, including null, when the tool's Result is an object schema.
• With a Rechecker, the gate checks the answer again as it goes out. For a call, it reruns Admit and op.Check for the operation that ran on every answer. It runs Guard only when the call returned a successful result. For the list, it reruns them for every tool that was listed, then runs Guard with a nil descriptor and the listed descriptors as the result.

New raises Gate.MaxResponse, when it is lower, to three times MaxResult plus 64 KiB. A result goes out twice, as structuredContent and as the text block, and escaping can make the text longer.

ToolName

func ToolName(id string) string

The tool an operation is served as: bookmarks.create is bookmarks_create.

Read this page as markdown — exact, unstyled, and cheap for an agent to fetch.