Linear MCP 服务器

注意：以下内容为完整翻译，不包含任何额外信息。

简介

这是一个基于 TypeScript 和 Model Context Protocol（MCP）协议实现的自定义线性 (Linear) 问题跟踪系统适配器。该服务器允许 AI 代理通过标准输入输出与 Linear 平台交互，支持创建、查询和更新问题、团队及项目等操作。

运行方式

快速入门

1. 获取 API 密钥
   访问 Linear 网站，创建新项目并获取 API 接口密钥。

2. 安装依赖
   使用 Node.js 包管理器安装所需依赖：

   npm install @linear/sdk@37.0.0 @modelcontextprotocol/sdk@0.6.0
   

3. 运行服务器
   在项目根目录下创建 index.ts 文件，添加以下代码并执行：

   import { LinearMCPAdapter } from './src/adapter';
   
   const adapter = new LinearMCPAdapter({
     token: 'your-linear-token',
     projectId: 'your-project-id'
   });
   
   adapter.start();
   

   然后运行：

   npm run dev
   

核心功能

问题管理

• 创建问题
  发送 POST 请求至 /create-issue 接口，支持自定义标题、描述、优先级和指派人。

• 查询问题
  支持通过项目 ID、团队 ID 和状态参数灵活筛选问题，默认返回前50条记录。

• 更新问题
  支持对现有问题的全部字段进行更新操作，包括标题、描述、状态、指派人等。

团队管理

• 获取所有团队
  调用 /list-teams 接口，返回当前工作区下的所有团队信息。

项目管理

• 获取所有项目
  支持通过团队 ID 过滤查询项目列表，默认返回前50个项目。

开发指南

快速开发

在项目根目录执行以下命令启动开发服务器，并开启自动构建功能：

npm run dev

自动重建

使用以下命令保持开发环境的热重载：

npm run watch

调试工具

运行以下命令安装调试工具并启动调试服务器：

npm install -g supergiant
supergiant start

配置指南

在代码中配置

在 index.ts 文件中初始化适配器时，可传递如下参数：

const adapter = new LinearMCPAdapter({
  token: 'your-linear-token',
  projectId: 'your-project-id'
});

在环境变量中配置

在项目根目录创建 .env 文件，添加以下内容：

LINEAR_TOKEN=your-linear-token
LINEAR_PROJECT_ID=your-project-id

工具接口

创建问题

请求参数格式如下：

{
  title: string;    // 必填：问题标题
  description?: string; // 可选：问题描述
  priority?: number;    // 可选：优先级，取值范围0-4
  assignee?: string;   // 可选：指派人ID
  labels?: string[];   // 可选：标签列表
}

查询问题

请求参数格式如下：

{
  assignee?: string;  // 可选：查询指定人的所有问题
  status?: string;    // 可选：按状态过滤（如："open"、"in-progress"等）
  first?: number;     // 可选：限制返回的问题数量，默认为50
}

更新问题

请求参数格式如下：

{
  issueId: string;   // 必填：问题ID
  title?: string;    // 可选：新标题
  description?: string; // 可选：新描述
  status?: string;   // 可选：新状态
  assignee?: string; // 可选：新指派人
  priority?: number; // 可选：新优先级
  labels?: string[]; // 可选：更新标签列表
}

获取问题详情

请求参数格式如下：

{
  issueId: string; // 必填：问题ID
}

技术细节

• 构建工具：使用 TypeScript 和 Node.js 进行开发。
• 依赖管理：
  • Linear SDK 版本：37.0.0
  • MCP SDK 版本：0.6.0
• 通信协议：基于标准输入输出的自定义协议，兼容 Model Context Protocol 标准。

错误处理

所有 API 请求均返回结构化的错误信息，格式如下：

{
  "error": {
    "code": string; // 错误码
    "message": string; // 错误描述
  }
}

示例代码

创建问题示例

在终端中执行以下命令创建新问题：

echo '{
  "title": "测试问题标题",
  "description": "这是一个测试问题，用于验证API功能。",
  "priority": 2,
  "labels": ["bug", "high"]
}' | ./dist/index.js

查询问题示例

查询指定团队的问题列表：

echo '{
  "assignee": "user123",
  "status": "open"
}' | ./dist/index.js

完整代码结构

// src/adapter.ts
export class LinearMCPAdapter {
  private token: string;
  private projectId: string;

  constructor(options: {
    token: string;
    projectId: string;
  }) {
    this.token = options.token;
    this.projectId = options.projectId;
  }

  public async createIssue(issue: CreateIssueParams): Promise<void> {
    // 实现创建问题的具体逻辑
  }

  public async getIssues(filter?: GetIssuesFilter): Promise<Issue[]> {
    // 实现获取问题列表的逻辑
  }

  public async updateIssue(id: string, updates: UpdateIssueParams): Promise<void> {
    // 实现更新问题的逻辑
  }

  public async getIssue(id: string): Promise<Issue | null> {
    // 实现获取单个问题详情的逻辑
  }
}

其他注意事项

• 所有 API 请求均支持 JSON 格式的请求体。
• 确保在生产环境使用 HTTPS 协议进行通信。
• 建议在敏感操作中添加适当的错误处理机制。

项目贡献

欢迎 fork 和提交 Pull Request，共同完善此适配器的功能。