1# MCP servers
 2
 3Use the official Go SDK: `github.com/modelcontextprotocol/go-sdk`. Default to
 4stdio for local agent use; choose Streamable HTTP only when the server needs
 5networked clients or deployment behind an HTTP boundary.
 6
 7MCP servers are still command-line binaries. Read `cli.md` alongside this file
 8for Cobra/Fang setup, command ergonomics, and version-policy guidance.
 9
10## Shape
11
12```text
13cmd/<server>/main.go       # CLI entrypoint
14cmd/<server>/serve.go      # serve command and transport flag
15internal/config/config.go  # env and flag parsing
16internal/server/server.go  # MCP implementation, transports, handlers
17internal/server/tools.go   # typed tool parameter structs, split into tool-per-file if it gets unwieldy
18internal/<client>/...      # API client being wrapped
19```
20
21## Tools
22
23- Use typed parameter structs with JSON and jsonschema tags.
24- Add tool annotations: read-only/destructive/idempotent/open-world hints.
25- Make descriptions operational: what the tool does, when to use it, and any
26  required prerequisite tool.
27- Return structured errors for real failures; use MCP `IsError` for tool-level
28  domain errors the model should see.
29- Clamp or validate bounds at the boundary and document whether clamping is
30  silent or an error.
31
32If the wrapped API has sharp edges, add a `usage`/instructions tool documenting
33them.
34
35## Config
36
37- Required connection info comes from env vars and/or explicit flags.
38- Validate URLs and auth shape before starting the server.
39- Allow separate auth layers when real deployments need them, but document how
40  headers/cookies interact.
41
42## Release
43
44MCP servers are usually plain static binaries. Use `CGO_ENABLED=0` unless a
45dependency requires CGO. Add nFPM only when system installation, services, or
46managed config files are part of the product (seldom).
47
48Prefer the static build shape from `mise.md`: `netgo`, `osusergo`, optional
49project-specific `static_build`, `-d -s -w -buildid= -extldflags=-static`, and
50explicit version injection when the server exposes `--version` or embeds version
51metadata. Do not rely on Fang's CLI fallback alone for MCP implementation
52metadata; use the same project-owned version value anywhere the server reports
53it. Remove those static-only pieces when the wrapped API client or storage layer
54requires CGO.