documents-search
Search for documents in Shortcut project management by title, archived status, or user association to locate specific project files.
Instructions
Find documents.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nextPageToken | No | 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 | Yes | Find documents matching the specified name | |
| archived | No | Find only documents matching the specified archived status | |
| createdByCurrentUser | No | Find only documents created by current user | |
| followedByCurrentUser | No | Find only documents followed by current user |
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>` : ""}` : ""}`, }, ], }; }