Files
outline/server/tools/collections.ts
Tom Moor 1bd6ad830e MCP improvements (#11822)
* fix: Data always included in list_documents response

* Remove resources, add fetch tool
Fix pagination arguments do not accept string

* type -> resource

* Add URL resolving
2026-03-20 09:45:50 -04:00

284 lines
8.6 KiB
TypeScript

import { z } from "zod";
import { Sequelize, Op, type WhereOptions } from "sequelize";
import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { CollectionPermission } from "@shared/types";
import { Collection, Team } from "@server/models";
import { authorize } from "@server/policies";
import { presentCollection } from "@server/presenters";
import AuthenticationHelper from "@shared/helpers/AuthenticationHelper";
import { UrlHelper } from "@shared/utils/UrlHelper";
import {
success,
error,
getActorFromContext,
buildAPIContext,
pathToUrl,
withTracing,
} from "./util";
/**
* Registers collection-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 collectionTools(server: McpServer, scopes: string[]) {
if (AuthenticationHelper.canAccess("collections.list", scopes)) {
server.registerTool(
"list_collections",
{
title: "List collections",
description:
"Lists all collections the authenticated user has access to. Returns a summary of each collection.",
annotations: {
idempotentHint: true,
readOnlyHint: true,
},
inputSchema: {
query: z
.string()
.optional()
.describe(
"An optional search query to filter collections by name."
),
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_collections",
async ({ query, offset, limit }, extra) => {
try {
const user = getActorFromContext(extra);
const collectionIds = await user.collectionIds();
const and: WhereOptions<Collection>[] = [
{ deletedAt: { [Op.eq]: null } },
{ archivedAt: { [Op.eq]: null } },
{ id: collectionIds },
];
if (query) {
and.push(
Sequelize.literal(
`unaccent(LOWER(name)) like unaccent(LOWER(:query))`
) as unknown as WhereOptions<Collection>
);
}
const where: WhereOptions<Collection> = {
teamId: user.teamId,
[Op.and]: and,
};
const collections = await Collection.scope({
method: ["withMembership", user.id],
}).findAll({
where,
replacements: { query: `%${query}%` },
order: [
Sequelize.literal('"collection"."index" collate "C"'),
["updatedAt", "DESC"],
],
offset: offset ?? 0,
limit: limit ?? 25,
});
// If the query looks like a collection ID or urlId, try direct
// lookup first so exact matches appear at the top of results.
let exactMatch: Collection | null = null;
if (query && UrlHelper.SLUG_URL_REGEX.test(query)) {
exactMatch = await Collection.findByPk(query, {
userId: user.id,
});
if (exactMatch && !collectionIds.includes(exactMatch.id)) {
exactMatch = null;
}
}
const presented = await Promise.all(
collections
.filter((c) => c.id !== exactMatch?.id)
.map(async (collection) =>
pathToUrl(
user.team,
await presentCollection(undefined, collection)
)
)
);
if (exactMatch) {
presented.unshift(
pathToUrl(
user.team,
await presentCollection(undefined, exactMatch)
)
);
}
return success(presented);
} catch (message) {
return error(message);
}
}
)
);
}
if (AuthenticationHelper.canAccess("collections.create", scopes)) {
server.registerTool(
"create_collection",
{
title: "Create collection",
description:
"Creates a new collection. Collections are used to organize documents.",
annotations: {
idempotentHint: false,
readOnlyHint: false,
},
inputSchema: {
name: z.string().describe("The name of the collection."),
description: z
.string()
.optional()
.describe("A markdown description for the collection."),
icon: z
.string()
.optional()
.describe("An icon for the collection, e.g. an emoji."),
color: z
.string()
.optional()
.describe("The hex color for the collection icon, e.g. #FF0000."),
},
},
withTracing("create_collection", async (input, context) => {
try {
const ctx = buildAPIContext(context);
const { user } = ctx.state.auth;
const team = await Team.findByPk(user.teamId, {
rejectOnEmpty: true,
});
authorize(user, "createCollection", team);
const collection = Collection.build({
name: input.name,
description: input.description,
icon: input.icon,
color: input.color,
teamId: user.teamId,
createdById: user.id,
permission: CollectionPermission.ReadWrite,
});
await collection.saveWithCtx(ctx);
const reloaded = await Collection.findByPk(collection.id, {
userId: user.id,
rejectOnEmpty: true,
});
const presented = pathToUrl(
user.team,
await presentCollection(undefined, reloaded)
);
return success(presented);
} catch (message) {
return error(message);
}
})
);
}
if (AuthenticationHelper.canAccess("collections.update", scopes)) {
server.registerTool(
"update_collection",
{
title: "Update collection",
description:
"Updates an existing collection 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 collection to update."),
name: z
.string()
.optional()
.describe("The new name for the collection."),
description: z
.string()
.optional()
.describe("The new markdown description for the collection."),
icon: z
.string()
.nullable()
.optional()
.describe(
"An icon for the collection, e.g. an emoji. Set to null to remove."
),
color: z
.string()
.nullable()
.optional()
.describe(
"The hex color for the collection icon. Set to null to remove."
),
},
},
withTracing("update_collection", async (input, context) => {
try {
const ctx = buildAPIContext(context);
const { user } = ctx.state.auth;
const collection = await Collection.findByPk(input.id, {
userId: user.id,
rejectOnEmpty: true,
});
authorize(user, "update", collection);
if (input.name !== undefined) {
collection.name = input.name.trim();
}
if (input.description !== undefined) {
collection.description = input.description;
}
if (input.icon !== undefined) {
collection.icon = input.icon;
}
if (input.color !== undefined) {
collection.color = input.color;
}
await collection.saveWithCtx(ctx);
const presented = pathToUrl(
user.team,
await presentCollection(undefined, collection)
);
return success(presented);
} catch (message) {
return error(message);
}
})
);
}
}