mcpsrv

Documentation

Overview

Package mcpsrv provides an extensible MCP server for powhttp.

This package exposes a high-level API for creating and running an MCP server with all builtin powhttp tools, prompts, and resources. Users can extend the server with custom tools, prompts, and resources using functional options.

Basic Usage

Create a server with default configuration:

server, err := mcpsrv.NewServer(client.New())
if err != nil {
    log.Fatal(err)
}
server.Run(ctx)

Extension

Add custom tools using MCP SDK types directly:

import mcp "github.com/modelcontextprotocol/go-sdk/mcp"

type MyInput struct {
    Query string `json:"query"`
}

type MyOutput struct {
    Count int `json:"count"`
}

func myHandler(ctx context.Context, req *mcp.CallToolRequest, input MyInput) (*mcp.CallToolResult, MyOutput, error) {
    return nil, MyOutput{Count: 42}, nil
}

server, err := mcpsrv.NewServer(
    client.New(),
    mcpsrv.WithTool(&mcp.Tool{Name: "my_tool", Description: "My tool"}, myHandler),
)

Configuration

Configure logging and other options:

server, err := mcpsrv.NewServer(
    client.New(),
    mcpsrv.WithLogLevel("debug"),
    mcpsrv.WithLogFile("/var/log/powhttp-mcp.log"),
)

Index

• func AddTool[In, Out any](srv *sdkmcp.Server, t *sdkmcp.Tool, h sdkmcp.ToolHandlerFor[In, Out])
• type Deps
  • func (d *Deps) DecodeBody(entry *client.SessionEntry, target string) ([]byte, string, error)
  • func (d *Deps) FetchEntry(ctx context.Context, sessionID, entryID string) (*client.SessionEntry, error)
• type Option
  • func WithDepsTool[In, Out any](tool *mcp.Tool, builder func(*Deps) ...) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithLogFile(path string) Option
  • func WithLogLevel(level string) Option
  • func WithPrompt(prompt *mcp.Prompt, ...) Option
  • func WithResourceTemplate(template *mcp.ResourceTemplate, ...) Option
  • func WithTool[In, Out any](tool *mcp.Tool, ...) Option
  • func WithoutBuiltinPrompts() Option
  • func WithoutBuiltinTools() Option
• type Server
  • func NewServer(c *client.Client, opts ...Option) (*Server, error)
  • func (s *Server) Close() error
  • func (s *Server) Deps() *Deps
  • func (s *Server) Run(ctx context.Context) error

Functions

func AddTool

func AddTool[In, Out any](srv *sdkmcp.Server, t *sdkmcp.Tool, h sdkmcp.ToolHandlerFor[In, Out])

AddTool registers a tool with the server, validating that the output type's zero value passes the SDK's JSON schema check. This catches nil-slice-as-null bugs at startup: Go's json.Marshal serializes nil slices as null, but the SDK infers "type": "array" from the Go type, so null fails validation at runtime.

If the zero value of Out fails schema validation, AddTool panics with an actionable message telling the caller which field to fix.

Use this instead of sdkmcp.AddTool to get the additional check.

Types

type Deps

type Deps struct {
	Client       *client.Client
	Indexer      *indexer.Indexer
	Cache        *cache.EntryCache
	Config       *config.Config
	Search       *search.SearchEngine
	Fingerprint  *compare.FingerprintEngine
	Diff         *compare.DiffEngine
	Cluster      *catalog.ClusterEngine
	Describe     *catalog.DescribeEngine
	ClusterStore *catalog.ClusterStore
	Flow         *flow.FlowEngine
	TextQuery    *textquery.Engine
}

Deps contains all dependencies available to custom tools. This gives custom tools access to the same infrastructure as builtin tools.

func (*Deps) DecodeBody

func (d *Deps) DecodeBody(entry *client.SessionEntry, target string) ([]byte, string, error)

DecodeBody extracts and base64-decodes the body for a given target ("request" or "response"). Returns the decoded bytes and the content-type header value. Does not filter by content type.

func (*Deps) FetchEntry

func (d *Deps) FetchEntry(ctx context.Context, sessionID, entryID string) (*client.SessionEntry, error)

FetchEntry retrieves an entry by ID, checking the cache first. If not cached, it fetches from the API client and caches the result.

type Option

type Option func(*serverConfig)

Option configures the server.

func WithDepsTool

func WithDepsTool[In, Out any](tool *mcp.Tool, builder func(*Deps) func(context.Context, *mcp.CallToolRequest, In) (*mcp.CallToolResult, Out, error)) Option

WithDepsTool registers a custom tool that has access to Deps. Use this when your tool needs access to search, cache, or other infrastructure.

The builder receives Deps and returns a handler function.

Example:

mcpsrv.WithDepsTool(
    &mcp.Tool{Name: "search_body", Description: "Search HTTP bodies"},
    func(d *mcpsrv.Deps) func(ctx context.Context, req *mcp.CallToolRequest, input MyInput) (*mcp.CallToolResult, MyOutput, error) {
        return func(ctx context.Context, req *mcp.CallToolRequest, input MyInput) (*mcp.CallToolResult, MyOutput, error) {
            results, _ := d.Search.Search(ctx, &search.SearchRequest{Query: input.Query})
            return nil, MyOutput{Count: len(results.Results)}, nil
        }
    },
)

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets a custom HTTP client for the powhttp API. Note: This does not affect the client passed to NewServer.

func WithLogFile

func WithLogFile(path string) Option

WithLogFile sets the log file path. If empty, logs are written to stderr only.

func WithLogLevel

func WithLogLevel(level string) Option

WithLogLevel sets the log level (debug, info, warn, error).

func WithPrompt

func WithPrompt(prompt *mcp.Prompt, handler func(context.Context, *mcp.GetPromptRequest) (*mcp.GetPromptResult, error)) Option

WithPrompt registers a custom prompt with the server.

The handler signature matches the MCP SDK pattern:

func(ctx context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error)

Example:

mcpsrv.WithPrompt(
    &mcp.Prompt{Name: "my_prompt", Description: "My prompt"},
    func(ctx context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
        return &mcp.GetPromptResult{
            Description: "My prompt result",
            Messages: []*mcp.PromptMessage{
                {Role: "user", Content: &mcp.TextContent{Text: "Hello"}},
            },
        }, nil
    },
)

func WithResourceTemplate

func WithResourceTemplate(template *mcp.ResourceTemplate, handler func(context.Context, *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error)) Option

WithResourceTemplate registers a custom resource template with the server.

The handler signature matches the MCP SDK pattern:

func(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error)

Example:

mcpsrv.WithResourceTemplate(
    &mcp.ResourceTemplate{URITemplate: "custom://{id}", Name: "Custom Resource"},
    func(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
        return &mcp.ReadResourceResult{
            Contents: []*mcp.ResourceContents{
                {URI: req.Params.URI, MIMEType: "application/json", Text: `{"data": "value"}`},
            },
        }, nil
    },
)

func WithTool

func WithTool[In, Out any](tool *mcp.Tool, handler func(context.Context, *mcp.CallToolRequest, In) (*mcp.CallToolResult, Out, error)) Option

WithTool registers a custom tool with the server.

The handler signature must match the MCP SDK pattern:

func(ctx context.Context, req *mcp.CallToolRequest, input T) (*mcp.CallToolResult, Out, error)

Where T is the input type (will be unmarshaled from JSON) and Out is the output type (will be marshaled to JSON).

Example:

type MyInput struct {
    Query string `json:"query"`
}

type MyOutput struct {
    Count int `json:"count"`
}

func myHandler(ctx context.Context, req *mcp.CallToolRequest, input MyInput) (*mcp.CallToolResult, MyOutput, error) {
    return nil, MyOutput{Count: 42}, nil
}

mcpsrv.WithTool(&mcp.Tool{Name: "my_tool", Description: "My tool"}, myHandler)

func WithoutBuiltinPrompts

func WithoutBuiltinPrompts() Option

WithoutBuiltinPrompts disables all builtin powhttp prompts. Use this if you want to register only your own prompts.

func WithoutBuiltinTools

func WithoutBuiltinTools() Option

WithoutBuiltinTools disables all builtin powhttp tools. Use this if you want to register only your own tools.

type Server

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

Server is the powhttp MCP server. It wraps the internal implementation and provides extension points.

func NewServer

func NewServer(c *client.Client, opts ...Option) (*Server, error)

NewServer creates a new MCP server with builtin powhttp tools.

The client parameter is required and provides access to the powhttp API. Use functional options to configure logging, add custom tools, etc.

func (*Server) Close

func (s *Server) Close() error

Close cleans up server resources.

func (*Server) Deps

func (s *Server) Deps() *Deps

Deps returns the dependencies for building custom tools.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the MCP server with stdio transport. It also starts background refresh for all sessions. The server runs until the context is cancelled.