Documentation
¶
Overview ¶
Package server provides the small MCP server surface used by a product's injected collaboration process.
The package deliberately keeps the SDK behind this boundary. Callers register product-owned tools and handlers, while the package owns MCP framing, capability advertisement, bounds, and wire-error classification.
Index ¶
- Constants
- Variables
- type Config
- type Content
- type Handler
- type Result
- type Server
- func (s *Server) AddTool(tool Tool) error
- func (s *Server) Config() Config
- func (s *Server) Register(tool Tool) error
- func (s *Server) RegisterTool(tool Tool) error
- func (s *Server) Run(ctx context.Context) error
- func (s *Server) Serve(ctx context.Context, reader io.Reader, writer io.Writer) error
- func (s *Server) ServeStdio(ctx context.Context, reader io.Reader, writer io.Writer) error
- type ServerConfig
- type Tool
- type ToolHandler
- type ToolResult
Constants ¶
const ( DefaultServerName = "carbon-collab-mcp" DefaultServerVersion = "0.1.0" // DefaultMaxInputBytes bounds one tools/call arguments value before the // application handler is invoked. DefaultMaxInputBytes = 256 << 10 // DefaultMaxOutputBytes bounds a handler's structured result and encoded // content before the SDK is allowed to serialize it. DefaultMaxOutputBytes = 256 << 10 // MaxFrameOverheadBytes is reserved for the JSON-RPC/MCP envelope around a // bounded argument or result. It is part of the frame policy, not an // allowance for application payloads. MaxFrameOverheadBytes = 4 << 10 // MaxRequestIDBytes bounds the encoded JSON-RPC request ID (including JSON // quotes for a string). The ID is echoed into every response, so this bound // is reserved from the frame overhead rather than allowed to consume // application payload capacity. MaxRequestIDBytes = MaxFrameOverheadBytes - 512 // DefaultMaxMessageBytes bounds one newline-delimited MCP frame's JSON // bytes. The final '\n' delimiter is excluded from this count. The default // is deliberately larger than the maximum argument/result plus the // envelope, so a handler-valid boundary value cannot fail at transport. DefaultMaxMessageBytes = DefaultMaxOutputBytes + MaxFrameOverheadBytes DefaultMaxConcurrentRequests = 8 MaxConcurrentRequests = DefaultMaxConcurrentRequests )
The default identity is intentionally explicit: an empty SDK implementation would otherwise produce an invalid peer identity on the wire.
const ( MaxMessageBytes = DefaultMaxMessageBytes MaxInputBytes = DefaultMaxInputBytes MaxOutputBytes = DefaultMaxOutputBytes )
These aliases make the policy easy to discover without creating a second set of values. They are hard bounds in the default configuration; callers may choose a smaller bound in Config.
Variables ¶
var ( // ErrInvalidArgument classifies a handler failure as an MCP invalid-params // error. Its text is never sent to a peer, so wrapping it cannot disclose a // handler's detail. ErrInvalidArgument = errors.New("invalid argument") // ErrInternal classifies a handler failure as an MCP internal error. ErrInternal = errors.New("internal error") // ErrInvalidToolName means a tool name is empty, too long, or contains a // character outside the MCP tool-name alphabet. ErrInvalidToolName = errors.New("invalid tool name") // ErrDuplicateTool means a tool name has already been registered. ErrDuplicateTool = errors.New("duplicate tool") // ErrInvalidToolSchema means the supplied input or output schema is not a // valid JSON object/schema accepted by the MCP SDK. ErrInvalidToolSchema = errors.New("invalid tool schema") // ErrInvalidConfig means a server bound was configured with a non-positive // value or its identity was invalid. ErrInvalidConfig = errors.New("invalid server configuration") // ErrInputLimit and ErrOutputLimit are returned by the framing seams when a // frame or result exceeds the configured bound. ErrInputLimit = errors.New("input exceeds limit") ErrOutputLimit = errors.New("output exceeds limit") // ErrInputEnvelope is returned when a peer-controlled field that is echoed // in a response (currently the JSON-RPC request ID) exceeds its bound. ErrInputEnvelope = errors.New("input envelope exceeds limit") // ErrBatchUnsupported rejects JSON-RPC batch arrays before the SDK can // dispatch any member or construct an aggregate response. ErrBatchUnsupported = errors.New("batch requests are not supported") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Name string
Version string
// MaxMessageBytes bounds each newline-delimited JSON-RPC message.
MaxMessageBytes int
// MaxInputBytes bounds tools/call arguments before a Handler is called.
MaxInputBytes int
// MaxOutputBytes bounds the encoded tools/call result produced by a
// Handler.
MaxOutputBytes int
MaxConcurrentRequests int
}
Config configures a Server. Zero identity fields and bounds select the explicit package defaults. Every running server therefore has a non-empty name, version, and finite input/output bound.
type Content ¶
type Content struct {
Text string
}
Content is the deliberately narrow content surface exposed by this server. Collaboration responses are text plus structured JSON; image/audio/resource content would expand the process boundary without a use in this server.
type Handler ¶
Handler handles one tools/call argument object. Arguments are a defensive copy of the bounded JSON received from the peer. A handler returning ErrInvalidArgument (possibly wrapped) produces JSON-RPC -32602; all other handler errors produce the generic JSON-RPC -32603 message.
type Result ¶
type Result struct {
Content []Content
StructuredContent json.RawMessage
IsError bool
}
Result is the product-owned projection of an MCP tools/call result.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a reusable, one-session MCP server. It is safe to register tools before Serve is called; each tool name can be registered at most once.
func New ¶
New constructs a server with explicit identity, tools-only capabilities, and bounded framing. It does not start I/O.
func (*Server) AddTool ¶
AddTool is an alias for RegisterTool for callers familiar with the SDK's terminology.
func (*Server) RegisterTool ¶
RegisterTool adds one tool. Duplicate and invalid names are returned as typed sentinel errors; the underlying SDK's replacing AddTool behavior is intentionally not exposed.
func (*Server) Run ¶
Run serves the process's stdin/stdout. It is the convenience entry point for a stdio executable; tests and embedded callers should use Serve.
func (*Server) Serve ¶
Serve runs the server over stdio-shaped streams. The reader and writer may be ordinary io.Reader/io.Writer values; if they also implement io.Closer, cancellation closes them so a blocked SDK read is released. A frame is newline-delimited, as required by the SDK's stdio transport.
type Tool ¶
type Tool struct {
Name string
Title string
Description string
InputSchema json.RawMessage
OutputSchema json.RawMessage
Handler Handler
}
Tool is a product-owned tool definition. InputSchema must be a JSON object schema; an omitted schema means any object. OutputSchema is optional. SDK types intentionally do not appear in this exported API.
Source Files