Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:73-89 (handler)

  The core handler function that executes the tool logic: creates a new document using the Shortcut client API and returns a formatted result or error.

  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 the parameters for the documents-create tool: title (string, max 256 chars) and content (string in HTML).

  {
  	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)

  Registration of the documents-create tool on the CustomMcpServer, specifying name, description, input schema, and handler function.

  server.addToolWithWriteAccess(
  	"documents-create",
  	"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),
  );