Linear MCP Server

Linear MCP 服务

用于与 Linear API 交互的 MCP 服务。此服务提供一组工具，可通过 Cline 管理 Linear 问题、项目和团队。

设置指南

1. 环境设置

1. 克隆代码仓库
2. 安装依赖：

   npm install
   

3. 将 .env.example 复制为 .env：

   cp .env.example .env
   

2. 身份验证

此服务支持两种身份验证方式：

API 密钥（推荐）

1. 前往 Linear 设置
2. 导航到“Security & access”部分
3. 找到“Personal API keys”部分
4. 点击“New API key”
5. 为密钥添加一个描述性标签（例如“Cline MCP”）
6. 立即复制生成的令牌
7. 将令牌添加到 .env 文件中：

   LINEAR_API_KEY=your_api_key
   

OAuth 流程（替代方案）尚未实现

1. 在 https://linear.app/settings/api/applications 创建 OAuth 应用
2. 在 .env 中配置 OAuth 环境变量：

   LINEAR_CLIENT_ID=your_oauth_client_id
   LINEAR_CLIENT_SECRET=your_oauth_client_secret
   LINEAR_REDIRECT_URI=http://localhost:3000/callback
   

3. 运行服务

1. 构建服务：

   npm run build
   

2. 启动服务：

   npm start
   

4. Cline 集成

1. 打开 Cline MCP 设置文件：

   • macOS：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows：%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Linux：~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 添加 Linear MCP 服务配置：

   {
     "mcpServers": {
       "linear": {
         "command": "node",
         "args": ["/path/to/linear-mcp/build/index.js"],
         "env": {
           "LINEAR_API_KEY": "your_personal_access_token"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

可用操作

此服务目前支持以下操作：

问题管理

• ✅ 创建问题，支持所有字段（标题、描述、团队、项目等）
• ✅ 更新现有问题（优先级、描述等）
• ✅ 删除问题（单个或批量删除）
• ✅ 使用筛选条件搜索问题
• ✅ 将问题关联到项目
• ✅ 创建父子问题关系
• ✅ 读取和创建评论及串联评论

项目管理

• ✅ 创建项目并关联问题
• ✅ 获取项目信息，包含丰富文本描述
• ✅ 搜索项目，包含丰富文本描述
• ✅ 将问题关联到项目
• ✅ 使用 Linear 的 documentContent 字段正确处理描述

团队管理

• ✅ 获取团队信息（包含状态和工作流详情）
• ✅ 访问团队状态和标签

身份验证

• ✅ API 密钥身份验证
• ✅ 安全存储令牌

批量操作

• ✅ 批量创建问题
• ✅ 批量删除问题

批量更新（测试中）

• 🚧 批量更新问题（已实现并行处理，尚需测试）

丰富文本描述支持

此服务现在可以正确处理 Linear 项目的丰富文本描述：

• 旧版支持：保持与旧版 description 字段的兼容性
• 丰富内容：使用 Linear 的 documentContent 字段存储实际描述内容
• 自动回退：丰富内容不可用时，回退到旧版字段
• 类型安全：为两种描述格式提供了适当的 TypeScript 类型

工作原理

Linear 使用双字段系统存储描述：

1. description - 旧版字段（为保持向后兼容，通常为空）
2. documentContent.content - 包含实际丰富文本描述内容

MCP 服务会自动：

• 从 Linear API 查询这两个字段
• 优先使用 documentContent.content，而不是旧版 description 字段
• 提供工具函数 getProjectDescription()，以便一致地访问描述
• 在响应中返回 actualDescription 字段，方便访问

开发中的功能

目前正在开发以下功能：

问题管理

• 🚧 复杂搜索筛选条件
• 🚧 为大型结果集提供分页支持

元数据操作

• 🚧 标签管理（创建/更新/分配）
• 🚧 周期/里程碑管理

项目管理

• 🚧 项目模板支持
• 🚧 高级项目操作

身份验证

• 🚧 支持自动刷新令牌的 OAuth 流程

性能与安全

• 🚧 速率限制
• 🚧 详细日志记录
• 🚧 负载测试与优化

开发

# Install dependencies
npm install

# Run tests
npm test

# Run integration tests (requires LINEAR_API_KEY)
npm run test:integration

# Build the server
npm run build

# Start the server
npm start

集成测试

集成测试用于验证身份验证和 API 调用是否正常运行：

1. 设置身份验证（建议测试时使用 API Key）
2. 运行集成测试：

   npm run test:integration
   

测试 OAuth：

1. 在 .env 中配置 OAuth 凭据
2. 在 src/__tests__/auth.integration.test.ts 中移除 OAuth 测试的 .skip
3. 运行集成测试

最近的改进

项目描述支持（最新）

• ✅ 通过支持 Linear 的 documentContent 字段，修复项目描述为空的问题
• ✅ 为富文本内容添加适当的 TypeScript 类型
• ✅ 实现从富文本内容到旧版描述的自动回退
• ✅ 更新所有项目相关的查询和处理器
• ✅ 为新的描述处理方式添加全面的测试
• ✅ 与现有 API 使用者保持向后兼容

之前的改进

• ✅ 增强所有操作的类型安全性
• ✅ 实现真正的批量操作，以提升性能
• ✅ 改进错误处理和验证
• ✅ 添加全面的测试覆盖
• ✅ 重构架构以提升可维护性