MCP Linear.app Server

# Testing Checklist Use this checklist to verify all functionality of the MCP Linear.app server. ## Prerequisites - [ ] Bun 1.0.0+ installed (or Node.js 18+) - [ ] Linear API key obtained - [ ] Dependencies installed (`bun install`) - [ ] Project built successfully (`bun run build`) - [ ] No TypeScript errors (`bun run typecheck`) - [ ] No linting errors (`bun run lint`) ## Build Verification ```bash # Should complete without errors bun run build # Should pass with no errors bun run typecheck # Should complete with no errors/warnings bun run lint ``` - [ ] Build completes successfully - [ ] TypeScript compilation successful - [ ] Linting passes - [ ] `dist/` folder created with compiled JS ## Environment Setup - [ ] `.env` file created - [ ] `LINEAR_API_KEY` set in `.env` - [ ] API key is valid (test at https://linear.app/settings/api) - [ ] API key has required permissions ## Server Startup ```bash export LINEAR_API_KEY=your_key_here bun run dist/index.js # or with Node.js: node dist/index.js ``` - [ ] Server starts without errors - [ ] Shows "Linear MCP Server running on stdio" - [ ] No initialization errors - [ ] Connects to Linear API successfully ## Tool: linear_list_teams ### Test Cases ``` List all Linear teams ``` - [ ] Returns list of teams - [ ] Each team has: id, name, key, description - [ ] Response is valid JSON - [ ] No errors ``` List all teams including archived ``` - [ ] Returns teams including archived ones - [ ] Properly filters based on includeArchived parameter ### Expected Behavior - Returns 200-level response - Valid JSON structure - Team objects properly formatted ## Tool: linear_list_users ### Test Cases ``` List all Linear users ``` - [ ] Returns list of users - [ ] Each user has: id, name, email, displayName, active, admin - [ ] Response is valid JSON - [ ] No errors ``` List all users including disabled ``` - [ ] Returns users including disabled ones - [ ] Properly filters based on includeDisabled parameter ### Expected Behavior - Returns all active users by default - User objects properly formatted ## Tool: linear_list_projects ### Test Cases ``` List all Linear projects ``` - [ ] Returns list of projects - [ ] Each project has: id, name, description, state, progress, dates, lead - [ ] Response is valid JSON ``` List projects for team [TEAM_ID] ``` - [ ] Returns only projects for specified team - [ ] Properly filters by teamId ### Expected Behavior - Projects properly formatted - Team filtering works correctly ## Tool: linear_list_workflow_states ### Test Cases ``` List workflow states for team [TEAM_ID] ``` - [ ] Returns list of workflow states - [ ] Each state has: id, name, type, color, description, position - [ ] States in correct order (by position) ### Expected Behavior - Must provide teamId (required parameter) - Returns team-specific workflow states ## Tool: linear_list_labels ### Test Cases ``` List all Linear labels ``` - [ ] Returns list of labels - [ ] Each label has: id, name, color, description ``` List labels for team [TEAM_ID] ``` - [ ] Returns only team-specific labels ### Expected Behavior - Labels properly formatted - Team filtering works ## Tool: linear_create_label ### Test Cases ``` Create a label called "test-label" for team [TEAM_ID] ``` - [ ] Creates label successfully - [ ] Returns created label with id - [ ] Label appears in linear_list_labels ``` Create a label with color "#FF0000" and description ``` - [ ] Creates label with specified color - [ ] Description is set correctly ### Expected Behavior - Returns success message - Label is actually created in Linear - Error if team doesn't exist ## Tool: linear_list_issues ### Test Cases ``` List all issues in Linear ``` - [ ] Returns list of issues (up to default limit of 25) - [ ] Each issue has full structure: id, identifier, title, description, state, assignee, team, project, labels, etc. ``` List issues for team [TEAM_ID] ``` - [ ] Returns only issues for specified team ``` List issues with status "started" ``` - [ ] Returns only in-progress issues - [ ] Properly filters by status ``` List urgent priority issues ``` - [ ] Returns only priority 1 issues - [ ] Priority filtering works ``` List issues assigned to [USER_ID] ``` - [ ] Returns only issues assigned to specified user ``` List issues for project [PROJECT_ID] ``` - [ ] Returns only issues in specified project ``` List issues with label "bug" ``` - [ ] Returns only issues with specified label ``` List 50 issues (test limit parameter) ``` - [ ] Returns up to 50 issues - [ ] Respects limit parameter ### Expected Behavior - Filters can be combined - Default limit is 25 - All issue fields properly populated ## Tool: linear_create_issue ### Test Cases ``` Create an issue titled "Test Issue" in team [TEAM_ID] ``` - [ ] Creates issue successfully - [ ] Returns created issue with identifier (e.g., "ENG-123") - [ ] Issue appears in Linear ``` Create an issue with full parameters: - title: "Full Test" - description: "This is a test issue" - teamId: [TEAM_ID] - priority: 2 (High) - assigneeId: [USER_ID] - projectId: [PROJECT_ID] ``` - [ ] Creates issue with all fields - [ ] All fields set correctly - [ ] Issue has assignee, project, priority ``` Create sub-issue with parentId ``` - [ ] Creates sub-issue successfully - [ ] Parent relationship established ### Error Cases - [ ] Missing title shows error - [ ] Missing teamId shows error - [ ] Invalid teamId shows error - [ ] Invalid priority (5) shows error ## Tool: linear_update_issue ### Test Cases ``` Update issue [ISSUE_ID] to change title to "Updated Title" ``` - [ ] Updates issue successfully - [ ] Title changed in Linear - [ ] Returns updated issue ``` Update issue [ISSUE_ID] to set priority to urgent (1) ``` - [ ] Priority updated - [ ] Change reflected in Linear ``` Update issue [ISSUE_ID] to assign to [USER_ID] ``` - [ ] Assignee updated - [ ] User assigned successfully ``` Update issue [ISSUE_ID] to add to project [PROJECT_ID] ``` - [ ] Project assignment works - [ ] Issue appears in project ``` Update issue [ISSUE_ID] to change state to [STATE_ID] ``` - [ ] State/status updated - [ ] Workflow state changed ### Error Cases - [ ] Invalid issue ID shows error - [ ] Invalid assignee ID shows error - [ ] Invalid state ID shows error ## Tool: linear_get_issue ### Test Cases ``` Get details for issue [ISSUE_ID] ``` - [ ] Returns full issue details - [ ] All fields populated - [ ] No errors ``` Get issue by identifier (e.g., "ENG-123") ``` - [ ] Works with issue identifier - [ ] Returns same data as by ID ### Error Cases - [ ] Invalid issue ID shows error - [ ] Non-existent issue shows error ## Tool: linear_search_issues ### Test Cases ``` Search for issues about "authentication" ``` - [ ] Returns relevant issues - [ ] Search works across title and description - [ ] Results ranked by relevance ``` Search "test" in team [TEAM_ID] ``` - [ ] Returns only results from specified team - [ ] Team filter works with search ``` Search with limit of 10 ``` - [ ] Returns max 10 results - [ ] Limit parameter respected ### Expected Behavior - Full-text search across issues - Can combine with team filter - Returns ranked results ## Tool: linear_assign_issue ### Test Cases ``` Assign issue [ISSUE_ID] to user [USER_ID] ``` - [ ] Issue assigned successfully - [ ] Assignee updated in Linear - [ ] Returns success message ### Error Cases - [ ] Invalid issue ID shows error - [ ] Invalid user ID shows error ## Tool: linear_add_comment ### Test Cases ``` Add comment to issue [ISSUE_ID]: "This is a test comment" ``` - [ ] Comment added successfully - [ ] Comment appears in Linear - [ ] Returns comment ID and timestamp ``` Add comment with markdown: "## Heading\n- Item 1\n- Item 2" ``` - [ ] Markdown preserved - [ ] Comment formatted correctly ### Error Cases - [ ] Invalid issue ID shows error - [ ] Empty comment body shows error ## Tool: linear_create_cycle ### Test Cases ``` Create cycle for team [TEAM_ID]: - name: "Test Sprint" - startsAt: "2024-02-01" - endsAt: "2024-02-14" ``` - [ ] Cycle created successfully - [ ] Appears in Linear - [ ] Dates set correctly ``` Create cycle with description ``` - [ ] Description field works - [ ] Cycle has description ### Error Cases - [ ] Invalid team ID shows error - [ ] Missing required fields shows error - [ ] Invalid date format shows error - [ ] End date before start date shows error ## Tool: linear_list_cycles ### Test Cases ``` List cycles for team [TEAM_ID] ``` - [ ] Returns team's cycles - [ ] Each cycle has: id, number, name, dates, progress, team ``` List cycles including archived ``` - [ ] Returns archived cycles - [ ] Archive filter works ### Expected Behavior - Team filtering works - Cycles properly formatted ## MCP Client Integration ### Setup - [ ] MCP client config created - [ ] Absolute path used for dist/index.js - [ ] API key in env section - [ ] Config file valid JSON ### Connection Test - [ ] MCP client restarted - [ ] No connection errors in logs - [ ] Tools appear available ### Natural Language Tests ``` List all my Linear teams ``` - [ ] Works with natural language - [ ] Returns teams ``` Create a test issue in the Engineering team ``` - [ ] Understands team name (not just ID) - [ ] Creates issue successfully ``` Show me all high priority issues assigned to me ``` - [ ] Combines multiple filters - [ ] Returns correct results ``` Create a 2-week sprint starting next Monday ``` - [ ] Understands relative dates - [ ] Creates cycle correctly ### Workflow Tests **Daily Standup:** 1. List my assigned issues 2. Filter for "started" status 3. Add update comments - [ ] Complete workflow works - [ ] All steps successful **Sprint Planning:** 1. List teams 2. Create new cycle 3. List backlog issues 4. Update issues to add to cycle - [ ] Complete workflow works - [ ] Cycle creation works - [ ] Issue updates work **Bug Triage:** 1. Search for "bug" issues 2. Create bug labels if needed 3. Assign bugs to team members 4. Set priorities - [ ] Complete workflow works - [ ] All operations successful ## Error Handling Tests ### API Errors - [ ] Invalid API key shows clear message - [ ] Rate limit error handled gracefully - [ ] Network error handled properly ### Validation Errors - [ ] Missing required parameter shows error - [ ] Invalid parameter type shows error - [ ] Invalid enum value shows error - [ ] Out of range value shows error ### Linear API Errors - [ ] Not found errors clear - [ ] Permission errors clear - [ ] Invalid ID errors helpful ## Performance Tests ``` List 100 issues (max limit) ``` - [ ] Completes in reasonable time (<5s) - [ ] Doesn't timeout ``` Create 5 issues rapidly ``` - [ ] All created successfully - [ ] No rate limit issues (or handled gracefully) ``` Search with broad query ``` - [ ] Returns results promptly - [ ] Handles large result sets ## Security Tests - [ ] API key not exposed in error messages - [ ] API key not logged - [ ] Sensitive data not in logs - [ ] Environment variable required - [ ] Invalid credentials handled safely ## Documentation Tests - [ ] README examples work - [ ] Quick Start guide accurate - [ ] API Reference matches implementation - [ ] Development guide accurate - [ ] All code examples functional ## Final Checklist ### Code Quality - [ ] No TypeScript errors - [ ] No ESLint warnings - [ ] Code formatted with Prettier - [ ] All files have proper headers - [ ] Imports use .js extension ### Functionality - [ ] All 15 tools work - [ ] All parameters validated - [ ] All errors handled - [ ] All responses formatted ### Documentation - [ ] README complete - [ ] API reference accurate - [ ] Quick start tested - [ ] Development guide accurate - [ ] Examples all work ### Integration - [ ] MCP client config works - [ ] Natural language commands work - [ ] Workflows complete successfully - [ ] No client errors ## Sign Off - [ ] All critical tests passing - [ ] All tools functional - [ ] Documentation accurate - [ ] Ready for production use --- **Tester Name:** **\*\*\*\***\_\_\_**\*\*\*\*** **Date:** **\*\*\*\***\_\_\_**\*\*\*\*** **Version Tested:** **\*\*\*\***\_\_\_**\*\*\*\*** **Status:** ☐ Pass ☐ Fail ☐ Needs Work **Notes:**