Documentation
¶
Overview ¶
Package mcpserver exposes Chronos tools to any Model Context Protocol (MCP) host — Claude Desktop, IDEs, and other agent frameworks — over JSON-RPC 2.0. It is the server counterpart to the MCP client in engine/mcp: where the client consumes external MCP servers, this lets Chronos BE one.
Tools are sourced from an internal tool.Registry, so a tools/call dispatches through Registry.Execute and automatically honors each tool's Permission, the approval hook, and the panic-to-error recovery already built into the engine. Remote exposure defaults to requiring approval (see WithDefaultPermission), following the safe-by-default precedent for remotely invokable tools.
Two transports are provided, mirroring the client: newline-delimited JSON-RPC over stdio (ServeStdio) and HTTP+SSE (SSEHandler). The JSON-RPC dispatch is transport-agnostic (HandleMessage), so both transports share one code path.
Index ¶
- type Option
- type Server
- func (s *Server) Expose(def *tool.Definition)
- func (s *Server) ExposeAll(r *tool.Registry)
- func (s *Server) HandleMessage(ctx context.Context, raw []byte) (response []byte, reply bool)
- func (s *Server) SSEHandler() http.Handler
- func (s *Server) ServeStdio(ctx context.Context, in io.Reader, out io.Writer) error
- func (s *Server) SetApprover(a tool.Approver)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Server)
Option configures a Server.
func WithDefaultPermission ¶
func WithDefaultPermission(p tool.Permission) Option
WithDefaultPermission sets the permission applied to an exposed tool whose Definition leaves Permission unset. The default is tool.PermRequireApproval, so a remotely invocable tool needs explicit human approval unless the caller deliberately exposes it as tool.PermAllow.
func WithVersion ¶
WithVersion sets the server version advertised to clients.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server exposes a set of tools over MCP. It is safe for concurrent use once constructed; expose tools and set the approver before serving.
func (*Server) Expose ¶
func (s *Server) Expose(def *tool.Definition)
Expose makes def callable by MCP hosts. A def with no Permission set inherits the server's default permission (require-approval), so nothing is silently remotely-executable without an explicit opt-in.
It registers a shallow copy rather than mutating the caller's Definition, so exposing a tool never changes how it behaves for local (non-MCP) use.
func (*Server) ExposeAll ¶
ExposeAll exposes every tool in r, applying the default permission to any tool that has none. It is a convenience for publishing an existing registry.
func (*Server) HandleMessage ¶
HandleMessage processes one raw JSON-RPC message and returns the raw response to send back, or reply=false when the message is a notification (no id) that needs no response. It never returns an error: a malformed (but size-bounded) message becomes a JSON-RPC error response, and tool failures become isError tool results, so one bad message never tears down the transport. Transport- level faults (e.g. an over-cap frame) are handled by the transport, not here.
func (*Server) SSEHandler ¶
SSEHandler returns an http.Handler implementing the MCP HTTP+SSE transport on a single path. A GET opens the event stream and is answered with an `endpoint` event naming the URL (this path plus ?session=<id>) to POST JSON-RPC requests to; each POST is processed and its response pushed back to that session's stream as a `message` event. This mirrors the engine/mcp SSE client.
func (*Server) ServeStdio ¶
ServeStdio runs the MCP server over newline-delimited JSON-RPC on in/out, blocking until in reaches EOF or ctx is canceled. Each request is dispatched sequentially and its response written as one line; notifications produce no output.
A frame larger than maxLineBytes is a transport-level fault (bufio.ErrTooLong) and ends the stream with an error — distinct from a malformed-but-bounded message, which HandleMessage turns into an error response without tearing down the connection.
func (*Server) SetApprover ¶
SetApprover wires a human-in-the-loop approval service into the tool path, so require-approval tools block for a decision before executing. Without one, a require-approval tool call fails (never silently runs).
Source Files