Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:102-129 (handler)

  The handler function that executes the core logic for the 'documents-search' tool. It calls the ShortcutClientWrapper's searchDocuments method, processes the response (including pagination), handles empty results and errors, and formats the output using toResult.

  private async searchDocuments(
  	params: {
  		title: string;
  		archived?: boolean;
  		createdByCurrentUser?: boolean;
  		followedByCurrentUser?: boolean;
  	},
  	nextPageToken?: string,
  ) {
  	try {
  		const { documents, total, next_page_token } = await this.client.searchDocuments({
  			...params,
  			nextPageToken,
  		});
  
  		if (!documents) throw new Error(`Failed to search for document matching your query.`);
  		if (!documents.length) return this.toResult(`Result: No documents found.`);
  
  		return this.toResult(
  			`Result (${documents.length} shown of ${total} total documents found):`,
  			documents,
  			next_page_token,
  		);
  	} catch (error) {
  		const errorMessage = error instanceof Error ? error.message : "Unknown error";
  		return this.toResult(`Failed to search documents: ${errorMessage}`);
  	}
  }

• src/tools/documents.ts:30-59 (registration)

  Registers the 'documents-search' tool using server.addToolWithReadAccess, specifying the tool name, description, input schema, and the inline handler that delegates to the searchDocuments method.

  server.addToolWithReadAccess(
  	"documents-search",
  	"Find documents.",
  	{
  		nextPageToken: z
  			.string()
  			.optional()
  			.describe(
  				"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  			),
  		title: z.string().describe("Find documents matching the specified name"),
  		archived: z
  			.boolean()
  			.optional()
  			.describe("Find only documents matching the specified archived status"),
  		createdByCurrentUser: z
  			.boolean()
  			.optional()
  			.describe("Find only documents created by current user"),
  		followedByCurrentUser: z
  			.boolean()
  			.optional()
  			.describe("Find only documents followed by current user"),
  	},
  	async ({ nextPageToken, title, archived, createdByCurrentUser, followedByCurrentUser }) =>
  		await tools.searchDocuments(
  			{ title, archived, createdByCurrentUser, followedByCurrentUser },
  			nextPageToken,
  		),
  );

• src/tools/documents.ts:33-53 (schema)

  Zod-based input schema for the 'documents-search' tool, defining parameters like title (required), and optional fields for pagination, archived status, and user-specific filters.

  {
  	nextPageToken: z
  		.string()
  		.optional()
  		.describe(
  			"If a next_page_token was returned from the search result, pass it in to get the next page of results. Should be combined with the original search parameters.",
  		),
  	title: z.string().describe("Find documents matching the specified name"),
  	archived: z
  		.boolean()
  		.optional()
  		.describe("Find only documents matching the specified archived status"),
  	createdByCurrentUser: z
  		.boolean()
  		.optional()
  		.describe("Find only documents created by current user"),
  	followedByCurrentUser: z
  		.boolean()
  		.optional()
  		.describe("Find only documents followed by current user"),
  },

• src/client/shortcut.ts:548-581 (helper)

  Supporting method in ShortcutClientWrapper that performs the actual API call to Shortcut's searchDocuments endpoint, maps parameters, handles feature access errors, extracts pagination token, and returns structured results.

  async searchDocuments({
  	title,
  	archived,
  	createdByCurrentUser,
  	followedByCurrentUser,
  	pageSize = 25,
  	nextPageToken,
  }: {
  	title: string;
  	archived?: boolean;
  	createdByCurrentUser?: boolean;
  	followedByCurrentUser?: boolean;
  	pageSize?: number;
  	nextPageToken?: string;
  }) {
  	const response = await this.client.searchDocuments({
  		title,
  		archived,
  		created_by_me: createdByCurrentUser,
  		followed_by_me: followedByCurrentUser,
  		page_size: pageSize,
  		next: nextPageToken,
  	});
  
  	if (response.status === 403) throw new Error("Docs feature disabled for this workspace.");
  
  	const documents = response?.data?.data;
  	const total = response?.data?.total;
  	const next = response?.data?.next;
  
  	if (!documents) return { documents: null, total: null, next_page_token: null };
  
  	return { documents, total, next_page_token: this.getNextPageToken(next) };
  }

• src/tools/base.ts:650-663 (helper)

  Utility method from BaseTools used to format tool responses as MCP CallToolResult, embedding JSON data and pagination tokens in text content.

  protected toResult(
  	message: string,
  	data?: unknown,
  	paginationToken?: string | null | undefined,
  ): CallToolResult {
  	return {
  		content: [
  			{
  				type: "text",
  				text: `${message}${data !== undefined ? `\n\n<json>\n${JSON.stringify(data, null, 2)}\n</json>${paginationToken ? `\n\n<next-page-token>${paginationToken}</next-page-token>` : ""}` : ""}`,
  			},
  		],
  	};
  }