mcpkit

mcpkit

Agent-facing MCP ergonomics built on modelcontextprotocol/go-sdk.

It adds structured agent tool results, optional proxy-tool plumbing, and list/preview helpers.

Single runtime dependency: modelcontextprotocol/go-sdk

Install

go get github.com/brandonkramer/mcpkit

Development

Install git hooks once in the repo:

lefthook install

Hooks run golangci-lint on commit (staged .go files) and ./scripts/check.sh on push (tests, examples build, lint). CI runs the same checks on pull requests.

make check    # full local CI script
make test
make lint

Minimal: envelope + adapter

Register tools directly with go-sdk

sdkmcp.AddTool(server, &sdkmcp.Tool{
    Name: "ping", Description: "Health check",
}, func(ctx context.Context, _ *sdkmcp.CallToolRequest, _ struct{}) (*sdkmcp.CallToolResult, any, error) {
    env := envelope.Success("ping").
        Summary("pong").
        Data(map[string]string{"status": "ok"}).
        Build()
    return adapter.FromEnvelope(&env)
})

Shorthand helpers (same envelope shape, less boilerplate):

return adapter.OK("notes.list", "2 note(s)", data, "notes.create title=\"...\"")
return adapter.ErrorCode("not_found", err)

On error without a code:

return adapter.Error(err)

Text mode for clients that only read content text (structured envelope still in structuredContent):

adapter.OKWithOptions("notes.get", "note 01", data, adapter.Options{Text: adapter.TextSummary})
// TextFull (default): full envelope JSON in text
// TextSummary: summary line only
// TextNone: no text content

No summarize.Registry, no tool.Bridge, no server helper required.

Proxy: backend + registry

When tools proxy to a service and share summarization logic:

reg := summarize.Passthrough() // or your own Registry; Passthrough() for day-one proxy wiring

bridge := &tool.Bridge{
    Backend:   tool.FuncBackend(myBackend.Call),
    Responder: summarize.NewResponder(reg),
}

tool.AddProxy(server, bridge, tool.ProxySpec[CreateArgs, Item]{
    Name: "items.create", Description: "Create an item",
    Prepare: func(_ *tool.Bridge, args CreateArgs) (CreateArgs, summarize.Meta, error) {
        return tool.PrepareWorkDir(defaultWorkDir, args, setWorkDir, getWorkDir)
    },
})

WorkDir is app-specific — use tool.ResolveWorkDir / tool.PrepareWorkDir in your prepare hooks, not on Bridge.

List tool summarization:

summary, next := present.SummarizeToolList(data, meta, summarize.ToolListSummary[Item]{
    CountLabel: "item(s)",
    Next:       []string{"items.create title=\"...\""},
    PageHint:   "narrow filter=... or use CLI for full list",
    NextFor: func(item Item) []string {
        return []string{envelope.Hint("items.get", envelope.HintParam("id", item.ID))}
    },
})

summarize.Meta

Meta passes context from prepare / present hooks to summarizers.

Only use the fields your app needs. A replay/poll proxy might use Limit, SinceSeq, and RunID; a notes MCP might only set Limit or use Extra alone.

Transport

Build once with server.New, then serve over any go-sdk transport:

server, _, err := mcpserver.New(mcpserver.Config{
    Name: "notes", Version: "1.0.0",
    Register: func(s *sdkmcp.Server, _ string) { registerNotesTools(s, db) },
})

// Stdio
_ = server.Run(ctx, &sdkmcp.StdioTransport{})

// HTTP (go-sdk) — see modelcontextprotocol/go-sdk StreamableHTTPHandler
handler := sdkmcp.NewStreamableHTTPHandler(func(_ *http.Request) *sdkmcp.Server {
    return server
}, nil)
_ = http.ListenAndServe(":8080", handler)

Packages