server

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 6, 2026 License: MIT Imports: 6 Imported by: 0

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

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 PromptArg

type PromptArg struct {
	Name        string
	Description string
	Required    bool
}

PromptArg describes a single argument accepted by a prompt.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is the ado-mcp application server.

func New

func New(name, version string, readOnly bool) *Server

New creates a Server with the given name/version and read-only policy.

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

func (s *Server) Connect(ctx context.Context, t mcp.Transport) (*mcp.ServerSession, error)

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

func (s *Server) NoteToolset(name string)

NoteToolset records that a toolset is being registered. Call once per area.

func (*Server) PromptCount

func (s *Server) PromptCount() int

PromptCount returns the number of prompts registered so far.

func (*Server) ReadOnly

func (s *Server) ReadOnly() bool

ReadOnly reports whether mutating tools are suppressed.

func (*Server) Run

func (s *Server) Run(ctx context.Context, t mcp.Transport) error

Run serves the MCP protocol over the given transport until the context is cancelled or the client disconnects.

func (*Server) ToolCount

func (s *Server) ToolCount() int

ToolCount returns the number of tools registered so far.

func (*Server) Toolsets

func (s *Server) Toolsets() []string

Toolsets returns the names of registered toolsets.

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.

type Toolset

type Toolset struct {
	Name     string
	Register func(s *Server, c *ado.Clients)
}

Toolset pairs a toolset name with the function that registers its tools. Each Azure DevOps area exposes one of these so the entrypoint can register only the toolsets enabled by configuration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL