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