stackkitmcp

package
v0.57.6 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MCPTokenEnv     = "STACKKIT_MCP_TOKEN"
	MCPTokenFileEnv = "STACKKIT_MCP_TOKEN_FILE"

	// AgentCredentialEnv and AgentCredentialFileEnv carry the per-agent
	// credential of a directly attached (stdio) agent.
	AgentCredentialEnv     = "STACKKIT_MCP_AGENT_CREDENTIAL"
	AgentCredentialFileEnv = "STACKKIT_MCP_AGENT_CREDENTIAL_FILE"
)

Dedicated MCP credential sources. The token file lets an installer mint the credential without placing it on a command line or in a process listing.

View Source 
const AgentEnvelopeHeader = "Stackkit-Agent-Envelope"

AgentEnvelopeHeader is where the Access Gate hands the endpoint the agent envelope it verified (homelab identity target §7). The router replaces any client copy with the gate's answer, so the endpoint only ever sees an envelope the gate admitted on this request.

View Source 
const DefaultLocalServerURL = "http://localhost:8082"

DefaultLocalServerURL is the loopback-only default for a local stackkit-server when STACKKITS_SERVER_URL and --server-url are unset. Standard Mode binds MCP and the API to the developer machine; it is not a hosted production origin.

View Source 
const ReadOnlyAgentCapability = "techstack.inventory.read"

ReadOnlyAgentCapability is the lease capability whose ceiling is the read-only tools.

Variables

This section is empty.

Functions

func AgentFromContext added in v0.53.10 

func AgentFromContext(ctx context.Context) (mcpagents.Agent, bool)

AgentFromContext returns the per-agent credential that authenticated the request. A request admitted by the shared legacy token has none.

func EnvBoolValue 

func EnvBoolValue(value string) bool

EnvBoolValue parses common truthy environment values.

func FirstNonEmpty 

func FirstNonEmpty(values ...string) string

FirstNonEmpty returns the first non-empty value after trimming whitespace.

func IsLoopbackListenAddr 

func IsLoopbackListenAddr(addr string) bool

IsLoopbackListenAddr reports whether an HTTP listen address is loopback-only.

func JSONResult 

func JSONResult(value any) *mcp.CallToolResult

func NewHTTPServer 

func NewHTTPServer(addr string, handler http.Handler) *http.Server

NewHTTPServer creates a hardened Streamable HTTP server. WriteTimeout stays disabled because MCP Streamable HTTP may keep responses open.

func ParseModes 

func ParseModes(raw string) map[string]bool

ParseModes parses a comma-separated MCP mode list.

func RequireMCPCredential added in v0.53.10 

func RequireMCPCredential(token string, agents *mcpagents.Store, next http.Handler) http.Handler

RequireMCPCredential admits requests that present the shared MCP token or an active per-agent credential from the store, and it fails closed: with neither configured every request is denied with configuration guidance. An agent credential is re-checked on every request, so revoking it denies the next call.

func RequireMCPToken 

func RequireMCPToken(token string, next http.Handler) http.Handler

RequireMCPToken admits only requests that present the configured MCP token as a bearer credential or X-StackKit-MCP-Token value.

func ResolveAgentCredential added in v0.53.13 

func ResolveAgentCredential() (string, error)

ResolveAgentCredential returns the per-agent credential of a directly attached agent from STACKKIT_MCP_AGENT_CREDENTIAL or the file named by STACKKIT_MCP_AGENT_CREDENTIAL_FILE. An empty result means none is configured; an unreadable or empty file is an error.

func ResolveMCPToken added in v0.45.0 

func ResolveMCPToken(flagValue string) (string, error)

ResolveMCPToken returns the dedicated MCP token from the explicit flag value, STACKKIT_MCP_TOKEN, or the file named by STACKKIT_MCP_TOKEN_FILE, in that order. An empty result means no token is configured. A configured token file that cannot be read or is empty is an error, never a silent fallback.

func ShellQuote 

func ShellQuote(value string) string

func SiblingStackkitBinary 

func SiblingStackkitBinary() (string, error)

SiblingStackkitBinary returns the packaged CLI beside stackkit-server or stackkit-mcp, through the shared exact-build local process binding.

func StringMapValue 

func StringMapValue(values map[string]any, key string) string

func TextResult 

func TextResult(text string) *mcp.CallToolResult

Types

type AgentEnvelopePrincipal 

type AgentEnvelopePrincipal struct {
	Account       string
	AgentInstance string
	LeaseID       string
	Capability    string
	// LinkRef names the pinned agent link (generation and install time).
	LinkRef string
}

AgentEnvelopePrincipal is a verified agent call: the Homelab account it acts for, the agent instance, the lease and the capability.

func EnvelopeAgentFromContext 

func EnvelopeAgentFromContext(ctx context.Context) (AgentEnvelopePrincipal, bool)

EnvelopeAgentFromContext returns the envelope agent that authenticated the request.

type AgentEnvelopeVerifier 

type AgentEnvelopeVerifier interface {
	ConsumeAgentEnvelope(envelope, method, path string, body []byte) (AgentEnvelopePrincipal, error)
}

AgentEnvelopeVerifier verifies, at the endpoint, an envelope the gate admitted: the signature and claims again, the method and path as received, the hash of the exact body, and the gate's single admission, which it spends.

type App 

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

App owns the StackKits MCP registration shared by stackkit-mcp and stackkit-server.

func New 

func New(opts Options) *App

New creates a configured StackKits MCP app.

func (*App) OpenMCP 

func (a *App) OpenMCP() map[string]any

OpenMCP returns agent-native discovery metadata for the local MCP surface.

func (*App) OpenMCPJSON 

func (a *App) OpenMCPJSON() []byte

OpenMCPJSON returns pretty JSON discovery metadata.

func (*App) OpenMCPJSONFor added in v0.53.10 

func (a *App) OpenMCPJSONFor(r *http.Request) []byte

OpenMCPJSONFor serves the full discovery document only to a request that presents the configured MCP token; every other request gets OpenMCPPublic.

func (*App) OpenMCPPublic added in v0.53.10 

func (a *App) OpenMCPPublic() map[string]any

OpenMCPPublic is what an unauthenticated GET /openmcp.json may learn: the connector identity, transport and credential model, never the tool, resource or prompt inventory of an installation.

func (*App) ProtectedStreamableHTTPHandler 

func (a *App) ProtectedStreamableHTTPHandler() http.Handler

ProtectedStreamableHTTPHandler requires the dedicated MCP token on every request. Without a configured token it denies every request; it never falls back to an open endpoint or to another credential.

A request the Access Gate admitted with a Gateway-signed agent envelope is admitted only through the envelope verifier (AgentEnvelopes), never through another credential.

func (*App) Server 

func (a *App) Server() *mcp.Server

Server builds a Model Context Protocol server with the configured modes.

func (*App) StreamableHTTPHandler 

func (a *App) StreamableHTTPHandler() http.Handler

StreamableHTTPHandler returns the stateless MCP 2026-07-28 Streamable HTTP handler. Each POST is served from that request alone: the SDK issues no Mcp-Session-Id, ignores one a client sends, and answers GET and DELETE with 405. Clients on older protocol versions are still served, one request at a time, with SDK-synthesized initialization defaults.

type Options 

type Options struct {
	Modes     map[string]bool
	ServerURL string
	// OwnerStepUpOrigin is the server's local Owner approval origin. When
	// set, the State Console links to its enrollment start page (the LAN
	// enrollment bootstrap a device scans) and an agent's write denial links
	// to its agent-approval page; the Owner's answer never passes through a
	// tool result.
	OwnerStepUpOrigin string
	APIKey            string
	Transport         string
	MCPToken          string
	AllowWrite        bool
	// Agents holds per-agent MCP credentials. When set, a request that
	// authenticates with an agent credential may call mutating tools only
	// after the owner approves that exact call; AllowWrite no longer applies
	// to it and stays the switch for the shared token and an anonymous stdio
	// attachment.
	Agents *mcpagents.Store
	// AgentToken identifies a directly attached (stdio) agent by its per-agent
	// credential. The credential is re-checked against Agents on every
	// mutating call, so every write of that agent needs per-call owner
	// approval and a revoke takes effect on its next call.
	AgentToken string
	// AgentEnvelopes verifies the agent envelopes the Access Gate admitted
	// (stackkit-server with the identity workspace). Without it a request
	// that carries one is refused.
	AgentEnvelopes AgentEnvelopeVerifier
	BaseDir        string
	// PinBaseDir confines every tool to BaseDir. A remote caller then cannot
	// point base_dir at other paths of the host or container.
	PinBaseDir bool
	// JSONResponse answers Streamable HTTP calls with application/json instead
	// of an event stream; stackkit-server sets it because its tools never stream.
	JSONResponse bool
	Binary       string
	Version      string
	GitCommit    string
}

Options configures the StackKits MCP server surface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.