README - Mo - Linear Task Management for Cursor IDE by ztfo

Mo - Linear Task Management for Cursor IDE

Mo is a task management tool designed as a Model Context Protocol (MCP) server for Cursor IDE. It provides seamless integration with Linear for issue tracking and task management, allowing developers to manage their workflow directly from within Cursor.

Project Status

Phase 1: ✅ Completed (March 21, 2024) - Core infrastructure and basic task management
Phase 2: ✅ Completed (April 5, 2024) - Linear integration and chat tool support
Phase 3: 🔄 In Progress - AI enhancement features
Phase 4: 📅 Planned - Advanced features and polish

See the for more details on the project timeline and phases.

Features

Task Management: Create, update, and track tasks directly in Cursor
Context-Awareness: Create tasks from code selections or current file context
Protocol Version Handling: Support for Cursor MCP protocol version compatibility
Rich Responses: Markdown-formatted responses with action buttons
Linear Integration: Sync tasks with Linear for team collaboration
- Authentication with secure credential storage
- Bidirectional synchronization between local tasks and Linear issues
- Filtering and querying Linear issues
- Support for projects, teams, and workflow states
Chat Integration: Use Linear tools directly in Claude chat within Cursor
Webhook Support: Register webhooks for real-time issue updates (optional)

Installation

Prerequisites

Cursor IDE
Node.js 16+
Linear account (for Linear integration)

Option 1: Install From npm (Recommended)

The package is available on npm and can be installed globally:

npm install -g mo-linear-mcp

You can also use it directly without installation via npx:

npx mo-linear-mcp

Visit the package on npm: mo-linear-mcp

Option 2: Local Development Setup

Clone this repository:

git clone https://github.com/yourusername/mo-linear-mcp.git
cd mo-linear-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Run in development mode:
```
npm run dev
```

Cursor MCP Configuration

To use Mo in Cursor, you need to configure it in the MCP settings. Here's an example configuration:

{
  "version": "0.1",
  "mcps": {
    "mo-linear-mcp-dev": {
      "name": "Mo Linear MCP (Dev)",
      "description": "Linear Task Management for Cursor IDE - Development Mode",
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/your/mo-linear-mcp",
      "enabled": true
    },
    "linear": {
      "name": "Linear",
      "description": "Linear Task Management for Cursor",
      "command": "npx",
      "args": ["-y", "mo-linear-mcp"],
      "enabled": true
    }
  }
}

To access the MCP configuration in Cursor:

Open Cursor IDE
Go to Settings → Extensions → MCP Servers
Click "Edit MCP Config" and paste the configuration above
Adjust the "cwd" path to match your local repository path (for development mode)

Development and Publishing

Local Development

For rapid development and testing:

# Watch for changes
npm run watch

# In another terminal, test commands
echo '{"command": "/mo linear-status"}' | npm run dev

Usage

Editor Mode Commands

Mo provides commands that can be used directly in the editor:

Basic Commands

/mo tasks - List all tasks with optional filtering
/mo new-task - Create a new task
/mo update-task - Update an existing task
/mo task-details - View task details
/mo delete-task - Delete a task
/mo help - Show help information
/mo settings - View/update settings

Linear Commands

/mo linear-auth - Authenticate with Linear API
/mo linear-status - Check Linear authentication status
/mo linear-logout - Log out from Linear API
/mo linear-teams - List Linear teams
/mo linear-projects - List Linear projects
/mo linear-states - List Linear workflow states
/mo linear-issues - List Linear issues
/mo linear-sync - Synchronize with Linear
/mo linear-push - Push tasks to Linear
/mo linear-pull - Pull issues from Linear

Chat Mode Tools

Mo can also be used directly in the Claude chat interface with the following syntax:

@Linear linear_auth key:your_api_key
@Linear linear_status
@Linear linear_teams
@Linear linear_projects team:team-id
@Linear linear_issues team:team-id
@Linear linear_sync

Authentication

To use the Linear integration, you need to authenticate with your Linear API key:

/mo linear-auth key:your_linear_api_key

Or in chat mode:

@Linear linear_auth key:your_linear_api_key

You can get your Linear API key from Linear's settings page.

Development

Project Structure

mo-linear-mcp/
├── src/             # Source code
│   ├── index.ts     # Entry point
│   ├── server.ts    # MCP server implementation
│   ├── commands/    # Command processing
│   ├── data/        # Data persistence
│   ├── linear/      # Linear API integration
│   ├── utils/       # Utility functions
│   └── types/       # TypeScript types
├── data/            # Local data storage
└── docs/            # Documentation
    ├── architecture/  # Architecture documentation
    ├── mcp/           # MCP-related documentation
    ├── linear/        # Linear integration documentation
    └── features/      # Feature specifications

Development Commands

# Build the project
npm run build

# Run in development mode
npm run dev

# Watch for changes
npm run watch

# Run linter
npm run lint

# Run tests
npm run test

Publishing

To publish the package to npm:

# Build the project
npm run build

# Make sure the binary is executable
chmod +x dist/index.js

# Create npm account if needed
npm adduser

# Publish to npm
npm publish

Debugging

Mo includes built-in debugging that logs to /tmp/mo-mcp-debug.log. Check this file for troubleshooting.

For more detailed debugging:

# Test MCP response handling
echo '{"command": "/mo linear-status"}' | npm run dev

# Test chat tool invocation directly
node dist/index.js linear_status

Documentation

- High-level plan and timeline
- Project status and context
- Chat integration details
- Command documentation
- Linear integration details
- Development guide

License

This project is licensed under the ISC License - see the LICENSE file for details.

Acknowledgements

Cursor IDE for the MCP platform
Linear for their excellent issue tracking API