Linear

Linear との対話には 2 つの経路がある:

1. Linear MCP サーバー — mcp__linear__* 系の高レベルツール（list_issues、get_issue、save_comment など）。通常はこちらを優先する。
2. linear_graphql クライアントツール — Symphony の app-server セッションが公開する生の GraphQL クライアント。MCP に存在しない操作（ファイルアップロード、イントロスペクション、新しい mutation の試行）に使う。

どちらも利用できない場合は停止し、ユーザーに Linear の設定を依頼する。

ツール選択ルール

以下の順で経路を選ぶ:

1. MCP に対応するツールがあれば MCP を使う（issue/コメント/プロジェクト/チームの CRUD はほぼ MCP でカバーされる）。
2. MCP に対応する操作がない、または下記の限定ケースでは linear_graphql を使う:
   • ファイル／動画アップロード（fileUpload mutation）
   • スキーマイントロスペクション（__type クエリ）
   • MCP がまだサポートしていない新しい／未知の mutation
   • レアな input 型のフィールド構造を確認する必要があるとき

MCP の使用上の注意

• 文字列値を渡すときは、エスケープシーケンスを含めず内容をそのまま送る。たとえば markdown 本文の改行はリテラル \n ではなく実際の改行を使う。
• 1 回のツール呼び出しにつき 1 つの操作を行う。
• 必要なフィールド／引数のみを渡し、不要な更新を避ける。

linear_graphql の使用上の注意

ツール入力:

{
  "query": "query or mutation document",
  "variables": {
    "optional": "graphql variables object"
  }
}

挙動:

• 1 回のツール呼び出しにつき 1 つの GraphQL オペレーションを送る。
• ツール呼び出し自体は完了していても、トップレベルの errors 配列がある場合は失敗した GraphQL オペレーションとして扱う。
• query/mutation は狭くスコープし、必要なフィールドのみを要求する。

一般的なワークフロー

各ワークフローで、MCP 経路を優先し、linear_graphql 経路はフォールバックとして示す。

key・identifier・id で issue をクエリする

ルックアップは段階的に使う: key -> identifier 検索 -> 内部 id。

MCP 経路:

• チケットキー（例: MT-686）から取得: mcp__linear__get_issue に id: "MT-686" を渡す（識別子も受け付ける）。
• フィルタ検索: mcp__linear__list_issues を使って team、project、assignee、state、label、createdAt などで絞り込む。
• issue の詳細／添付／コメントが必要なら、get_issue の応答や個別 API（list_comments、get_attachment）を組み合わせる。

linear_graphql フォールバック:

issue キーで検索:

query IssueByKey($key: String!) {
  issue(id: $key) {
    id
    identifier
    title
    state {
      id
      name
      type
    }
    project {
      id
      name
    }
    branchName
    url
    description
    updatedAt
    links {
      nodes {
        id
        url
        title
      }
    }
  }
}

identifier フィルタで検索:

query IssueByIdentifier($identifier: String!) {
  issues(filter: { identifier: { eq: $identifier } }, first: 1) {
    nodes {
      id
      identifier
      title
      state {
        id
        name
        type
      }
      project {
        id
        name
      }
      branchName
      url
      description
      updatedAt
    }
  }
}

内部 id がわかったら issue を読む:

query IssueDetails($id: String!) {
  issue(id: $id) {
    id
    identifier
    title
    url
    description
    state {
      id
      name
      type
    }
    project {
      id
      name
    }
    attachments {
      nodes {
        id
        title
        url
        sourceType
      }
    }
  }
}

issue のチームのワークフロー状態をクエリする

issue 状態を変更する前に、正確な状態 ID／名前が必要なときに使う。

MCP 経路:

• mcp__linear__get_issue で team 情報を取得し、mcp__linear__list_issue_statuses にその teamId を渡してそのチームのワークフロー状態一覧を得る。
• 個別の状態を取りたい場合は mcp__linear__get_issue_status。

linear_graphql フォールバック:

query IssueTeamStates($id: String!) {
  issue(id: $id) {
    id
    team {
      id
      key
      name
      states {
        nodes {
          id
          name
          type
        }
      }
    }
  }
}

コメントを作成する

MCP 経路:

• mcp__linear__save_comment を使う。issueId と body を渡す。
• スレッドへの返信は parentId を指定する。
• 本文の改行はそのまま実改行で記述する（リテラル \n を書かない）。

linear_graphql フォールバック:

mutation CreateComment($issueId: String!, $body: String!) {
  commentCreate(input: { issueId: $issueId, body: $body }) {
    success
    comment {
      id
      url
    }
  }
}

既存のコメントを編集する

MCP 経路:

• mcp__linear__save_comment に id を含めて呼ぶと既存コメントの更新になる（同じ "save" API で create/update を兼ねる）。

linear_graphql フォールバック:

mutation UpdateComment($id: String!, $body: String!) {
  commentUpdate(id: $id, input: { body: $body }) {
    success
    comment {
      id
      body
    }
  }
}

issue を別の状態に移動する

MCP 経路:

1. mcp__linear__get_issue でチームを特定する。
2. mcp__linear__list_issue_statuses で目的の状態 ID を取得する。
3. mcp__linear__save_issue に id と stateId（または対応するフィールド）を渡して更新する。

linear_graphql フォールバック:

mutation MoveIssueToState($id: String!, $stateId: String!) {
  issueUpdate(id: $id, input: { stateId: $stateId }) {
    success
    issue {
      id
      identifier
      state {
        id
        name
      }
    }
  }
}

GitHub PR を issue にアタッチする

MCP 経路:

• mcp__linear__create_attachment に issueId、url、title を渡す。
• GitHub PR 用のリッチなプレビュー（PR の状態など）が必要で MCP がそれをサポートしない場合のみ、フォールバックの attachmentLinkGitHubPR を使う。

linear_graphql フォールバック:

GitHub 固有のリンクメタデータが欲しい場合:

mutation AttachGitHubPR($issueId: String!, $url: String!, $title: String) {
  attachmentLinkGitHubPR(
    issueId: $issueId
    url: $url
    title: $title
    linkKind: links
  ) {
    success
    attachment {
      id
      title
      url
    }
  }
}

プレーンな URL アタッチメントで足りる場合:

mutation AttachURL($issueId: String!, $url: String!, $title: String) {
  attachmentLinkURL(issueId: $issueId, url: $url, title: $title) {
    success
    attachment {
      id
      title
      url
    }
  }
}

コメントに動画／ファイルをアップロードする

MCP には現状アップロード API がない。linear_graphql 経路を使う。

3 ステップで行う:

1. linear_graphql を fileUpload で呼び出して、uploadUrl、assetUrl、必要なアップロードヘッダーを取得する。
2. ローカルファイルのバイトを curl -X PUT と fileUpload から返された正確なヘッダーで uploadUrl にアップロードする。
3. 再び操作する: mcp__linear__save_comment（または linear_graphql の commentCreate／commentUpdate）を呼び、結果の assetUrl をコメント本文に埋め込む。

mutation FileUpload(
  $filename: String!
  $contentType: String!
  $size: Int!
  $makePublic: Boolean
) {
  fileUpload(
    filename: $filename
    contentType: $contentType
    size: $size
    makePublic: $makePublic
  ) {
    success
    uploadFile {
      uploadUrl
      assetUrl
      headers {
        key
        value
      }
    }
  }
}

不慣れなオペレーション／スキーマの探索

MCP では露出していない mutation・input 型・object フィールドが必要なときは、linear_graphql 経由でターゲットされたイントロスペクションを使う。

mutation 名一覧:

query ListMutations {
  __type(name: "Mutation") {
    fields {
      name
    }
  }
}

特定の input オブジェクトを調査:

query CommentCreateInputShape {
  __type(name: "CommentCreateInput") {
    inputFields {
      name
      type {
        kind
        name
        ofType {
          kind
          name
        }
      }
    }
  }
}

query QueryFields {
  __type(name: "Query") {
    fields {
      name
    }
  }
}

query IssueFieldArgs {
  __type(name: "Query") {
    fields {
      name
      args {
        name
        type {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
            }
          }
        }
      }
    }
  }
}

使用ルール

• 通常の CRUD（issue／コメント／プロジェクト／チーム／ステータス／添付）は MCP を優先する。
• アップロード、イントロスペクション、未対応の mutation には linear_graphql を使う。
• 既知の情報に合わせて最も狭い issue ルックアップを優先する: key -> identifier 検索 -> 内部 id。
• 状態遷移では、まずチームの状態を取得し、ID を文字列リテラルでハードコードしない。
• GitHub PR を Linear issue にリンクするときは、リッチなプレビューが必要なら attachmentLinkGitHubPR を、それ以外は MCP の create_attachment を優先する。
• GraphQL アクセス用の新しい raw-token シェルヘルパーを導入しない。
• アップロード用のシェル作業は fileUpload から返された署名済みアップロード URL にのみ使用する。これらの URL は既に必要な認可情報を持っている。
• MCP のツールに文字列を渡すときは、エスケープシーケンスを書かずそのまま渡す（実改行を含む markdown など）。