This guide holds the detailed MCP implementation patterns that are too large for the subsystem routing guide. Read src/mcp/AGENTS.md first; it remains the precedence-bearing guide for MCP work.
The current MCP surface is intentionally polymorphic: lore-context,
lore-memory, lore-pinned, lore-query, lore-fact,
lore-decision, lore-project, lore-task, and
lore-procedure. User-facing behavior belongs in
docs/mcp-tools.md, not in this authoring guide.
The polymorphic lore-* tools above multiplex multiple actions behind one
MCP registration to keep per-session prompt overhead low. Each tool follows
the same shape:
-
Flat MCP-level
inputSchema. A top-levelactionenum field plus every action's parameters as optional fields. Each parameter description names which actions use it (e.g. "(action='create') The entity this fact is about"). This keeps the schema readable as a single property table for agents — discriminated unions at the MCP boundary would surface as a JSON SchemaoneOfwhich agents handle less consistently than flat property lists. -
Module-level discriminated union for runtime validation. A
z.discriminatedUnion("action", [...])schema parses the args inside the handler. Failed parses route throughformatDispatchError()so the agent gets a single-linetool: field: messageerror instead of a stack trace. -
One handler per action. Handlers are local async functions named
handle<Action>taking(services, args) → Promise<ToolResult>. The polymorphic dispatcher routes to the right handler via the discriminated union'sactiondiscriminator.
Skeleton:
async function handleSave(services: LoreServices, args: SaveArgs): Promise<ToolResult> { ... }
async function handleArchive(services: LoreServices, args: ArchiveArgs): Promise<ToolResult> { ... }
const memoryDispatchSchema = z.discriminatedUnion("action", [
z.object({ action: z.literal("save"), title: z.string(), content: z.string(), ... }),
z.object({ action: z.literal("archive"), memoryId: z.string() }),
...
])
server.registerTool("lore-memory", {
title: "Memory operations",
description: "Action-dispatched: save | archive | ...",
inputSchema: {
action: z.enum(["save", "archive", ...]).describe("..."),
title: z.string().optional().describe("(action='save') Required."),
memoryId: z.string().optional().describe("(action='archive') Required."),
...
},
}, async (args) => {
const parsed = memoryDispatchSchema.safeParse(args)
if (!parsed.success) {
return toolError(new Error(formatDispatchError("lore-memory", parsed.error)))
}
switch (parsed.data.action) {
case "save": return handleSave(services, parsed.data)
case "archive": return handleArchive(services, parsed.data)
...
}
})- Write a
handleXfunction following the existing pattern. - Add a new branch to the
discriminatedUnionfor that action's params. - Add the action value to the top-level
actionenum and add any new per-action fields to the flatinputSchema. - Add the dispatch case to the handler's
switch (parsed.data.action). - Update the polymorphic tool's description with a one-line bullet for the new action.
- Add a test in
polymorphic.test.tsexercising the new dispatch path.
Use the polymorphic shape from day one. Single-purpose tools should only be introduced when the surface really is one action. If a behavior can reasonably grow another action, start with a polymorphic family.
Every tool file exports a single registerFooTools(server, services) function
that calls server.registerTool() for each tool. The pattern:
import { z } from "zod"
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import type { LoreServices } from "../server.js"
import { toolError } from "../helpers.js"
export function registerFooTools(server: McpServer, services: LoreServices): void {
server.registerTool(
"lore-verb-noun",
{
title: "Human-readable title",
description: "What this tool does. Include usage guidance for the AI.",
inputSchema: {
paramName: z.string().describe("What this parameter is for"),
optionalParam: z.string().optional().describe("Optional context"),
},
annotations: { readOnlyHint: true }, // if tool only reads data
},
async ({ paramName, optionalParam }) => {
try {
// ... tool logic ...
return { content: [{ type: "text", text: "result" }] }
} catch (err) {
return toolError(err)
}
}
)
}-
Tool names: Always
lore-<verb>orlore-<verb>-<noun>in kebab-case. -
try/catch: Every tool callback must wrap its body in try/catch and return
toolError(err)on failure. MCP protocol requires tools to report errors as content, not throw exceptions. -
inputSchema: Always uses Zod objects. Each field must have a
.describe()call explaining the parameter to the AI. -
Clear sentinels: For optional update fields, omission always means "leave unchanged." For clearable non-string Notion properties,
nullis the canonical clear sentinel; MCP schemas may also accept""as an agent-friendly alias, but must normalize it tonullbefore calling domain services. For string / rich-text properties such assynopsis,alternatives, andconsequences,""is the clear value because the field domain is text. The field.describe()copy must state the keep / clear behavior whenever a parameter can clear existing data. -
annotations: Set
readOnlyHint: truefor tools that only read data. SetdestructiveHint: truefor tools that delete or archive. -
Project resolution: Most tools accept an optional
projectName/projectNamesparameter. Explicit project scope is strict: if the caller passes a name, every named project must resolve or the tool must return an error before reading or writing scoped data. For write tools (memory, knowledge, decisions, tasks) preferresolveProjectIds(services, projectName, projectNames)fromresolve.ts. For read tools that accept an explicitprojectNameparameter, useresolveReadProjectScope(services, projectName). Read tools that always operate on the auto-detected context keep readingservices.context.projectdirectly. The write-path resolver handles the catch-all warning for omitted scope:const resolved = await resolveProjectIds(services, projectName, projectNames) // resolved.ids → project IDs to persist // resolved.warnings → surface in the tool response
When the auto-detected context is a monorepo catch-all (config entry with path
"."), and no explicit project was named,resolveProjectIdsadds a warning naming the candidate sub-projects. The warning surfaces via the existingWarnings: …line in save tool responses — no display-layer changes needed per tool. -
Return format: Always return
{ content: [{ type: "text", text: "..." }] }. Format output as readable markdown when returning multiple items. -
Tags are a profile-owned closed vocabulary. Any tool that writes
tagsmust build its schema fromcreateTagsSchema(services.profile...)intools/tag-schema.ts. Pair it withkeywordsSchemaso callers have a home for free-form tokens (PR numbers, ticket IDs, file paths, class names). Out-of-vocab tags must fail validation. Read filters remain permissive so legacy or out-of-profile rows can still be found. -
Interactive init failures stay MCP-visible. If
initServices()fails during normal MCP startup, register diagnostic stubs for everylore-*dispatcher and connect stdio so the client gets recovery text. Do not callprocess.exit(1)for interactive init failures unless the diagnostic startup path is replaced by another MCP-visible recovery surface.
Prefer adding a new action to an existing polymorphic tool — see "Adding a new action to a polymorphic tool" above. Only introduce a new tool family when the surface genuinely doesn't fit any existing one.
To add a new family:
- Create
src/mcp/tools/<family>.tsfollowing the polymorphic pattern in any existing file. Definehandle<Action>functions, a discriminated union schema, and aregister<Family>Tools(server, services)exporter. - Register it in
server.ts:import { register<Family>Tools } from "./tools/<family>.js" // ... in main(): register<Family>Tools(server, services)
- Do not forget the try/catch +
toolError()wrapper inside each handler. - Document current behavior in
docs/mcp-tools.md, add help recipes insrc/mcp/help.tswhen users need examples, and update the rootREADME.mdonly when its public surface summary needs the new tool. - Add tests to
polymorphic.test.tsexercising at least: registration, each action's dispatch, an unknown-action error, and a per-action missing-required-field error.