Linear MCP Server

Linear MCP Server

Cline を通じて Linear の課題、プロジェクト、チームを管理するためのツールを提供する、Linear の API と連携する MCP サーバーです。

セットアップガイド

1. 環境のセットアップ

1. リポジトリをクローンします
2. 依存関係をインストールします：

   npm install
   

3. .env.example を .env にコピーします：

   cp .env.example .env
   

2. 認証

このサーバーは、次の 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 では、説明に 2 つのフィールドを使用します：

1. description - 従来のフィールド（後方互換性のため、空の場合がよくあります）
2. documentContent.content - 実際のリッチテキスト形式の説明内容を含みます

MCP サーバーは自動的に次の処理を行います：

• Linear の API から両方のフィールドを取得します
• 従来の description フィールドよりも documentContent.content を優先します
• 一貫してアクセスするためのユーティリティ関数 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 利用者との後方互換性を維持

これまでの改善

• ✅ すべての操作で型安全性を強化
• ✅ パフォーマンス向上のため、真のバッチ操作を実装
• ✅ エラー処理と検証を改善
• ✅ 包括的なテストカバレッジを追加
• ✅ 保守性向上のため、アーキテクチャをリファクタリング