Documentation
¶
Overview ¶
Package mcpserver implements a JSON-RPC 2.0 MCP stdio server supporting both newline-delimited JSON (NDJSON) and Content-Length header framing.
Index ¶
- Constants
- func IsLoopbackBindAddr(addr string) bool
- func ValidateHTTPOptions(opts HTTPOptions) error
- type HTTPOptions
- type Server
- func (s *Server) HTTPHandler(opts HTTPOptions) http.Handler
- func (s *Server) ListenAndServeHTTP(ctx context.Context, opts HTTPOptions, onBound func(addr string)) error
- func (s *Server) Serve(ctx context.Context, in io.Reader, out io.Writer) error
- func (s *Server) ServeHTTP(ctx context.Context, opts HTTPOptions) error
- type ServerOptions
- type ToolSet
Constants ¶
const ( ServerName = "mcplex" ServerVersion = version.Version DefaultProtocolVersion = "2025-11-25" )
Variables ¶
This section is empty.
Functions ¶
func IsLoopbackBindAddr ¶ added in v0.4.0
IsLoopbackBindAddr reports whether an HTTP listen address (`host:port`) binds strictly to loopback.
func ValidateHTTPOptions ¶ added in v0.4.0
func ValidateHTTPOptions(opts HTTPOptions) error
ValidateHTTPOptions enforces safe-by-default authentication invariants before exposing HTTP endpoints.
Types ¶
type HTTPOptions ¶
type HTTPOptions struct {
Addr string // e.g. "127.0.0.1:8787"
Path string // defaults to "/mcp"
Token string // optional Bearer token required on /mcp, /events, /api/events
AllowOrigin string // optional CORS Access-Control-Allow-Origin value
AllowInsecureNoToken bool // explicitly permit non-loopback bind or wildcard CORS without Token
SessionIdleTTL time.Duration // idle session TTL before auto-reaping tasks/spills (0 -> 30m, <0 disables)
// AllowedHosts are extra Host header values accepted on a loopback bind, e.g. the public hostname of a
// Cloudflare tunnel (--public-url). DNS rebinding cannot make such a public name resolve to the victim loopback.
AllowedHosts []string
// OAuth, when set, serves the OAuth 2.1 authorization server + metadata endpoints and accepts its access tokens
// on the MCP endpoint (in addition to Token). Its public host is added to the Host-header allowlist.
OAuth *oauthserver.Server
// TokenFunc optionally returns the live bearer token (used by interactive --ui token generation/rotation).
// When non-nil, it supersedes Token on every request.
TokenFunc func() string
}
HTTPOptions configures the MCP Streamable HTTP transport.
type Server ¶
type Server struct {
Engine *ptcruntime.Engine
// contains filtered or unexported fields
}
Server speaks MCP JSON-RPC 2.0 over stdio (NDJSON & Content-Length) and Streamable HTTP.
func NewServer ¶
func NewServer(engine *ptcruntime.Engine) *Server
NewServer wraps an Engine in an MCP server with default options.
func NewServerWithOptions ¶
func NewServerWithOptions(engine *ptcruntime.Engine, opts ServerOptions) *Server
NewServerWithOptions wraps an Engine in an MCP server with custom host profile options.
func (*Server) HTTPHandler ¶
func (s *Server) HTTPHandler(opts HTTPOptions) http.Handler
HTTPHandler returns an http.Handler implementing MCP Streamable HTTP over POST /mcp plus GET /healthz, GET /api/events, and GET /events (SSE).
func (*Server) ListenAndServeHTTP ¶ added in v0.3.0
func (s *Server) ListenAndServeHTTP(ctx context.Context, opts HTTPOptions, onBound func(addr string)) error
ListenAndServeHTTP validates security options, binds the TCP listener first, invokes onBound with the actual listening address, runs background idle-session reaping, and serves HTTP until ctx is canceled.
type ServerOptions ¶
type ServerOptions struct {
ServerName string
ServerVersion string // defaults to version.Version
Tools ToolSet // optional standalone tools alongside `exec`
Instructions string // returned in initialize.result.instructions (MCP 2025-03-26+)
ExecDescription string // custom description for the exec tool
DefaultMaxOutBytes int // advertised default inline output cap (0 -> 9600)
SkillResourceURI string // optional MCP resource URI, e.g. "mcplex://skill"
SkillResourceName string
SkillResourceText string
}
ServerOptions customizes server identity, toolset, initialize instructions, exec description, and skill resources.
type ToolSet ¶ added in v0.3.0
type ToolSet struct {
Read bool // expose standalone `read` tool (text ranges, tail, byteOffset, multimodal images)
Tasks bool // expose `spawn` + `task` background process & daemon toolset
Docs bool // expose on-demand `docs` lookup tool (topic/keyword reference for exec APIs & patterns)
}
ToolSet controls which optional MCP tools are exposed alongside the core `exec` tool. Zero value exposes only `exec` (used by host plugins like agy-ptc that already have native read/task tools).