import { z } from "zod"; import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js"; import documentCreator from "@server/commands/documentCreator"; import documentMover from "@server/commands/documentMover"; import documentUpdater from "@server/commands/documentUpdater"; import { Op } from "sequelize"; import { Collection, Document } from "@server/models"; import { sequelize } from "@server/storage/database"; import SearchHelper from "@server/models/helpers/SearchHelper"; import { authorize } from "@server/policies"; import { presentDocument } from "@server/presenters"; import AuthenticationHelper from "@shared/helpers/AuthenticationHelper"; import { UrlHelper } from "@shared/utils/UrlHelper"; import { error, success, buildAPIContext, buildSiblingIndexMap, getActorFromContext, pathToUrl, withTracing, } from "./util"; import { TextEditMode } from "@shared/types"; /** * Registers document-related MCP tools on the given server, filtered by * the OAuth scopes granted to the current token. * * @param server - the MCP server instance to register on. * @param scopes - the OAuth scopes granted to the access token. */ export function documentTools(server: McpServer, scopes: string[]) { if (AuthenticationHelper.canAccess("documents.list", scopes)) { server.registerTool( "list_documents", { title: "Search documents", description: "Searches documents the user has access to. Performs full-text search across document content when a query is provided, or lists recent documents when no query is given. Optionally filter by collection.", annotations: { idempotentHint: true, readOnlyHint: true, }, inputSchema: { query: z .string() .optional() .describe( "A search query to find documents by content or title. When omitted, returns recent documents." ), collectionId: z .string() .optional() .describe("An optional collection ID to filter documents by."), offset: z.coerce .number() .int() .min(0) .optional() .describe("The pagination offset. Defaults to 0."), limit: z.coerce .number() .int() .min(1) .max(100) .optional() .describe( "The maximum number of results to return. Defaults to 25, max 100." ), }, }, withTracing( "list_documents", async ({ query, collectionId, offset, limit }, extra) => { try { const user = getActorFromContext(extra); const effectiveOffset = offset ?? 0; const effectiveLimit = limit ?? 25; let indexMap: Map | undefined; if (collectionId) { const collection = await Collection.findByPk(collectionId, { userId: user.id, includeDocumentStructure: true, }); authorize(user, "readDocument", collection); if (collection?.documentStructure) { indexMap = buildSiblingIndexMap(collection.documentStructure); } } if (query) { // If the query looks like a document ID or urlId, try direct // lookup first so exact matches appear at the top of results. let exactMatch: Document | null = null; if (UrlHelper.SLUG_URL_REGEX.test(query)) { exactMatch = await Document.findByPk(query, { userId: user.id, }); if ( exactMatch && collectionId && exactMatch.collectionId !== collectionId ) { exactMatch = null; } } const { results } = await SearchHelper.searchForUser(user, { query, collectionId, offset: effectiveOffset, limit: effectiveLimit, }); const presented = await Promise.all( results .filter((result) => result.document.id !== exactMatch?.id) .map(async (result) => { const doc = pathToUrl( user.team, await presentDocument(undefined, result.document, { includeData: false, includeText: false, }) ); const siblingIndex = indexMap?.get(result.document.id); return { ...doc, context: result.context, ...(siblingIndex !== undefined && { index: siblingIndex, }), }; }) ); if (exactMatch) { const doc = pathToUrl( user.team, await presentDocument(undefined, exactMatch, { includeData: false, includeText: false, }) ); const siblingIndex = indexMap?.get(exactMatch.id); presented.unshift({ ...doc, context: undefined, ...(siblingIndex !== undefined && { index: siblingIndex }), }); } return success(presented); } const collectionIds = collectionId ? [collectionId] : await user.collectionIds(); const documents = await Document.findAll({ where: { teamId: user.teamId, collectionId: collectionIds, archivedAt: { [Op.eq]: null }, deletedAt: { [Op.eq]: null }, }, order: [["updatedAt", "DESC"]], offset: effectiveOffset, limit: effectiveLimit, }); const presented = await Promise.all( documents.map(async (document) => { const result = pathToUrl( user.team, await presentDocument(undefined, document, { includeData: false, includeText: false, }) ); const siblingIndex = indexMap?.get(document.id); if (siblingIndex !== undefined) { result.index = siblingIndex; } return result; }) ); return success(presented); } catch (message) { return error(message); } } ) ); } if (AuthenticationHelper.canAccess("documents.create", scopes)) { server.registerTool( "create_document", { title: "Create document", description: "Creates a new document. Requires a collectionId to place the document in a collection, or parentDocumentId to nest it under an existing document.", annotations: { idempotentHint: false, readOnlyHint: false, }, inputSchema: { title: z.string().describe("The title of the document."), text: z .string() .optional() .describe("The markdown content of the document."), collectionId: z .string() .optional() .describe("The collection to place the document in."), parentDocumentId: z .string() .optional() .describe("The parent document ID to nest this document under."), icon: z .string() .optional() .describe("An icon for the document, e.g. an emoji."), color: z .string() .optional() .describe("The hex color for the document icon, e.g. #FF0000."), publish: z .boolean() .optional() .describe( "Whether to publish the document. Defaults to true. Set to false to create as a draft." ), }, }, withTracing("create_document", async (input, context) => { try { const { collectionId, parentDocumentId } = input; const ctx = buildAPIContext(context); const { user } = ctx.state.auth; let collection; let parentDocument; if (parentDocumentId) { parentDocument = await Document.findByPk(parentDocumentId, { userId: user.id, }); if (parentDocument?.collectionId) { collection = await Collection.findByPk( parentDocument.collectionId, { userId: user.id } ); } authorize(user, "createChildDocument", parentDocument, { collection, }); } else if (collectionId) { collection = await Collection.findByPk(collectionId, { userId: user.id, }); authorize(user, "createDocument", collection); } const document = await documentCreator(ctx, { title: input.title, text: input.text, icon: input.icon, color: input.color, parentDocumentId: parentDocumentId, publish: input.publish !== false, collectionId: collection?.id, }); const { text, ...attributes } = await presentDocument( undefined, document, { includeData: false, includeText: true, includeUpdatedAt: true, } ); return { content: [ { type: "text" as const, text: JSON.stringify(pathToUrl(user.team, attributes)), }, { type: "text" as const, text: String(text ?? ""), }, ], } satisfies CallToolResult; } catch (message) { return error(message); } }) ); } if (AuthenticationHelper.canAccess("documents.move", scopes)) { server.registerTool( "move_document", { title: "Move document", description: "Moves a document to a different location or reorders it within its current parent. Provide a collectionId to move to the root of a collection, a parentDocumentId to nest under another document, and/or an index to control position among siblings.", annotations: { idempotentHint: false, readOnlyHint: false, }, inputSchema: { id: z .string() .describe("The unique identifier of the document to move."), collectionId: z .string() .optional() .describe( "The destination collection ID. Required if parentDocumentId is not provided." ), parentDocumentId: z .string() .optional() .describe( "The ID of the document to nest this document under. The document will be moved to the parent's collection." ), index: z .number() .int() .min(0) .optional() .describe( "The zero-based position to insert the document among its siblings. Use this to reorder documents within the same collection and parent. Omit to place at the end." ), }, }, withTracing("move_document", async (input, context) => { try { const ctx = buildAPIContext(context); const { user } = ctx.state.auth; return await sequelize.transaction(async (transaction) => { ctx.state.transaction = transaction; ctx.context.transaction = transaction; const document = await Document.findByPk(input.id, { userId: user.id, rejectOnEmpty: true, transaction, }); authorize(user, "move", document); let collectionId = input.collectionId; if (input.parentDocumentId) { if (input.parentDocumentId === input.id) { return error("Cannot nest a document inside itself"); } const parent = await Document.findByPk(input.parentDocumentId, { userId: user.id, rejectOnEmpty: true, transaction, }); authorize(user, "update", parent); collectionId = parent.collectionId!; if (!parent.publishedAt) { return error("Cannot move document inside a draft"); } } else if (!collectionId) { return error( "Either collectionId or parentDocumentId is required" ); } else { const collection = await Collection.findByPk(collectionId, { userId: user.id, rejectOnEmpty: true, transaction, }); authorize(user, "updateDocument", collection); } const { documents, collections } = await documentMover(ctx, { document, collectionId: collectionId ?? null, parentDocumentId: input.parentDocumentId ?? null, index: input.index, }); const indexMap = new Map(); for (const col of collections) { if (col.documentStructure) { for (const [id, idx] of buildSiblingIndexMap( col.documentStructure )) { indexMap.set(id, idx); } } } const presented = await Promise.all( documents.map(async (doc) => { const result = pathToUrl( user.team, await presentDocument(undefined, doc, { includeData: false, includeText: false, }) ); const siblingIndex = indexMap.get(doc.id); if (siblingIndex !== undefined) { result.index = siblingIndex; } return result; }) ); return success(presented); }); } catch (message) { return error(message); } }) ); } if (AuthenticationHelper.canAccess("documents.update", scopes)) { server.registerTool( "update_document", { title: "Update document", description: "Updates an existing document by its ID. Only the fields provided will be updated.", annotations: { idempotentHint: true, readOnlyHint: false, }, inputSchema: { id: z .string() .describe("The unique identifier of the document to update."), title: z .string() .optional() .describe("The new title for the document."), text: z .string() .optional() .describe("The new markdown content for the document."), editMode: z .enum(TextEditMode) .optional() .describe("How to apply the text update. Defaults to replace."), collectionId: z .string() .optional() .describe( "The collection ID to publish a draft to, required when publishing a draft that has no collection." ), icon: z .string() .nullable() .optional() .describe( "An icon for the document, e.g. an emoji. Set to null to remove." ), color: z .string() .nullable() .optional() .describe( "The hex color for the document icon. Set to null to remove." ), publish: z .boolean() .optional() .describe( "Set to true to publish a draft document, or false to convert a published document back to a draft." ), }, }, withTracing("update_document", async (input, context) => { try { const ctx = buildAPIContext(context); const { user } = ctx.state.auth; const document = await Document.findByPk(input.id, { userId: user.id, includeState: true, rejectOnEmpty: true, }); let updated; if (input.publish === false) { authorize(user, "unpublish", document); updated = await document.unpublishWithCtx(ctx, { detach: false, }); } else { authorize(user, "update", document); updated = await documentUpdater(ctx, { document, ...input, }); } const { text, ...attributes } = await presentDocument( undefined, updated, { includeData: false, includeText: true, includeUpdatedAt: true, } ); return { content: [ { type: "text" as const, text: JSON.stringify(pathToUrl(user.team, attributes)), }, { type: "text" as const, text: String(text ?? ""), }, ], } satisfies CallToolResult; } catch (message) { return error(message); } }) ); } }