README.md•5.57 kB
# 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:
```bash
git clone <repository-url>
cd shortcut-mcp
```
2. Install dependencies using pnpm:
```bash
pnpm install
```
3. Create the configuration directory and file:
```bash
mkdir -p ~/.shortcut_mcp
echo "SHORTCUT_TOKEN=your-api-token-here" > ~/.shortcut_mcp/.env
```
4. Build the project:
```bash
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:
```bash
./start_mcp.sh
```
For development mode with hot reload:
```bash
./start_mcp.sh dev
```
For hot reload support that maintains MCP connection:
```bash
./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