Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.
TypeScript agent-memoryai-agentsanthropicclaude-codecursorgitknowledge-baseknowledge-graphllmmarkdownmcpmcp-servermodel-context-protocolnote-takingobsidianpkmragsecond-brainself-hostedzettelkasten
import { TOOL_MAP, type Tool } from "./tools";
/**
* The dispatch boundary: validate a tool call's arguments against the tool's OWN inputSchema,
* then run it.
*
* Why this exists — the 2026-08-06 incident. `brain_append` takes `text`; its siblings
* `brain_write` and `brain_edit` take `content`. A caller sent `content` to `brain_append`.
* Nothing validated arguments, so the handler destructured `text` as `undefined`,
* `String(undefined ?? "")` collapsed to `""`, and the note was "appended" with a single blank
* line — five times, each reported as `{ ok: true }`. The vault's own git history is the receipt:
* five commits, `+1 line (0 non-blank)` each.
*
* Handlers coerce with `String(x)`, which turns a missing argument into the string "undefined" —
* that is how `brain_move` without `to` renamed a live note to `undefined.md` and reported success.
* Coercion cannot be made safe one handler at a time; the schema is the contract, so it is
* enforced here, once, before any handler runs.
*
* Strict about unknown keys on purpose. An argument the server silently ignores is an argument the
* caller believed it had sent, and this failure mode is exactly that bug with a different name.
* The error names the parameters the tool does accept, so a model can retry correctly first time.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
type Args = Record<string, any>;
interface PropSchema {
type?: string;
}
interface ToolSchema {
properties?: Record<string, PropSchema>;
required?: string[];
}
/** MCP reserves `_`-prefixed keys for protocol metadata; they are not tool arguments. */
const isMeta = (k: string) => k.startsWith("_");
function typeMatches(expected: string | undefined, value: unknown): boolean {
switch (expected) {
case "string":
return typeof value === "string";
case "number":
return typeof value === "number" && Number.isFinite(value);
case "boolean":
return typeof value === "boolean";
case "object":
return typeof value === "object" && value !== null && !Array.isArray(value);
case "array":
return Array.isArray(value);
default:
return true; // no declared type — nothing to check
}
}
function describeType(value: unknown): string {
if (value === null) return "null";
if (Array.isArray(value)) return "array";
return typeof value;
}
/**
* Check `args` against `tool.inputSchema`. Returns an error message for the caller, or null when
* the call is well-formed. The message is written for a model that has to fix its own call.
*/
export function validateArgs(tool: Tool, args: Args): string | null {
const schema = tool.inputSchema as ToolSchema;
const props = schema.properties ?? {};
const accepted = Object.keys(props);
const acceptedList = accepted.length > 0 ? accepted.join(", ") : "(none)";
if (typeof args !== "object" || args === null || Array.isArray(args)) {
return `${tool.name}: \`arguments\` must be an object with ${acceptedList}.`;
}
// Unknown keys first: when a caller sends `content` to a tool that wants `text`, naming the
// mistake beats reporting the resulting "missing required" further down.
const unknown = Object.keys(args).filter((k) => !isMeta(k) && !(k in props));
if (unknown.length > 0) {
return (
`${tool.name} does not accept ${unknown.map((k) => `\`${k}\``).join(", ")}. ` +
`Its parameters are: ${acceptedList}. Nothing was written — re-send the call with the ` +
`payload under the right parameter name.`
);
}
for (const key of schema.required ?? []) {
const v = args[key];
if (v === undefined || v === null) {
return `${tool.name} requires \`${key}\`, which was missing. Its parameters are: ${acceptedList}. Nothing was written.`;
}
}
for (const [key, value] of Object.entries(args)) {
if (isMeta(key) || value === undefined || value === null) continue;
const expected = props[key]?.type;
if (!typeMatches(expected, value)) {
return `${tool.name}: \`${key}\` must be a ${expected}, got ${describeType(value)}. Nothing was written.`;
}
}
return null;
}
/**
* Look up a tool, validate its arguments, and run it. Throws on an unknown tool or a call that
* does not satisfy the tool's schema — the MCP route turns a throw into an `isError` result, so a
* rejected call is visible to the caller instead of being reported as a successful write.
*
* Scope enforcement stays in the route: it depends on the authenticated caller, not the arguments.
*/
export async function callTool(name: string, args: Args): Promise<unknown> {
const tool = TOOL_MAP.get(name);
if (!tool) throw new Error(`unknown tool: ${name}`);
const problem = validateArgs(tool, args ?? {});
if (problem) throw new Error(problem);
return await tool.handler(args ?? {});
}