# 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