youtrack-agent-mcp

English | 日本語

エージェントから YouTrack を操作するための MCP サーバーです。イシューの作成・更新、ステートマシンに沿ったステート遷移、コメント、検索、添付ファイルやナレッジベース記事の管理まで対応しており、いずれも YouTrack REST API を経由します。

プロジェクトのワークフローはハードコードしていません。イシューのタイプ、カスタムフィールド、ステート遷移はいずれも実行時に YouTrack から読み取るので、YouTrack インスタンスの設定に合わせてそのまま動作します。ツール名はすべて yt_ で始まります。

動作環境

• Node.js 20 以降
• イシュー・コメント・記事の読み書きができる YouTrack のパーミッショントークン
• インスタンスの URL（例: https://example.youtrack.cloud）

インストール

npm install
npm run build

設定

サーバーは 2 つの環境変数を参照します。

export YOUTRACK_URL="https://example.youtrack.cloud"
export YOUTRACK_TOKEN="perm:xxxxxxxxxxxx"

MCP クライアント（Claude Code、Codex など）には stdio 経由で登録します。

{
  "mcpServers": {
    "youtrack": {
      "command": "node",
      "args": ["/path/to/youtrack-agent-mcp/dist/index.js"],
      "env": {
        "YOUTRACK_URL": "https://example.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:xxxxxxxxxxxx"
      }
    }
  }
}

ツール

issueId には、読みやすい id（PRJ-15）と内部 id（3-15）のどちらも使えます。

| ツール | 内容 | | --- | --- | | yt_create_issue | イシューを作成します。type、カスタム fields、tags、parentIssueId、dependencies は任意です。 | | yt_get_issue | イシューを取得します。フィールドや実行可能な遷移に加え、コメントやリンクも取得できます。 | | yt_update_issue | サマリー、説明、タグ、カスタムフィールドを変更します。 | | yt_transition_issue | イシューをステートマシンに沿って遷移させます。引き継ぎ用のコメントも添えられます。 | | yt_get_available_transitions | 現在のステートから実行できる遷移の一覧を返します。 | | yt_add_comment | コメントを追加します。 | | yt_set_comment_reaction | コメントにリアクションを付けます。 | | yt_apply_command | YouTrack のコマンドをそのまま実行します。他のツールで扱えない単発のフィールド編集・リンク・一括編集に使います。 | | yt_search_issues | YouTrack クエリでイシューを検索します。 | | yt_search_articles | ナレッジベースの記事を検索します。 | | yt_get_article / yt_create_article | ナレッジベースの記事を取得または作成します。 | | yt_list_attachments / yt_upload_attachment / yt_download_attachment | 添付ファイルを管理します。 | | yt_list_projects | トークンでアクセスできるプロジェクトの一覧を返します。 | | yt_get_me | 現在のユーザーと所属グループを返します。 |

ステート遷移

ステートの変更はステートマシンを通ります。まず何が許可されているかを問い合わせてから適用してください。

yt_get_available_transitions({ issueId: "PRJ-42" })
// -> State: In Progress, transitions: ["Fix", "Won't fix"]

yt_transition_issue({ issueId: "PRJ-42", transition: "Fix" })

ステートマシンのフィールドが複数あるイシューでは、field でどのフィールドを対象にするか指定します。現在のステートから実行できない遷移は YouTrack 側で拒否されます。

遷移と一緒にメモを送る

遷移にメモが必要なときは、コメントを別途投稿するのではなく handoffMessage として渡します。こうすると、コメントとステートの変更が 1 つの引き継ぎとしてまとめて記録されます。

yt_transition_issue({
  issueId: "PRJ-42",
  transition: "Fix",
  handoffMessage: "Root cause was a stale cache key. Fixed in the last commit."
})

画像を添付する

YouTrack はコメント本文にバイト列を持たせられないため、ファイルは単独でアップロードして名前で参照します。先にアップロードしてから、引き継ぎのメモに埋め込んでください。

yt_upload_attachment({ issueId: "PRJ-42", filePath: "/abs/path/before-after.png" })
// -> { name: "before-after.png", ... }

yt_transition_issue({
  issueId: "PRJ-42",
  transition: "Fix",
  handoffMessage: "Verified, see the diff:\n\n![before/after](before-after.png)"
})

順番が大事です。![](name) の参照はアップロード済みの添付ファイルに対して解決されるので、先にアップロードを済ませておく必要があります。画像を複数含めるときは、ファイルごとにアップロードして、それぞれ名前で参照してください。

フィールドの設定

yt_create_issue と yt_update_issue は、カスタムフィールド用に fields マップを受け取ります。

yt_update_issue({ issueId: "PRJ-42", fields: { Priority: "Critical", Assignee: "jane" } })

専用ツールで扱えない操作（イシューのリンク、タグ付け、一括編集など）には、YouTrack のコマンド構文を使う yt_apply_command を使います。

yt_apply_command({ issueId: "PRJ-42", command: "tag regression Assignee me" })

開発

npm run dev     # run from source
npm run build   # compile to dist/
npm run check   # type-check
npm test        # run tests

リリース

バージョンタグを push すると、GitHub Actions がパッケージを npm に公開します。

npm version patch      # bumps package.json and creates a v* tag
git push --follow-tags

.github/workflows/release.yml のワークフローが、タグ付けされたバージョンをビルド・テストして公開します。公開には OIDC 経由の npm trusted publishing を使います。リポジトリをパッケージの trusted publisher として登録しておけば、管理すべきトークンはありません。トークンで公開したい場合は、NPM_TOKEN シークレットを追加すれば同じワークフローがそれを利用します。

ライセンス

MIT