Documentation
¶
Overview ¶
Package server wires the Model Context Protocol server together: it owns the underlying mcp.Server, enforces the read-only policy, and exposes typed helpers that the per-area tool packages use to register tools.
Tools are registered through the generic Register function, which derives the JSON input/output schema from Go types, attaches MCP annotation hints, and transparently skips mutating tools when the server runs in read-only mode.
Index ¶
- func Register[In, Out any](s *Server, def ToolDef, h mcp.ToolHandlerFor[In, Out])
- type ListResult
- type PagedListResult
- type PromptArg
- type Server
- func (s *Server) AddPrompt(name, description string, args []PromptArg, ...)
- func (s *Server) Connect(ctx context.Context, t mcp.Transport) (*mcp.ServerSession, error)
- func (s *Server) NoteToolset(name string)
- func (s *Server) PromptCount() int
- func (s *Server) ReadOnly() bool
- func (s *Server) Run(ctx context.Context, t mcp.Transport) error
- func (s *Server) ToolCount() int
- func (s *Server) Toolsets() []string
- type ToolDef
- type Toolset
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
func Register[In, Out any](s *Server, def ToolDef, h mcp.ToolHandlerFor[In, Out])
Register adds a typed tool to the server. In and Out are arbitrary structs: their JSON schemas are inferred automatically, inputs are validated against the schema before the handler runs, and outputs are returned as structured content. Mutating tools (def.Write) are silently skipped in read-only mode.
The handler should return business results as the Out value; transport- and API-level failures should be returned as the error, which Register surfaces to the client as a tool error rather than a protocol error.
Types ¶
type ListResult ¶
type ListResult[T any] struct { Count int `json:"count" jsonschema:"number of items returned"` Items []T `json:"items" jsonschema:"the returned items"` }
ListResult wraps a collection of items. The MCP specification requires a tool's structured output to be a JSON object, so list-returning tools cannot return a bare array; they return a ListResult instead. The wrapper also gives the model an explicit item count.
func List ¶
func List[T any](items []T) ListResult[T]
List builds a ListResult from a slice, computing the count.
type PagedListResult ¶ added in v0.1.2
type PagedListResult[T any] struct { Count int `json:"count" jsonschema:"number of items returned"` Items []T `json:"items" jsonschema:"the returned items"` ContinuationToken string `` /* 126-byte string literal not displayed */ }
PagedListResult wraps a page of items along with the token to fetch the next page (empty when there is none). Use this instead of ListResult for endpoints whose next-page token arrives on the HTTP response rather than in the JSON body (e.g. Azure DevOps' Graph list endpoints, via the X-MS-ContinuationToken response header) — ListResult has nowhere to put it, which would otherwise silently truncate pagination after the first page.
func PagedList ¶ added in v0.1.2
func PagedList[T any](items []T, continuationToken string) PagedListResult[T]
PagedList builds a PagedListResult from a slice and a continuation token.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the ado-mcp application server.
func (*Server) AddPrompt ¶
func (s *Server) AddPrompt(name, description string, args []PromptArg, render func(args map[string]string) string)
AddPrompt registers a prompt (a user-invoked, parameterized template that clients surface as a slash command). The render function builds the prompt text from the supplied argument values; the result is returned to the client as a single user message that guides the model through a multi-step flow.
func (*Server) Connect ¶
Connect serves the MCP protocol over the given transport, returning the session. Unlike Run it does not block; it is primarily used by tests that drive the server in-process via an in-memory transport.
func (*Server) NoteToolset ¶
NoteToolset records that a toolset is being registered. Call once per area.
func (*Server) PromptCount ¶
PromptCount returns the number of prompts registered so far.
func (*Server) Run ¶
Run serves the MCP protocol over the given transport until the context is cancelled or the client disconnects.
type ToolDef ¶
type ToolDef struct {
// Name is the unique tool identifier, e.g. "wit_get_work_item".
Name string
// Title is an optional human-readable display name.
Title string
// Description tells the model what the tool does and when to use it.
Description string
// Write marks the tool as mutating. Write tools are skipped entirely when
// the server is in read-only mode and are annotated readOnlyHint=false.
Write bool
// Destructive hints that the tool may delete or overwrite data (e.g. delete
// a work item). Only meaningful for write tools.
Destructive bool
// Idempotent hints that repeating the call with identical arguments has no
// further effect. Only meaningful for write tools.
Idempotent bool
}
ToolDef describes a tool to register. The zero value is a read-only, non-destructive tool.