Documentation
¶
Overview ¶
Package mcp serves Mesh's retrieval + write-back surface to a coding agent over JSON-RPC 2.0 on stdio. A local agent (Claude Code / Codex) spawns `mesh mcp` and talks to it directly; no port or auth surface. The JSON-RPC envelope matches the hephaestus MCP house pattern.
Index ¶
- func Contract() string
- func ToolSpecs() []map[string]any
- func WithScopeFilter(ctx context.Context, sf *ScopeFilter) context.Context
- type ScopeFilter
- type Server
- func (s *Server) Close() error
- func (s *Server) HandleHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Server) NotePath(id string) (string, error)
- func (s *Server) Reconcile() error
- func (s *Server) ServeStdio() error
- func (s *Server) WaitReady() error
- func (s *Server) Watch(ctx context.Context, debounce, reconcile time.Duration, ...) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Contract ¶
func Contract() string
Contract returns the agent-usage contract text (how to retrieve cheaply), shared by the MCP initialize instructions and the web app's API reference.
func ToolSpecs ¶
ToolSpecs returns the MCP tool definitions (name, description, inputSchema). It is the single source for both the MCP tools/list response and the web app's API reference, so the two never drift.
func WithScopeFilter ¶
func WithScopeFilter(ctx context.Context, sf *ScopeFilter) context.Context
WithScopeFilter returns a context carrying sf, read by the tools via scopeFromCtx.
Types ¶
type ScopeFilter ¶
type ScopeFilter struct {
AllowedRead map[string]bool // scopes the caller may read; nil = unrestricted
WriteScope string // scope new notes are stamped with ("" = caller must pass one)
CanWrite func(scope string) bool // may the caller write a note carrying this scope?
}
ScopeFilter is the per-request access-control context the hub injects so the MCP tools enforce scope: read filtering (search/fetch/neighbors/community/god_nodes) and write gating + stamping (append_note/write_entity). A nil filter (solo run, or a hub with no scopes configured) imposes no restriction, so behavior is unchanged.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server holds the live index, graph, and retriever for one vault.
Concurrency: tool calls run on the ServeStdio goroutine while the optional background watcher (Watch) rebuilds on file changes. mu guards the graph + retriever pointers so a reader always sees a consistent pair; reloadMu makes a rebuild single-flight so the dispatch goroutine (a write-back) and the watcher never reindex at the same time.
func NewServerAt ¶
NewServerAt is like NewServer but keeps the index in an explicit dir instead of <vaultRoot>/.mesh. The hub uses it to serve hosted MCP over its vault while indexing OUTSIDE the git repo (so the index never syncs to clients).
func (*Server) HandleHTTP ¶
func (s *Server) HandleHTTP(w http.ResponseWriter, r *http.Request)
HandleHTTP serves ONE JSON-RPC request over HTTP (MCP Streamable HTTP, the request/response shape; no SSE stream). Same dispatch as stdio, so a remote agent gets identical results. Stateless per call; auth + transport live in the caller (cmd/mesh `mesh mcp --http` or the hub's /mcp route). The body cap mirrors the largest sane tool call.
func (*Server) NotePath ¶
NotePath resolves a note id to its vault-relative path (for the hub's ACL gate).
func (*Server) Reconcile ¶
Reconcile re-reads the vault and rebuilds the in-memory index (authoritative). The hub calls this after a sync lands so hosted MCP serves fresh results.
func (*Server) ServeStdio ¶
ServeStdio reads newline-delimited JSON-RPC requests from stdin and writes responses to stdout until EOF.
func (*Server) WaitReady ¶ added in v0.1.1
WaitReady blocks until ALL background startup work (initial reload plus the writeback backfill and note<->code bridge) has finished and reports the load error, for callers that need fully deterministic startup (tests, hub boot).
func (*Server) Watch ¶
func (s *Server) Watch(ctx context.Context, debounce, reconcile time.Duration, logf func(string, ...any)) error
Watch live-reindexes the vault in the background until ctx is cancelled, so a long-running agent session sees notes a human edits in their editor without a restart. logf must write to stderr: stdout carries the JSON-RPC stream.
Source Files