MCP Server

notes mcp starts a Model Context Protocol server over stdio. It speaks JSON-RPC on stdout and sends logging to stderr so the protocol stream stays clean.

{
  "mcp": {
    "notes": {
      "type": "local",
      "command": ["notes", "mcp"],
      "enabled": true
    }
  }
}

The server exposes note tools for reading, listing, writing, and deleting vault files. Reads include a SHA-256 revision that writes can use to reject stale content. See the generated MCP tool reference for tool parameters.

Successful writes and deletes send a desktop notification when notify-send is available. Notifications are best-effort, so the operation still succeeds when notify-send is missing or cannot reach a notification service.

Tools

Agent harnesses prefix tool names with the server key. With the server configured as notes, note_read appears as notes_note_read.

Results and Code Mode

Each tool declares an outputSchema and returns its result as structuredContent, alongside the same text content as before. Clients that type results from the schema, such as OpenCode’s Code Mode, can chain calls without parsing text:

const { notes = [] } = await tools["notes"].note_list({ tag: "handoff" });
const note = await tools["notes"].note_read({ path: notes[0].filePath });

await tools["notes"].note_write({
  path: note.path,
  content: `${note.content}\n- Picked up\n`,
  expectedHash: note.hash,
});

note_list returns { notes } for the current project, or { sections } grouped by project when all is set. note_write and note_delete return the path, the Git commit and push outcome, and the rendered output; note_write also returns the new hash.

Resources

• notes://context - repo-note context for the current repository.
• notes://command/{name} - help text for a notes command.

Resources are a progressive enhancement; tools are the primary interface.