Shortcut MCP Server

Instructions

Implementation Reference

• src/tools/stories.ts:425-438 (handler)

  Handler function that implements the tool logic: fetches current user and story, uses existing branch name if available or generates one via createBranchName, and returns it.

  async getStoryBranchName(storyPublicId: number) {
  	const currentUser = await this.client.getCurrentUser();
  	if (!currentUser) throw new Error("Unable to find current user");
  
  	const story = await this.client.getStory(storyPublicId);
  
  	if (!story)
  		throw new Error(`Failed to retrieve Shortcut story with public ID: ${storyPublicId}`);
  
  	const branchName =
  		(story as Story & { formatted_vcs_branch_name: string | null }).formatted_vcs_branch_name ||
  		this.createBranchName(currentUser, story);
  	return this.toResult(`Branch name for story sc-${storyPublicId}: ${branchName}`);
  }

• src/tools/stories.ts:119-126 (registration)

  Registers the 'stories-get-branch-name' tool with MCP server, including input schema and handler reference.

  server.addToolWithReadAccess(
  	"stories-get-branch-name",
  	"Get a valid branch name for a specific story.",
  	{
  		storyPublicId: z.number().positive().describe("The public Id of the story"),
  	},
  	async ({ storyPublicId }) => await tools.getStoryBranchName(storyPublicId),
  );

• src/tools/stories.ts:418-423 (helper)

  Helper function to generate a formatted branch name from user mention name, story ID, and sanitized story name.

  private createBranchName(currentUser: MemberInfo, story: Story) {
  	return `${currentUser.mention_name}/sc-${story.id}/${story.name
  		.toLowerCase()
  		.replace(/\s+/g, "-")
  		.replace(/[^\w-]/g, "")}`.substring(0, 50);
  }