Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:25-41 (handler)

  Implements the core logic of the 'create-document' tool: calls client.createDoc with title and content, returns formatted success result with id, title, app_url or error message using toResult helper.

  private async createDocument(title: string, content: string) {
  	try {
  		const doc = await this.client.createDoc({
  			title,
  			content,
  		});
  
  		return this.toResult("Document created successfully", {
  			id: doc.id,
  			title: doc.title,
  			app_url: doc.app_url,
  		});
  	} catch (error) {
  		const errorMessage = error instanceof Error ? error.message : "Unknown error";
  		return this.toResult(`Failed to create document: ${errorMessage}`);
  	}
  }

• src/tools/documents.ts:13-20 (schema)

  Zod input schema defining 'title' (string, max 256 chars) and 'content' (string in HTML format).

  {
  	title: z.string().max(256).describe("The title for the new document (max 256 characters)"),
  	content: z
  		.string()
  		.describe(
  			"The content for the new document in HTML format (e.g., <p>Hello</p>, <h1>Title</h1>, <ul><li>Item</li></ul>)",
  		),
  },

• src/tools/documents.ts:10-22 (registration)

  Registers the 'create-document' tool on the MCP server, specifying name, description, input schema, and thin handler delegating to createDocument method.

  server.tool(
  	"create-document",
  	"Create a new document in Shortcut with a title and content. Returns the document's id, title, and app_url. Note: Use HTML markup for the content (e.g., <p>, <h1>, <ul>, <strong>) rather than Markdown.",
  	{
  		title: z.string().max(256).describe("The title for the new document (max 256 characters)"),
  		content: z
  			.string()
  			.describe(
  				"The content for the new document in HTML format (e.g., <p>Hello</p>, <h1>Title</h1>, <ul><li>Item</li></ul>)",
  			),
  	},
  	async ({ title, content }) => await tools.createDocument(title, content),
  );

• src/tools/base.ts:462-471 (helper)

  BaseTools helper method to format MCP tool results as CallToolResult with a text content block containing message and optional pretty-printed JSON data.

  protected toResult(message: string, data?: unknown): CallToolResult {
  	return {
  		content: [
  			{
  				type: "text",
  				text: `${message}${data !== undefined ? `\n\n${JSON.stringify(data, null, 2)}` : ""}`,
  			},
  		],
  	};
  }