Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:131-140 (handler)

  The handler function for the 'documents-get-by-id' tool. It retrieves the document by ID using the Shortcut client and returns a formatted result or error.

  private async getDocumentById(docId: string) {
  	try {
  		const doc = await this.client.getDocById(docId);
  		if (!doc) return this.toResult(`Document with ID ${docId} not found.`);
  		return this.toResult(`Document with ID ${docId}`, doc);
  	} catch (error) {
  		const errorMessage = error instanceof Error ? error.message : "Unknown error";
  		return this.toResult(`Failed to get document: ${errorMessage}`);
  	}
  }

• src/tools/documents.ts:64-66 (schema)

  Input schema validation using Zod for the document ID parameter.

  {
  	docId: z.string().describe("The ID of the document to retrieve"),
  },

• src/tools/documents.ts:61-68 (registration)

  Registration of the 'documents-get-by-id' tool on the MCP server, including description, input schema, and handler binding.

  server.addToolWithReadAccess(
  	"documents-get-by-id",
  	"Get a document as markdown by its ID",
  	{
  		docId: z.string().describe("The ID of the document to retrieve"),
  	},
  	async ({ docId }: { docId: string }) => await tools.getDocumentById(docId),
  );

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

  Helper method used by the handler to format the tool response as MCP CallToolResult with JSON data embedded in text.

  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>` : ""}` : ""}`,
  			},
  		],
  	};
  }