Linear Project

Linear Project MCP サーバー

Linear のプロジェクトワークフローを管理する、スコープで制限された Model Context Protocol サーバーです。オプションで読み取り専用の GitHub エビデンスと、ローカルの Obsidian ノートアダプターを利用できます。

このサーバーは、このリポジトリにある 3 つのスキルを補完します。既存のコネクターではチームの作成、厳密なスコープラベルの適用、安全なローカルエビデンスのリンクができない場合に、それらのワークフローに必要な連携機能を提供します。

対応内容

Linear の構成	プロジェクトスコープ	イシュー識別子の動作
既存のチーム	正確なプロジェクトに加え、ACQI のイシューラベルとプロジェクトラベル	OPEN-42 のような既存のチームキーを維持します
キーが ACQI の新しい専用チーム	正確なプロジェクトに加え、ACQI ラベル	チームが空であることを確認できた場合に限り、ACQI-1 から開始します
既存の親チーム配下に新設する ACQI サブチーム	正確なプロジェクトに加え、ACQI ラベル	サブチームが空であることを確認できた場合に限り、ACQI-1 から開始します

Linear の識別子はチームに属し、プロジェクトやラベルには属しません。サーバーは、プロジェクト、ラベル、ノート、イシューを作成する前に、既存の OPEN チームで ACQI-1 を想定するリクエストを拒否します。最初の識別子の読み戻しは即時の安全確認であり、同時実行ロックではありません。最初のイシューを初期設定する間は、複数の書き込みを同時に行わないでください。

過去の記録は進行中の作業とは分けて管理されます。過去の記録には、正確な [HISTORICAL] のタイトル接頭辞、スコープラベルと HISTORICAL ラベル、Historical only: true、Actionability: none、および再実行時の安全性を確保する決定論的なソースマーカーが付与されます。

ツール

ツール	モード	用途
linear_project_capabilities	読み取り	アダプター、到達可能性、許可リスト、書き込み状態を報告します
linear_project_resolve_scope	読み取り	正確なチーム／プロジェクト／ラベルのスコープを解決します
linear_project_create_team	書き込み	スコープキーを持つ専用チームまたはサブチームを作成、または再利用します
linear_project_bootstrap	書き込み	チーム、プロジェクト、ラベル、オプションのリンク、最初のイシューを作成、または再利用します
linear_project_list_scoped_issues	読み取り	スコープラベルが付いた、正確なプロジェクト内のイシューのみを一覧表示します
linear_project_upsert_scoped_issue	書き込み	進行中または過去の作業を冪等に作成、または更新します
linear_project_find_candidates	読み取り	移動はせず、許可リストに登録された照合候補を検索します
linear_project_move_candidate	書き込み	審査済みの候補を、正確な移動元の状態と識別子の保護条件を適用して移動します
linear_project_link_evidence	書き込み	検証済みの GitHub または Obsidian リンクを、スコープ内のイシューに追加します
github_get_project_evidence	読み取り	許可リストに登録されたリポジトリ、コミット、PR、またはイシューを正規化します
obsidian_search_project_notes	読み取り	許可リストに登録されたローカルの Markdown ノートを検索します
obsidian_read_project_note	読み取り	許可リストに登録されたローカルの Markdown ノートを 1 つ読み取ります
obsidian_upsert_project_note	書き込み	ノート内のサーバー管理セクションのみを置き換えます

すべてのツールは、厳密な入力スキーマと構造化出力を使用します。変更を伴うツールでは、確認フィールドに文字列リテラルが必要です。また、グローバルな書き込みも有効にする必要があります。

インストールとビルド

必要条件：Node.js 20 以降、および pnpm 10。pnpm 11 では Node.js 22 以降が必要で、Node.js 20 との互換性下限は検証できません。

pnpm install --frozen-lockfile
cp .env.example .env
pnpm check
pnpm build

npm パッケージ名は @openly-useful/linear-project-mcp-server です。これをインストールすると、プロトコルサーバー linear-project-mcp-server と、範囲が制限された安全性ヘルパー linear-project-mcp-write-window がインストールされます。最初の npm リリースが成功した後でのみ、npx @openly-useful/linear-project-mcp-server で実行できます。それまでは、以下に示すように、ソースをチェックアウトしてビルドおよび実行してください。

公式 MCP Registry 名は org.openlyuseful/linear-project です。server.json、package.json.mcpName、npm パッケージのバージョン、Registry パッケージのバージョンは一致している必要があります。リポジトリ内の Openly Useful パブリッシャープロジェクションには、LLC の設立が完了するまで有効な、創業者個人が現在の運営者であること、および創業者兼所有者の承認が記録されています。prepublishOnly は、その承認に加えて、正確な npm ID、ポリシー、名前空間、リポジトリの来歴、登録メタデータを検証します。プロバイダー認証とレビューは MCP Registry の別の手順です。ビルド、テスト、検証、pnpm pack --dry-run ではレコードは公開されません。

設定

.env.example をコピーし、必要なアダプターのみを設定してください。

Linear では LINEAR_API_KEY または LINEAR_ACCESS_TOKEN のいずれかを使用できます。スコープが指定された Linear の読み取りと変更には、正確な LINEAR_ALLOWED_ORGANIZATION_ID が必要です。すべての変更には、さらに以下が必要です。

• MCP_WRITES_ENABLED=true；
• 60 分以内に期限を迎える、未来の MCP_WRITE_WINDOW_EXPIRES_AT；
• バンドルされた書き込みウィンドウヘルパーを使用する場合は、安全で書き込み可能な MCP_AUDIT_LOG_PATH；
• ACQI など、LINEAR_ALLOWED_SCOPE_CODES に指定された正確なコード；
• スコープコードとキーが完全に一致する専用チームでない場合は、LINEAR_ALLOWED_TEAM_IDS に指定された移行先チームの ID；
• 任意の許可リストが空でない場合は、LINEAR_ALLOWED_PROJECT_IDS に指定されたプロジェクト ID；
• 変更を行うツールの確認フィールドに、リテラル値 true が設定されていること。

新しい ACQI サブチームを作成するには、親チーム ID を許可リストに追加し、team_mode: "subteam" を選択して parent_team_id を渡し、team_key: "ACQI" を使用してください。認証された Linear の ID には、ワークスペース内でチームを作成する権限が必要です。

新しいプロジェクトの ID はまだ存在しないため、最初のプロジェクトのブートストラップ時に限り、LINEAR_ALLOWED_PROJECT_IDS を空のままにしてください。読み取り確認後、継続的な運用の前に、その正確な ID を追加してください。プロジェクト ID の許可リストが空でない場合、既存のプロジェクトはあらかじめ許可リストに追加されている必要があります。また、スコープが指定されたすべての操作には、正確なスコーププロジェクトラベルが必要です。

GitHub は任意です。GITHUB_TOKEN と、正確な owner/name 形式のエントリーを GITHUB_ALLOWED_REPOSITORIES に設定してください。アダプターが行うのは GET リクエストのみです。調査する予定の参照に必要な、メタデータとコンテンツ、プルリクエスト、または Issue への読み取り専用アクセス権を持つ、きめ細かなトークンを使用してください。

Obsidian は任意で、ローカル環境のみで動作します。OBSIDIAN_VAULT_PATH は絶対パスである必要があり、OBSIDIAN_ALLOWED_DIRECTORIES には Vault からの相対ディレクトリを指定します。OBSIDIAN_VAULT_NAME を設定すると、obsidian:// リンクを使用できます。アクセスできるのは、指定したディレクトリ配下の .md ファイルのみです。パストラバーサル、シンボリックリンク、Markdown 以外のパス、200,000 バイトを超えるファイルは拒否されます。ノートを Linear にリンクする際に送信されるのは Obsidian URI とタイトルのみで、内容は送信されません。

操作の監査を行うには、MCP_AUDIT_LOG_PATH に正規化された絶対パスを設定し、リポジトリの外部を指定してください。その親ディレクトリはすでに存在し、現在のユーザーが所有していて、グループまたはその他のユーザーに書き込み権限が付与されていない必要があります。サーバーは、操作 ID、ツール名、モード、所要時間、結果、安全なエラー分類を含む簡潔な NDJSON の試行／結果レコードを追記します。ツール引数、結果本文、説明、認証情報、エラーメッセージは記録されません。監査が設定されている場合、監査先が利用できないと、ワークフローの実行前に書き込みがブロックされ、読み取りは監査機能が低下した状態として記録されます。

Codex に接続する

Codex の登録エイリアスとして linear_project を使用します。このエイリアスはローカルクライアントの設定キーであり、npm パッケージ名および実行ファイル名とは意図的に異なります。

ソースチェックアウトのサーバーディレクトリから：

pnpm install --frozen-lockfile
pnpm build
MCP_ENTRYPOINT="$(pwd)/dist/index.js"
codex mcp add linear_project -- node "$MCP_ENTRYPOINT"
codex mcp get linear_project --json
codex mcp list --json

最初の npm リリースが利用可能になった後は、バージョンを固定したレジストリインストールを次のように登録することもできます：

codex mcp add linear_project -- npx --yes @openly-useful/[email protected]
codex mcp get linear_project --json
codex mcp list --json

API トークンを codex mcp add --env で追加しないでください。指定した値がローカルの Codex 設定に保存されます。認証情報を子プロセスにのみ渡す、保護されたランチャーまたはオペレーティングシステムのシークレットストアを使用してください。秘密情報ではない許可リスト設定はクライアント設定に保存できますが、実際の組織、チーム、プロジェクト、リポジトリ、または Vault の値をリポジトリに含めてはなりません。

登録後、現在のタスクでツールレジストリが更新されない場合は、新しい Codex タスクを開始してください。その新しいタスクで：

1. linear_project ツールが表示されることを確認します。
2. linear_project_capabilities を呼び出し、writesEnabled が false であること、Linear に到達できること、組織が許可されていることを確認します。
3. 対象のスコープコードについて linear_project_resolve_scope を呼び出し、チーム、プロジェクト、課題ラベル、プロジェクトラベルがそれぞれ正しく解決されることを確認します。

トラブルシューティングでは、パッケージ名を区別してください：

名前	用途
linear_project	codex mcp add、codex mcp get、codex mcp list で使用する登録エイリアスです。
@openly-useful/linear-project-mcp-server	npx およびパッケージマネージャーで使用する npm パッケージ指定子です。
org.openlyuseful/linear-project	公式 MCP Registry サーバー名および npm の mcpName です。
linear-project-mcp-server	インストールされる実行ファイルおよび MCP プロトコルサーバーの成果物名です。
linear-project-mcp-write-window	書き込みウィンドウ設定を範囲限定して明示的に変更するための、インストール済みヘルパーです。

別の MCP クライアントに接続する

サーバーをビルドし、クライアントでローカルの stdio プロセスを設定します。正確な設定キーはクライアントによって異なりますが、一般的な形式は次のとおりです：

{
  "mcpServers": {
    "linear_project": {
      "command": "/path/to/protected/linear-project-mcp-launcher",
      "args": []
    }
  }
}

保護されたランチャーは、クライアントのシークレットストアまたは保護されたプロセス環境から認証情報を読み込み、その後、自身を linear-project-mcp-server プロセスに置き換える必要があります。ランチャー、.env、またはシークレットを含むクライアント設定をコミットしないでください。

推奨される運用手順

1. 書き込みを無効にした状態で開始し、linear_project_capabilities を呼び出します。
2. 読み取り専用ツールを使って、正確な宛先を特定または確認します。
3. 組織、チーム、プロジェクト、スコープ、リポジトリ、ノートディレクトリの許可リストを、必要最小限の範囲に設定します。
4. 対象の操作に限って書き込みを有効にします。
5. 決定的なソースマーカーを使って、初期化またはアップサートします。
6. 結果を読み戻して操作を再実行します。完了済みのインポートでは、追加レコードがゼロ件になる必要があります。
7. 書き込みを再び無効にします。

設定はサーバープロセスの起動時に読み込まれます。そのため、MCP_WRITES_ENABLED の有効化または無効化後、機能の確認や書き込みの実行を行う前に、該当する MCP クライアントセッションへの再接続または再起動が必要です。安全な書き込みウィンドウは次のとおりです。

1. 書き込みを無効にした状態で、正確なスコープを特定して確認します。
2. 接続中のサーバープロセスを停止し、保護されたランタイム環境に対して制限付きヘルパーを使用してから、再接続します。
3. linear_project_capabilities を呼び出し、明示的に確認した変更を1件行う前に、想定される書き込み状態と許可リストを確認します。
4. 変更したレコードを読み戻し、同じ決定的な操作を再実行します。再実行の結果は、追加変更ゼロ件でなければなりません。
5. サーバープロセスを停止し、ヘルパーでウィンドウを無効にしてから再接続し、linear_project_capabilities で無効状態を確認します。

スコープの読み戻し、再実行、または無効状態の確認に失敗した場合は、処理を停止し、書き込みを無効のままにしてください。

ヘルパーで指定できるウィンドウは1～60分です。有効化にはスコープコードを2回入力する必要があります。また、空でない組織、チーム、プロジェクト、スコープの許可リストと、MCP_AUDIT_LOG_PATH が必要です。ヘルパーがウィンドウを暗黙的に延長することはありません。リポジトリの外部にある保護された環境ファイルを使用してください。

linear-project-mcp-write-window status --env-file /path/to/protected.env
linear-project-mcp-write-window enable --env-file /path/to/protected.env --scope ACQI --minutes 15 --confirm ACQI
# Reconnect or restart the MCP client, verify capabilities, perform one scoped operation, read back, and replay.
linear-project-mcp-write-window disable --env-file /path/to/protected.env
# Reconnect or restart again, then verify writesEnabled is false.

enable は MCP_WRITES_ENABLED=true と、制限時間を設けた RFC 3339 形式の MCP_WRITE_WINDOW_EXPIRES_AT を書き込みます。disable は MCP_WRITES_ENABLED=false に戻し、有効期限を消去します。設定を変更するたびに、サーバープロセスへの再接続または再起動が必要です。有効期限はフェイルクローズを実現する追加の制限であり、操作後に無効化して再接続することの代わりにはなりません。

このサーバーはデーモンを実行せず、ファイルを監視せず、調整対象の候補を自動的に移動せず、リポジトリの証拠だけを根拠に Issue を完了済みにしません。別個の移動ツールを使うには、正確な移動元の状態を入力し、明示的に確認する必要があります。チームをまたぐ移動では、識別子の変更と移動元ラベルの置換についても確認が必要です。継続的な更新は、MCP クライアントがツールを明示的に呼び出した場合にのみ行われます。

トランスポートとデプロイ

現行リリースがサポートするのはローカル stdio です。これは、ローカルの保管庫を読み取る Obsidian アダプターの意図的な仕様です。将来リモートにデプロイする場合は、MCP SDK の Streamable HTTP トランスポートを使用し、ローカルファイルシステムへのアクセスを省き、サーバー側の認証を追加したうえで、同じ許可リストと確認ゲートを維持してください。

開発

pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

テストでは、メモリ内の Linear および MCP トランスポートと、一時的な Obsidian フィクスチャを使用します。実稼働サービスには接続しません。読み取り専用の評価に関する質問は、evaluations/read-only.xml にあります。

実装の参考資料：MCP TypeScript SDK v2、Linear TypeScript SDK、Linear teams、GitHub REST authentication、Obsidian URI。

ライセンス

MIT