Documentation
¶
Overview ¶
Package mcp wraps the CKV read-only surface as an MCP server.
CKV exposes only **read-only** tools — those that *infer* meaning from the indexed code. The companion **read-write** memory MCP (working memory: remember_fact, record_decision, log_interaction) is a separate concern and will live in pkg/memory (planned). Splitting the two is deliberate so callers (coding agent, CKS) can mount the write surface behind tighter policy than the read surface.
Tools exposed today (read-only):
- cks.context.semantic_search — query.Engine.Search wrapper
- cks.ops.get_freshness — freshness.Check wrapper
- cks.ops.health — embedder + index identity probe
- cks.ops.warmup — pre-load embedder, report cold-start ms
Transport is stdio by default (Claude Code default). This package is importable by **CKS** — CKS multiplexes CKV's tools alongside CKG's in its own combined `cks-mcp` binary.
Index ¶
Constants ¶
const ( ServerName = "ckv" ServerVersion = "0.1.0" )
ServerName / ServerVersion are surfaced to MCP clients on init.
const ResponseSchemaVersion = "1.1"
ResponseSchemaVersion is the version tag every tool response carries in the top-level "schema_version" field. Bump policy:
- patch (1.0 → 1.0.1) is reserved; we don't ship patch bumps.
- minor (1 → 1.1): purely additive — new fields, new tools, new nested objects. Old parsers keep working.
- major (1 → 2): breaking change — field removal, type change, semantic change. Consumers must update parsing.
Read-side contract: callers should compare the major version and degrade gracefully on mismatch (e.g. cks could log a warning and fall back to last-known-good fields). 1.1 (2026-05-29): added Hit.category + Hit.guidance from policy loader.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Server)
Option customizes NewServer (functional options).
func WithFilter ¶
WithFilter attaches a Sensitive Filter. All MCP tool responses pass through this filter before reaching the caller. Nil uses PassThrough.
func WithFootprint ¶
WithFootprint attaches a footprint logger; each MCP tool dispatch is then wrapped in a span (event = "mcp.<tool>"). Nil-safe.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server owns the long-lived query engine + the underlying MCP server object. One Server per --out directory.
func NewServer ¶
NewServer constructs the MCP server bound to a pre-opened query.Engine. The caller owns the engine and is responsible for Close-ing it on shutdown.
server.WithRecovery installs a panic-to-error middleware on every tool handler. Without it, a panic in handleSemanticSearch (nil engine, ranking math, snippet decode) would unwind past the MCP server, terminate ckv mcp, close the stdio writer, and surface on the cks side as "transport closed." With recovery the process stays alive and the panicking call returns a normal MCP tool error so cks can continue using the same subprocess.
func (*Server) ServeHTTP ¶
ServeHTTP runs the streamable HTTP transport on the given address (e.g. ":8080"). Blocks until the listener is closed. Use when multiple clients need to share one MCP server instance — stdio is 1:1, HTTP supports concurrent sessions over the streamable protocol (POST for requests, GET for SSE notifications).
func (*Server) ServeStdio ¶
ServeStdio runs the JSON-RPC stdio loop. Blocks until EOF on stdin or context cancellation. This is what `claude mcp add cks` invokes.
func (*Server) Underlying ¶
Underlying returns the *server.MCPServer for cross-package multiplex.
Used by CKS (separate repo) to register CKG tools alongside CKV's inside one MCP endpoint. CKV itself never multiplexes — callers that only need CKV use cmd/ckv/mcp, which calls ServeStdio directly.
Source Files