kami
95ae900a58
docs/plans/06-mcp-support.md asks for the host direction — Maven connects OUT
to MCP servers and consumes what they offer. This is the client half: the
protocol, the transports, the connection manager, the config block. Nothing is
wired into a turn yet, and nothing here exposes Maven's own capabilities to an
outside caller.
internal/mcp:
- hand-rolled JSON-RPC 2.0 (the wire format is four fields, and the repo
vendors its deps, so a library would cost more than it saves);
- two transports: a stdio subprocess on this box, and streamable HTTP, which
accepts a plain JSON reply or an SSE frame because servers disagree about
which they send;
- Client: initialize handshake, tools/list, tools/call, resources/list,
resources/read. Text content only — everything downstream is a sentence;
- Manager: lazy dial, per-server failure that never blocks boot or the other
servers, backoff reconnect, Status for a web surface, graceful Close;
- the allowlist encoding: a discovered tool becomes the store row
"vikunja_list_tasks" with cmd ["mcp","vikunja","list_tasks"], scope
"mcp:vikunja". No new column, no migration, and ProposeTool, EnableTool,
the act matcher and the confirm turn all keep working untouched.
Constraints held, in code rather than in prose:
- OFF unless configured, and a server is dark until "enabled": true.
- A url server goes through internal/webfetch, so the SSRF guard, the size
cap, the redirect cap and the per-host rate limit apply. Reaching loopback
needs allow_private on THAT server, and each server gets its own fetcher so
one loopback exemption cannot become a hole for a public endpoint.
- readOnlyHint decides destructive: no hint means "assume it mutates", which
will route the call through the existing confirm turn. Guessing wrong in
that direction only costs a question.
- The catalogue stays small on purpose — allow_tools, and max_tools=12 per
server. The resident model is a 1.7B with a 4096-token context; a tool name
it half-remembers is a wrong act.
- Only the tool name and the router's arguments are sent. There is no API
here through which a note, a fact or the persona block could travel.
webfetch grows Post (JSON-RPC cannot be a GET) and surfaces response headers
for Mcp-Session-Id. It shares Get's guards exactly: a body buys a caller
nothing, a POST to the LAN is refused for the same reason a GET is.
Verified against the real Vikunja MCP server on homesrv
(http://localhost:9100/mcp): handshake, three discovered tools with update_task
correctly NOT read-only, a live list_projects call, a tool excluded by
allow_tools refused, and the same server refused outright once allow_private
was dropped. Tests cover both transports (the stdio one against a real
subprocess), SSE and JSON framing, session echo, reconnect, and the config
validation.
62 lines
2.2 KiB
Go
62 lines
2.2 KiB
Go
package mcp
|
|
|
|
import (
|
|
"regexp"
|
|
"strings"
|
|
)
|
|
|
|
// CmdPrefix is the reserved first argv element that marks an allowlist row as
|
|
// an MCP call rather than a process. An MCP tool row looks like
|
|
//
|
|
// name: "vikunja_list_tasks" cmd: ["mcp", "vikunja", "list_tasks"]
|
|
//
|
|
// which is why there is no new column and no migration: the store, the /tools
|
|
// page, ProposeTool, EnableTool, DisableTool, the act matcher and the confirm
|
|
// turn all keep working unchanged. The executor is the only place that has to
|
|
// know the difference, and it is one branch on Cmd[0].
|
|
//
|
|
// The rest of the allowlist discipline is inherited whole: a row that is not
|
|
// status='enabled' does not run, and a row marked destructive does not run on
|
|
// first hearing. Nothing here can enable itself — discovery only proposes.
|
|
const CmdPrefix = "mcp"
|
|
|
|
// Cmd builds the argv encoding for a discovered tool.
|
|
func Cmd(server, tool string) []string { return []string{CmdPrefix, server, tool} }
|
|
|
|
// ParseCmd recognises an MCP allowlist row. ok=false for an ordinary process
|
|
// tool, which is what almost every row is.
|
|
func ParseCmd(cmd []string) (server, tool string, ok bool) {
|
|
if len(cmd) != 3 || cmd[0] != CmdPrefix {
|
|
return "", "", false
|
|
}
|
|
if cmd[1] == "" || cmd[2] == "" {
|
|
return "", "", false
|
|
}
|
|
return cmd[1], cmd[2], true
|
|
}
|
|
|
|
var notName = regexp.MustCompile(`[^a-z0-9_]+`)
|
|
|
|
// LocalName is the allowlist name for a discovered tool: the server handle, an
|
|
// underscore, the remote name, lowercased and stripped of anything that is not
|
|
// a word character. Namespacing by server is what keeps two servers that both
|
|
// offer "search" from colliding, and what makes the provenance of a row on the
|
|
// /tools page obvious without opening the diff.
|
|
func LocalName(server, tool string) string {
|
|
clean := func(s string) string {
|
|
return strings.Trim(notName.ReplaceAllString(strings.ToLower(strings.TrimSpace(s)), "_"), "_")
|
|
}
|
|
s, t := clean(server), clean(tool)
|
|
switch {
|
|
case s == "":
|
|
return t
|
|
case t == "":
|
|
return s
|
|
}
|
|
return s + "_" + t
|
|
}
|
|
|
|
// Scope is the store scope for a server's rows, so the /tools page can group
|
|
// them and a human can tell at a glance where a capability came from.
|
|
func Scope(server string) string { return "mcp:" + server }
|