Skip to content

Build your personal knowledge base with Trilium Notes

2.8 KB
Raw Blame
/**
 * MCP (Model Context Protocol) server for Trilium Notes.
 *
 * Exposes existing LLM tools via the MCP protocol so external AI agents
 * (e.g. Claude Desktop) can interact with Trilium.
 */

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { isToolErrorResult } from "@triliumnext/commons";
import { app_info as appInfo } from "@triliumnext/core";
import { cls } from "@triliumnext/core";

import { allToolRegistries, resolveToolRegistries } from "@triliumnext/core/src/services/llm/tools/index.js";
import type { ToolDefinition } from "@triliumnext/core/src/services/llm/tools/tool_registry.js";

import sql from "../sql.js";

/**
 * Register a tool definition on the MCP server.
 *
 * Write operations are wrapped in CLS + transaction context so that
 * Becca entity tracking works correctly. With `toolHints`, the annotations tell
 * the client which tools only read and which overwrite or remove, so it can
 * decide what to ask the user about.
 */
function registerTool(server: McpServer, name: string, def: ToolDefinition, toolHints: boolean) {
    const annotations = def.mutates
        ? { readOnlyHint: false, destructiveHint: def.additive !== true, openWorldHint: false }
        : { readOnlyHint: true, openWorldHint: false };
    server.registerTool(name, {
        description: def.description,
        inputSchema: def.inputSchema,
        annotations: toolHints ? annotations : undefined
    }, (args: any): CallToolResult => {
        const result = cls.init(() => {
            cls.set("componentId", "mcp");

            return def.mutates
                ? sql.transactional(() => def.execute(args))
                : def.execute(args);
        });

        const content: CallToolResult["content"] = [{ type: "text", text: JSON.stringify(result) }];
        // Without `isError`, an agent (and the chat behind it) takes a failure for a success.
        return isToolErrorResult(result) ? { content, isError: true } : { content };
    });
}

/**
 * Build Trilium's MCP server. An in-chat agent's server sets `toolHints: false`: the chat's
 * approvals decide its calls, and Codex runs a tool marked read-only without asking.
 */
export async function createMcpServer({ toolHints = true }: { toolHints?: boolean } = {}): Promise<McpServer> {
    // Host-registered registries (the User Guide tools) load lazily; the array
    // is complete only after this resolves.
    await resolveToolRegistries();

    const server = new McpServer({
        name: "trilium-notes",
        version: appInfo.appVersion
    });

    for (const registry of allToolRegistries) {
        for (const [name, def] of registry) {
            registerTool(server, name, def, toolHints);
        }
    }

    return server;
}