Documentation
¶
Overview ¶
Package mcp implements the Model Context Protocol JSON-RPC 2.0 transport that LLM clients (Claude Desktop, Cursor, Claude.ai web) call to discover and invoke wick connectors as tools.
Surface:
POST /mcp — JSON-RPC requests GET /.well-known/oauth-protected-resource — auth metadata (RFC 9728)
Methods served (server-side, JSON-RPC 2.0):
initialize — protocol handshake, capability negotiation tools/list — enumerate the caller's accessible connector ops tools/call — invoke one op, dispatching to connectors.Service.Execute notifications/* — accepted as no-ops (we don't push from the server yet)
Auth model:
Static bearer (wick_pat_...) — PAT path, decoded via accesstoken.Service
OAuth opaque token — OAuth path, decoded via oauth.Service
Anything else — 401 with WWW-Authenticate pointing at
/.well-known/oauth-protected-resource
The auth middleware resolves a user_id and the user's filter-tag IDs onto the request context; everything below it (tools/list, tools/call) sees only the connectors that user can access.
Index ¶
- type AuthMiddleware
- type Handler
- func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeStdio(ctx context.Context, r io.Reader, w io.Writer)
- func (h *Handler) ServeStdioOS(ctx context.Context)
- func (h *Handler) WithAppURL(get func() string) *Handler
- func (h *Handler) WithBuildInfo(version, commit, buildTime string) *Handler
- func (h *Handler) WithWickRoot(root string) *Handler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthMiddleware ¶
type AuthMiddleware struct {
// contains filtered or unexported fields
}
AuthMiddleware extracts the Authorization: Bearer header, routes the token to the right validator (PAT vs OAuth), loads the user record + filter-tag IDs, and stamps both onto the request context using login.WithUser so downstream code reads identity exactly the way it does for cookie-authed requests.
Unauth requests get a 401 with WWW-Authenticate pointing at the resource-metadata document (RFC 9728), so spec-compliant MCP clients can discover the OAuth server and run the auth dance.
func NewAuthMiddleware ¶
func NewAuthMiddleware(tokens *accesstoken.Service, users userResolver, oauth oauthValidator, resourceMetaURL string) *AuthMiddleware
NewAuthMiddleware wires the bearer middleware. Pass nil oauth to run PAT-only (Phase B); attach later by replacing the field.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler wires the MCP JSON-RPC surface — tools/list, tools/call, initialize. Bearer auth is applied by AuthMiddleware before this handler runs, so every request reaches us with login.GetUser already populated.
Tool surface uses a meta-tool pattern: rather than expose every (connector × operation) pair as its own static MCP tool, the server exposes three stable tools — wick_list, wick_search, wick_execute — and lets the LLM discover the underlying connectors and operations at runtime. Adding/removing connectors in the admin UI never changes what the client cached, so Claude.ai users don't have to click "Refresh tool list" after every admin change.
func NewHandler ¶
func NewHandler(c *connectors.Service) *Handler
func (*Handler) ServeStdio ¶ added in v0.5.1
ServeStdio runs the MCP JSON-RPC server over r/w for local clients (Claude Desktop, Cursor, etc.). Each line from r is one JSON-RPC message; the response is written as one JSON line to w.
No auth middleware — the caller pre-populates ctx with login.WithUser (typically a synthetic local admin) before calling. Logs go to stderr so the protocol stream stays clean.
func (*Handler) ServeStdioOS ¶ added in v0.5.1
ServeStdioOS is the process-level entrypoint: reads os.Stdin, writes os.Stdout. Thin wrapper around ServeStdio for production use.
func (*Handler) WithAppURL ¶ added in v0.6.0
WithAppURL records a getter for the configurable base URL so the wick_encrypt / wick_decrypt redirect tools can mint absolute links. Pass configsSvc.AppURL — wick reads it on every call so admin URL edits take effect without a restart.
func (*Handler) WithBuildInfo ¶ added in v0.5.1
WithBuildInfo sets the version, short commit hash, and build timestamp shown in the MCP initialize response and wick_info tool. Called by RunMCPStdio with app.Build* vars.
func (*Handler) WithWickRoot ¶ added in v0.6.0
WithWickRoot records the project root directory for the wick_info tool. Called by RunMCPStdio after chdir — pass os.Getwd(). Empty string means the server is running in HTTP mode (no local filesystem access).
Source Files