Shortcut MCP Server

Shortcut MCP Server

A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Shortcut API and analyzing Loom videos attached to stories. This server helps developers:

• Read and update stories, manage comments, and query project data
• Analyze Loom videos for debugging insights
• Correlate video content with codebase to identify relevant files
• Generate debugging plans based on video analysis

Features

• Story Management: Get, search, and update stories
• Comment System: Add and retrieve story comments
• Project Organization: List projects, epics, and workflows
• File Attachments: Download and analyze file attachments from stories
• Video Analysis: Extract and analyze Loom videos from stories for debugging
• Codebase Correlation: Match video content with relevant source files
• Debugging Assistance: Generate debugging plans from video analysis
• Type Safety: Full TypeScript support with comprehensive type definitions
• Error Handling: Robust error handling with detailed error messages
• Response Size Management: Automatic warnings for large responses (>20k tokens)

Installation

1. Clone the repository:

git clone <repository-url>
cd shortcut-mcp

2. Install dependencies using pnpm:

pnpm install

3. Create the configuration directory and file:

mkdir -p ~/.shortcut_mcp
echo "SHORTCUT_TOKEN=your-api-token-here" > ~/.shortcut_mcp/.env

4. Build the project:

pnpm run build

Configuration

The server reads the Shortcut API token from ~/.shortcut_mcp/.env. This file should contain:

SHORTCUT_TOKEN=your-shortcut-api-token

To obtain your Shortcut API token:

1. Log in to Shortcut
2. Navigate to Settings > API Tokens
3. Generate a new token
4. Copy the token to your .env file

Usage

Start the MCP server:

./start_mcp.sh

For development mode with hot reload:

./start_mcp.sh dev

For hot reload support that maintains MCP connection:

./start_mcp_with_proxy.sh
# In another terminal, trigger reload with:
./reload_mcp.sh

Available Tools

Story Operations

• shortcut_get_story - Get detailed information about a specific story
• shortcut_search_stories - Search for stories using Shortcut's query syntax
• shortcut_get_project_stories - Get all stories in a specific project
• shortcut_get_epic_stories - Get all stories in a specific epic
• shortcut_update_story - Update story attributes (description, labels, workflow state, etc.)

Comment Operations

• shortcut_add_comment - Add a comment to a story
• shortcut_get_comments - Retrieve all comments for a story

Organization Tools

• shortcut_list_workflows - List all workflows and their states
• shortcut_list_projects - List all projects in the workspace
• shortcut_list_epics - List all epics in the workspace

File Operations

• shortcut_get_story_files - Get all file attachments for a story
• shortcut_download_file - Download file content from attachments (text or binary)

Video Analysis Tools

• shortcut_get_story_loom_videos - Extract Loom video links from a story
• shortcut_analyze_loom_video - Analyze Loom video metadata, transcript, and debugging insights
• shortcut_analyze_video_with_codebase - Correlate video content with codebase files
• shortcut_debug_video_issue - Deep debugging analysis with action tracking and error detection
• shortcut_analyze_video_with_anthropic - (Currently disabled) Visual analysis using Claude Vision

Development

Scripts

• pnpm run dev - Run in development mode with hot reload
• pnpm run build - Build TypeScript to JavaScript
• pnpm run typecheck - Check TypeScript types
• pnpm run lint - Run ESLint
• pnpm run format - Format code with Prettier
• pnpm test - Run unit and integration tests

Project Structure

shortcut-mcp/
├── src/
│   ├── server.ts              # Main MCP server implementation
│   ├── shortcutClient.ts      # Shortcut API client
│   ├── shortcut-types.ts      # TypeScript type definitions
│   ├── loomClient.ts          # Loom API integration
│   ├── loomDetector.ts        # Loom URL detection utilities
│   ├── videoAnalysis.ts       # Core video analysis service
│   ├── videoCodeAnalyzer.ts   # Codebase correlation analysis
│   ├── enhancedVideoAnalyzer.ts # Deep debugging analysis
│   ├── audioAnalyzer.ts       # Audio transcript analysis
│   ├── visualAnalyzer.ts      # Visual element detection
│   ├── debuggingAssistant.ts  # Debugging plan generation
│   ├── proxy.ts               # Hot reload proxy server
│   └── mimeTypes.ts           # File type utilities
├── tests/                     # Test files
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── dist/                      # Compiled JavaScript (generated)
├── start_mcp.sh              # Standard server startup script
├── start_mcp_with_proxy.sh   # Hot reload startup script
├── reload_mcp.sh             # Trigger hot reload
├── package.json              # Project configuration
└── tsconfig.json             # TypeScript configuration

Error Handling

The server provides detailed error messages for common issues:

• Missing or invalid API token
• API request failures
• Invalid story/project/epic IDs
• Network connectivity issues

License

ISC