Linear MCP Server

🚀 线性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标准。

💻 使用示例

基础用法

创建问题示例

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

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，共同完善此适配器的功能。