YouTrack (ymcp)

ymcp は、VPN の背後にあるセルフホスト型インスタンスを含む、YouTrack でのプロジェクト作業向けローカルツールチェーンです。2 つの要素で構成されています。あらゆる AI クライアント向けの MCP サーバーと、課題をコーディングエージェントに渡すパイプラインです。

MCP サーバーは、ログイン名とパスワードを使ってあなたに代わって通信し、YouTrack 組み込みの MCP サーバーが提供するすべてのツールを同じ名前で備えています。さらに、組み込みサーバーにない、削除、スプリント、添付ファイル、履歴、作業時間レポート、コマンドなどの機能も追加します。

• 58 個のツール：組み込みの 23 個は名前、引数、制限が同じで、さらに 35 個を追加
• ログイン名とパスワードだけで利用可能：YouTrack 側での設定、ウェブフック、OAuth クライアント、API キーは不要です。パスワードはシステムのキーチェーンに保存されます
• 管理者権限なしで動作：フィールドスキーマ、グループ、コメントは、一般ユーザーが読み取れる情報にフォールバックします
• 1 つのコマンドでインストール：Claude、Cursor、VS Code、Zed、Codex、Gemini など、ほか 8 つのクライアントにも自動で登録します
• macOS、Linux、Windows 向けの単一の静的バイナリ。ymcp update が組み込まれています

パイプラインは、YouTrack の検索で見つかった課題を受け取り、それぞれを独自のブランチでコーディングエージェントに割り当てます。

• Claude Code、Kimi、opencode、または任意の ACP エージェントが、サーバーと同じ YouTrack ツールを使用します
• ブランチ、GitHub プルリクエスト、GitLab マージリクエストに対応し、エージェントはレビューコメントにも回答します
• エージェントに質問がある場合や権限を求める場合は、システム通知とともに入力待ちになります
• パイプラインごとのボードを備えたTUI、またはスクリプト向けのシンプルなコマンドを利用できます

インストール

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/xlsft/ymcp/main/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/xlsft/ymcp/main/install.ps1 | iex

または、パッケージマネージャーでインストールしてから、ymcp setup を実行します。

brew install xlsft/tap/ymcp                                                  # macOS, Linux
scoop bucket add xlsft https://github.com/xlsft/scoop-bucket; scoop install ymcp   # Windows

パッケージマネージャーで管理されるコピーは、各マネージャーを通じて更新してください（brew upgrade ymcp など）。ymcp update を実行すると、その旨が表示されます。

インストーラーは最新リリースをダウンロードし、SHA-256 を検証します。次に ymcp setup を実行し、以下の操作を行います。

1. プロファイル名を尋ねます。デフォルトは youtrack です。
2. YouTrack の URL、ログイン名、パスワードを尋ね、保存する前に認証情報を検証します。
3. マシン上で見つかった MCP クライアントを一覧表示し、それぞれにチェックボックスを表示します。
4. 選択したクライアントに ymcp を stdio サーバーとして登録し、チェックを外したクライアントからは削除します。

いつでも ymcp setup を再度実行して、プロファイルの編集、クライアントの追加や削除、または別の YouTrack の追加ができます。

ymcp のセットアップを代行するエージェント（Cline など）向けの手順は、llms-install.md に記載されています。

複数の YouTrack インスタンス

各 YouTrack インスタンスはプロファイルであり、各プロファイルはそれぞれ独立した MCP サーバーです。プロファイルの表示名がサーバー名になります。YouTrack (work) は youtrack-work になり、youtrack-acme はそのままです。ymcp setup を再度実行するとプロファイルが一覧表示されます。プロファイルを選んで編集したり、名前を変更したり（対応するクライアントの設定も引き継がれます）、プロファイルを追加または削除したりできます。クライアントは ymcp --profile <key> を実行するため、各インスタンスはそれぞれ独自のツールとともに並んで表示されます。

リリースを検証する

このリポジトリのリリースワークフローでは、Sigstore を使って鍵なしでリリースに署名しています。checksums.txt には checksums.txt.sigstore.json バンドルがあり、各アーカイブには SPDX SBOM（*.sbom.json）があります。

cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/xlsft/ymcp/\.github/workflows/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c checksums.txt

各リリースには、checksums.txt 内のすべてのファイルを対象とした SLSA ビルド来歴も含まれており、GitHub に保存され、ymcp.intoto.jsonl として添付されています。

gh attestation verify ymcp_linux_amd64.tar.gz --repo xlsft/ymcp

Docker イメージにも同じ方法で署名し、SBOM と来歴のアテステーションを付与しています。

cosign verify xlsoftware/ymcp:latest \
  --certificate-identity-regexp '^https://github.com/xlsft/ymcp/\.github/workflows/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

コマンド

docs/reference.md には完全なリファレンスがあり、すべてのコマンド、各ツールとプロンプトの入出力、パイプラインファイルの各フィールドが記載されています。

コマンド
ymcp / ymcp serve	stdio 経由で MCP サーバーを実行します（クライアントが起動するコマンドです）。--transport http は Streamable HTTP を提供します。HTTP を参照してください
ymcp setup	プロファイルを追加または編集し、サインインして、使用するツールと MCP クライアントを選択します。--name、--tools、--clients cursor,zed、--all、--reauth、--remove を指定すると、質問への回答を省略できます
ymcp auth	プロファイルの URL、ログイン名、パスワードを設定または変更します。スクリプトでは --url、--login、--proxy、--password-stdin を使用できます
ymcp check	サインインして、ユーザー情報を表示します
ymcp call <tool> '<json>'	クライアントとまったく同じように、1 つのツールを呼び出します。例：ymcp call count_issues '{"query":"#Unresolved"}'
ymcp health	起動中の HTTP サーバーが応答するか確認します（--url のデフォルトは http://127.0.0.1:8090）
ymcp logs	サーバーの動作を表示します。-f はログをリアルタイムで追跡し、-n 200 は表示する行数を増やします
ymcp pipeline	パイプラインの TUI を開きます。ymcp pipeline --help には new、run、check、answer などが一覧表示されます。パイプライン を参照してください
ymcp update	バイナリを最新リリースに置き換えます（--check は確認のみを行います）
ymcp version	バージョンを表示します

ツール

組み込みの YouTrack MCP ツールセット

分野	ツール
課題	search_issues、get_issue、create_issue、create_draft_issue、update_issue、change_issue_assignee、get_issue_fields_schema
コメント、タグ、リンク、時間	add_issue_comment、get_issue_comments、manage_issue_tags、link_issues、log_work、get_saved_issue_searches
ナレッジベース	search_articles、get_article、create_article、update_article
プロジェクトとユーザー	find_projects、get_project、find_user、get_current_user、find_user_groups、get_user_group_members

カスタムフィールドは表示名で設定します。例：{"State": "In Progress", "Fix versions": ["2.1"]}。ymcp はフィールドの型を調べ、送信前にプロジェクトに照らして値を検証します。許可されている担当者も検証されるため、値が正しくない場合は有効な候補の一覧が返されます。

その他

領域	ツール
削除と取り消し	delete_issue、delete_issue_comment、restore_issue_comment、delete_article、delete_work_item、unlink_issues
アジャイルボードとスプリント	find_agile_boards、get_agile_board、get_sprint、create_sprint、update_sprint、add_issue_to_sprint、remove_issue_from_sprint、delete_sprint
履歴とレポート	get_issue_activities、count_issues、get_time_report、get_issue_work_items
一括変更	apply_command：YouTrack のコマンドダイアログにある任意のコマンドを、課題またはクエリ（最大 100 件）に適用します。最初に検証され、dryRun にも対応します
添付ファイル	課題とナレッジベースの記事の添付ファイル：get_issue_attachments、get_attachment（テキストはインラインで表示し、画像は画像として表示し、その他のファイルはローカルに保存）、add_attachment（複数ファイルを一度に追加）、delete_attachment
コメント	update_issue_comment
テキストの部分編集	edit_issue_description、edit_article_content：説明または記事内の文字列を検索して置換します。完全一致またはキャプチャグループ付きの正規表現で指定できるため、小さな変更のたびにテキスト全体を再送信する必要はありません
VCS	get_issue_vcs_changes：GitHub、GitLab、Bitbucket、Gitea、TeamCity の連携からコミットとプルリクエストを取得します
タグと保存済み検索	find_tags、create_tag、update_tag、delete_tag、create_saved_search、update_saved_search、delete_saved_search
その他の操作	call_api：他のツールで対応できない場合に、YouTrack または Hub の任意の REST エンドポイントをユーザーとして呼び出します

すべてのコマンドで --profile <key>（または YMCP_PROFILE）を指定して YouTrack インスタンスを選択します。例： ymcp --profile youtrack-acme check。指定しない場合、ymcp は youtrack プロファイルを使用します。プロファイルが 1 つしかない場合は、そのプロファイルを使用します。

データを削除または一括変更するツールには destructiveHint が付いているため、クライアントは実行前に確認します。

エラーには、次に何をすべきかが示されます。ymcp 独自のチェックでは、許可されている値が一覧表示されます（value "X" is not allowed; allowed: Critical, Major, …）。YouTrack のエラーにはステータスに応じたヒントが付加されます。404 の後に正しい ID を調べるツール、403 は再試行ではなく権限が必要であること、401 では ymcp auth が必要であることが示されます。プロキシからの HTML エラーページは、タイトルだけに短縮されます。

プロンプト

MCP プロンプトに対応しているクライアントでは、これらがスラッシュコマンドとして表示されます。それぞれ、どのツールをどの順番で使うかをモデルに指示し、確認なしに YouTrack を変更することはありません。

プロンプト
standup	前回の勤務日以降に行ったこと（月曜日の場合は金曜日以降）、次に行うこと、障害になっていることをまとめます。days を指定すると、さらに前までさかのぼります
triage	project の未トリアージ課題と、提案する種類、優先度、担当者、重複課題を表示します。承認された項目のみ適用します
sprint_report	board のスプリントについて、完了済みおよび未完了の作業、担当状況、スコープの変更、記録された時間、リスクをまとめます
issue_brief	issue の概要を把握できるよう、要約、状態、決定事項、未解決の質問、次のステップを示します

必要なツールが提供されている場合にのみ、プロンプトが表示されます（下記参照）。

ツールの選択

58 個すべてのツールを有効にすると、モデルのコンテキストを圧迫します。プロファイルで提供するグループを選択するか、serve に --tools（または YMCP_TOOLS）を渡して指定できます。この指定はプロファイルの設定より優先されます。

グループ	ツール
issues	検索、件数取得、読み取り、作成、編集、下書き、削除、コマンド、リンク、履歴、VCS の変更
comments	読み取り、追加、編集、削除、復元
attachments	課題と記事のファイル
articles	ナレッジベース
time	作業項目と時間レポート
agile	ボードとスプリント
projects	プロジェクトの検索と詳細表示
people	ユーザーとグループ
tags	タグと課題へのタグ付け
searches	保存済み検索
api	call_api

グループ名とツール名を組み合わせて選択でき、- を付けると除外できます。例：issues,comments,articles,-delete_issue。除外項目だけを指定した場合は、すべてを対象にしてから除外します。例：-api,-agile。起動ログには、提供されるツールが表示されます。例： tools="19 of 58: issues, comments, -delete_issue"。

パイプライン

パイプラインは YouTrack の検索を監視し、見つかった各課題をコーディングエージェントに渡します。エージェントは新しいブランチ上の専用の git ワークツリーで作業します。ymcp はブランチをプッシュし、プルリクエストまたはマージリクエストを作成し、変更がマージされるまでレビューコメントをエージェントに届けます。パイプラインの利用にはローカルへのインストールが必要です。Docker イメージには含まれていません。エージェントはこのマシン上、または SSH ホスト（workspace.host。~/.ssh/config のエイリアス）で作業します。

サイトのワークフローは、mainへの変更ごとに、TUI 自身のコードからこれらを生成します。

ymcp pipelineを実行すると TUI が開きます。プロファイル、それぞれのパイプラインのカード、パイプラインごとのボード、そして対応を待つ実行の受信トレイが表示されます。nを押すと、ウィザードを使ってパイプラインを作成できます。ボード上のカード、実行、またはバックログに残っている課題でenterを押すと、YouTrack の課題と同じように開きます。説明とコメント、プルリクエストのスレッド（[と]）、エージェントのログが表示されます。コメント欄（enter）では、以下のコマンドを/で補完できます。rを押すと、ボードまたはカードを再読み込みします。tを押すと、カードの上に実行のトランスクリプトが開きます。エージェントの思考や発言、実行する各ツールと、そのツールが参照するファイル、コマンド、パターン、さらに受け取った返信が、リアルタイムで表示されます。値が設定されている課題のフィールドはすべてカードの上部に表示され、タイトルの横、または収まらない場合はタイトルの下に、1行4つずつ並びます。eを押すと、プロジェクトのフィールド一覧が表示され、変更するフィールドを選べます。値を選択する、複数の値を追加または削除する、あるいは数値を入力できます。変更後にソースクエリで見つからなくなったバックログの課題は、ボードから消えます。ショートカットはキリル文字のキーボード配列でも使えます。kitty と Ghostty では、貼り付けたスクリーンショットや添付ファイルを含め、カード内に画像が表示され、エージェントの作業中ローダーもアニメーションします。それ以外のターミナルおよび tmux では、画像へのリンクが表示されます。YMCP_IMAGES=kittyまたはYMCP_IMAGES=offで設定を上書きできます。または、コマンドラインから実行します。

ymcp pipeline new backend --profile youtrack --dir ~/src/backend --query 'project: BE #Unresolved tag: ai'
ymcp pipeline backend edit     # adjust the stage commands to your workflow
ymcp pipeline backend check    # profile, query, stages, git and agent
ymcp pipeline backend run -d   # run in the background; `stop` stops it

ymcp pipeline --helpには、status、runs、logs、answer、cancel、deleteを含むすべてのコマンドが記載されています。各パイプラインは<config dir>/ymcp/pipelines/内の JSON ファイルで、実行情報は<config dir>/ymcp/state.dbに保存されます。

ステージ

ソースクエリには、保存済み検索と同じ構文を使います。見つかった各課題は、パイプラインのボード上を進んでいきます。

ステージ
Backlog	ソースクエリで見つかった課題のうち、まだ実行が開始されていないものです
Working	エージェントが課題に取り組みます。ymcp はステージの YouTrack コマンドを適用します。デフォルトは State In Progress です
Needs input	エージェントが質問した場合、権限を求めた場合、タイムアウトした場合、または失敗した場合です。ymcp は理由をコメントに記載し、tag needs-input を適用します
Review	エージェントの作業が完了し、ブランチがプッシュされた状態です。デフォルトのコマンドは State Fixed です
Done	デフォルトでは無効です。変更がマージされたとき、または課題がステージのクエリに一致したときに到達します
Closed	変更がマージされずにクローズされた場合、または課題がステージのクエリに一致した場合です。オプションのコマンドは /cancel への返信時にも実行されます

各ステージには、YouTrack のコマンドダイアログに入力する enter コマンドと、そのステージにある課題を識別する match クエリがあります。Working のコマンドは、課題をソースクエリの対象外にする必要があります。課題をソースクエリに戻すと、実行がキャンセルされます。実行がキャンセルされると（ymcp pipeline NAME cancel N の場合も同様）、コメントを付けてプルリクエストまたはマージリクエストをクローズし、ブランチは保持して、workspace.keepWorktree が設定されていない限りワークツリーを削除します。その課題を後で再実行すると、新しいブランチで開始します。実行をキャンセルするために課題を Backlog に戻した場合、課題がソースから外れるまでは再取得されません。それ以外の方法でキャンセルした場合は、課題がソースに戻ると再取得されます。変更がマージされずにクローズされると、実行は Closed として終了します。 workspace.parallel は、同時に実行する課題の数を設定します（1）。

終了した実行は、ボードまたは実行のカードで d を押すか、ymcp pipeline NAME delete N を実行すると、ローカルストアから削除できます。ログは削除されますが、課題、ブランチ、変更はそのまま残り、Backlog にあった課題は再取得されます。キャンセルされた実行は、ランナーが変更をクローズしてワークツリーを削除した後に削除できます。

エージェントは、リポジトリの user.name と user.email を使ってコミットします。workspace.identity.enabled を有効にすると、各ワークツリーでエージェント独自の作成者情報が使われ、ワークツリーの設定にのみ書き込まれます。workspace.identity.name は名前のテンプレート（{{agent.name}} · {{pipeline.name}} #{{run.number}}）で、workspace.identity.tag はメールアドレスの + の後に続く文字列のテンプレート（agent_{{pipeline.name}}_{{run.number}}。そのため [email protected] は [email protected] になります）です。どちらのテンプレートでも課題のキーを使用できます。タグに使われるのは小文字、数字、_ のみです。

すべてのコミットメッセージの先頭には workspace.commitPrefix（{{issue.id}}）が付きます。たとえばリポジトリで commitlint を実行している場合など、プレフィックスが不要なら "" を設定してください。そうすると、エージェントはリポジトリの形式に従ってコミットメッセージを作成します。strategy.title は PR/MR タイトルのテンプレート（{{issue.key}} {{issue.summary}}）です。{{commit.subject}} はブランチの最初のコミットの件名なので、"title": "{{commit.subject}}" とすると一般的な形式のタイトルになり、スカッシュマージでも保持されます。

エージェント

agent.provider
claude	CLI 経由の Claude Code。stream-json を使用する claude -p で、ターンごとに 1 つのプロセスを起動し、次のターンでは --resume を使用します
kimi	ACP 経由の Kimi Code。kimi acp
opencode	ACP 経由の opencode。opencode acp
acp	ACP に対応するその他のエージェント。agent.command で起動します

実行ごとに、ループバックポート上に専用の MCP サーバーと専用トークンが用意されます。エージェントはパイプラインのプロファイルとして、そのサーバー経由で YouTrack ツールを利用します。パスワードと YouTrack トークンは ymcp 内にとどまり、マシンの外に出ることはありません。 ランナーには、さらに 2 つのツールからアクセスできます。request_input は質問を行い、report は短いステータスを投稿します。

エージェントができることは、エージェント自身の設定によって決まります。モード（agent.mode。例：Claude の acceptEdits）と引数（agent.args。例：--allowedTools）です。エージェントが使用を許可されていないツールを要求した場合は、パイプラインの permissions で対応が決まります。ask（デフォルト）では実行が入力待ちになり、allow ではすべての要求を許可し、deny ではすべてを拒否して、エージェントはそのツールを使わずに続行します。新しい Claude パイプラインでは、agent.args に --dangerously-skip-permissions が設定されているため、Claude は確認なしですべてのツールを実行します。制限するには、この設定をモードまたは --allowedTools に置き換えてください。同じ理由から、新しい Kimi パイプラインは Kimi の yolo モードで開始します。auto は Kimi が安全と判断したものだけを許可し、default はすべてについて確認を求めます。

各ターンの前に ymcp が origin を取得するため、エージェントは自分で取得せずにベースブランチへリベースできます。

戦略

strategy.kind
branch	ブランチのみをプッシュします（デフォルト）。フィードバックは YouTrack からのみ受け取ります
github-pr	プルリクエスト
github-issue-pr	YouTrack の課題を反映する GitHub の課題と、それをクローズするプルリクエスト
gitlab-mr	gitlab.com またはセルフホストの GitLab 上にあるマージリクエスト。origin URL から特定します

プッシュ後、エージェントは専用の短いターンで PR/MR のタイトルと説明を作成します。ymcp は prompts.describe を使ってセッションを再開し、エージェントが set_change ツールに渡した内容を取得するため、作業中の発言がそこに反映されることはありません。説明の言語、形式、リンクなどのルールは prompts.describe に記述してください。エージェントがツールを呼び出さなかった場合、もう一度だけ呼び出すよう求め、そのターンの回答を説明として使用します。ホスト上で誰かが編集していない限り、その後のプッシュでも同じ方法で PR/MR が更新されます。"strategy": {"describe": false} を設定すると、strategy.title とそのターンの回答を使って作成します。strategy.draft を設定すると、ドラフトとして作成します。gitlab-mr では、strategy.squash と strategy.deleteBranch によって、マージリクエストの「コミットをスカッシュ」と「ソースブランチを削除」オプションがオンになります。トークンは、対象ホストにサインインしている gh または glab のいずれかから取得するか、システムのキーチェーン（サービス ymcp、アカウント vcs:<host>）から取得します。

CI

プッシュのたびに、ランナーはプッシュしたコミットの CI を監視します。GitHub の場合はチェック実行とコミットステータス、GitLab の場合はパイプラインを監視します。これはどの戦略でも機能します。branch は、トークンを使って origin が指すホストの CI を読み取ります。実行がレビュー中に CI が失敗すると、失敗したジョブとログの末尾をエージェントに渡してターンを開始し、その回答を課題に投稿します。このようなターンが ci.fixes 回（3 回）連続した後、次の失敗で実行が入力待ちになります。人が依頼したターンが始まると、回数のカウントは最初からやり直されます。カードのログには、CI の実行中、成功、失敗が表示されます。"ci": {"watch": false} を設定すると、監視が無効になります。

エージェントのメッセージ

エージェントが YouTrack またはプルリクエスト上に書き込む内容はすべて、非表示のマーカーとヘッダーで始まります。

@xlsft's agent #17 (backend)

Done: branch BE-123-fix-login, PR https://github.com/acme/api/pull/42

このマーカーは HTML コメントなので、YouTrack、GitHub、GitLab には表示されません。ymcp はこれを使って、エージェントのメッセージとあなたのメッセージを区別します。ヘッダーには、エージェント名、実行、パイプラインが記載されます。エージェントがメッセージへの対応を開始すると、ymcp はすぐにアニメーションする ymcp ロゴで返信し、後からそのコメントを回答、または実行が停止した理由に編集します。

フィードバックと入力が必要な場合

エージェントは、あなたのコメント、つまりプロフィールの YouTrack アカウントや gh または glab アカウントからのコメントに応答します。他のログインアカウントは feedback.youtrack、feedback.github、feedback.gitlab に追加してください。それ以外のユーザーからのコメントはスキップされます。 feedback.debounce（60s）以内に届いたコメントは、まとめてエージェントに送られます。

エージェントが質問した場合、権限を求めた場合、timeouts.silence（10m）にわたって応答がない場合、timeouts.total（2h）を超えて実行された場合、または失敗した場合、実行は入力待ちになります。許可された作成者からの最初の返信で再開されます。返信は YouTrack またはプルリクエストへのコメント、TUI の受信トレイ、あるいは ymcp pipeline backend answer 17 "…" で行えます。権限リクエストには /approve または /reject で応答します。timeouts.permission（30m）以内に返信がない場合、リクエストは拒否されます。 Claude の場合、/approve で許可されるのは、実行終了までの間、拒否されていた呼び出し（Bash(<command>)、Edit(//<path>)、…）に限られます。ツール全体が許可されるわけではありません。複合コマンドの場合、構成するコマンドごとにルールが適用されます。ワイルドカードやサブシェルなど、そのようなルールとして記述できない呼び出しは引き続き拒否されます。

次の3つの返信は ymcp 自体が処理し、エージェントには表示されません。

返信
/clear	YouTrack とプルリクエストまたはマージリクエストから、あなたとエージェントによる実行中のコメントをすべて非表示にします。コメントは履歴に残ります。YouTrack では削除済みとしてマークされ、復元できます。GitHub では古いコメントとして折りたたまれ、GitLab ではスレッドが解決済みになります（スレッド外の通常のコメントは表示されたままです）
/compact	パイプラインの language でエージェントに実行内容を要約させてから、コメントをクリアし、変更へのリンクとブランチへのリンクを含む要約を唯一のコメントとして残します
/cancel [why]	ymcp pipeline NAME cancel N と同じように実行をキャンセルし、クローズ済みステージのコマンドで課題をクローズします

"autoCompact": true にすると、完了またはクローズで終了するすべての実行がコンパクト化されます。コマンドは一度だけ実行されます。コメントを復元しても、コマンドは再実行されません。

通知

デフォルトでは、実行が入力待ちになった場合や失敗した場合、ymcp はアイコン付きのシステム通知を表示します。クリックすると、質問、プルリクエスト、または課題が開きます。macOS、Windows、Linux で動作します（Linux では D-Bus 上の通知デーモンが必要です）。

ymcp pipeline notify                                   # what is on and whether it works here
ymcp pipeline notify test                              # send a test notification
ymcp pipeline notify set toast.events=needs_input,run_failed,review_ready

イベントは needs_input、run_failed、review_ready、run_done、runner_stopped です。パイプラインでは、JSON の "notifications": {"events": [...]} を使って対象を絞り込めます。

プロンプトプリセット

エージェントのプロンプトは、プリセット（デフォルトは fix）から取得されます。プリセットには bugfix-test-first、feature、refactor、docs、investigate もあります。ymcp pipeline presets で各プリセットの用途を確認できます。prompts.start、prompts.feedback、prompts.answer を使うと、{{issue.id}} や {{branch}} などのプレースホルダーを含む、プリセットのテキストを置き換えられます。language（デフォルトは English）は、コメント、プルリクエスト、コミットメッセージなど、エージェントが公開するすべての内容で使われる言語です。

組み込みのプリセットは読み取り専用です。独自のプリセットは設定ファイルと同じ場所にある presets/ に保存されます。 ymcp pipeline presets copy fix mine を実行すると、presets edit mine で編集できるプリセットが作成されます。また、presets save NAME --from PIPELINE を実行すると、パイプラインで調整したプロンプトが保存されます。rename と rm は、それぞれ名前の変更と削除を行います。 パイプラインにはプリセットのテキストがコピーされるため、プリセットを変更または削除しても、パイプラインには影響しません。

設定

ymcp setup と ymcp auth は、各プロファイルの名前、URL、ログイン情報、プロキシを <config dir>/ymcp/config.json に保存します。このファイルを読み取れるのはあなただけです。

• macOS：~/Library/Application Support
• Linux：~/.config
• Windows：%APPDATA%

パスワードはシステムのキーチェーンに保存されます。macOS では Keychain、Linux では Secret Service、Windows では Credential Manager が使用されます。キーチェーンが存在しない場合に限り、設定ファイルに保存されます。

環境変数は、使用中のプロファイルに保存されている値より優先されます。CI で便利です。

変数
YOUTRACK_URL	インスタンスのルート。例：https://youtrack.example.com（/api は付けません）
YOUTRACK_LOGIN、YOUTRACK_PASSWORD	YouTrack または Hub のアカウント。LDAP も含みます
YOUTRACK_PROXY	HTTP(S)_PROXY を使用する場合（またはそのプロキシから YouTrack に接続できない場合に直接接続する場合）は空にします。常に直接接続する場合は none、プロキシ URL を使う場合はその URL を指定します
YMCP_PROFILE	--profile と同様に使用するプロファイル
YMCP_TOOLS	serve --tools と同様に提供するツール
YMCP_CONFIG	設定ファイルのパス

--env FILE を指定すると、これらの変数を dotenv ファイルから読み込みます（.env.example を参照）。

VPN を使用していますか？ MCP クライアントは、インターネット向けの HTTP(S)_PROXY を渡すことがよくあります。このようなプロキシは、内部の YouTrack をパブリック DNS で名前解決しようとするため、YouTrack に接続できません。プロキシが環境変数から設定されていて、YouTrack に接続できない場合、ymcp は直接接続し、その理由をログに記録します。明示的に設定したプロキシは常に使用されます。

HTTP

ymcp serve --transport http は、Streamable HTTP 経由で、各プロファイルをそれぞれ独自のパスで、すべて 1 つのプロセスから提供します。

YMCP_HTTP_TOKEN=$(openssl rand -hex 32) ymcp serve --transport http --addr 127.0.0.1:8090

起動ログには、各プロファイルとその URL（例：http://127.0.0.1:8090/youtrack-acme）が表示されます。デフォルトのプロファイルは / でも提供されます。--profiles a,b を指定すると、そのプロファイルだけが提供され、--profile a を指定すると、1 つのプロファイルだけが提供されます。サインインできないプロファイルは、警告を表示してスキップされます。

GET /healthz は、ロードバランサーや監視向けに、トークンなしで {"status":"ok","version":"…"} を返します。また、ymcp health を実行すると、コマンドラインからこのエンドポイントを確認できます。Docker イメージでは、このエンドポイントを HEALTHCHECK に使用します。

--token または YMCP_HTTP_TOKEN を指定すると、すべてのリクエストに Authorization: Bearer <token> が必要になります。クライアントの URL エントリにこのヘッダーを設定してください。トークンを設定しない場合、サーバーに接続できる人なら誰でもアクセスできるため、127.0.0.1（デフォルト）で待ち受けるか、トークンを設定してください。トークンなしで別のアドレスを待ち受けると、ymcp は警告を表示します。

Docker

xlsoftware/ymcp イメージは、linux/amd64 と linux/arm64 向けに HTTP サーバーを実行します。プロファイルは /config ボリュームに保存されます。コンテナにはキーチェーンがないため、パスワードはそのボリュームの設定ファイル（モード 0600）に保存されます。このボリュームは秘密情報として扱ってください。このイメージに含まれるのは MCP サーバーのみです。パイプラインにはローカルへのインストールが必要です。

プロファイルを追加します。auth は URL、ログイン情報、パスワードを尋ね、保存する前に確認します。

docker run -it --rm -v ymcp:/config xlsoftware/ymcp auth
docker run -it --rm -v ymcp:/config xlsoftware/ymcp --profile youtrack-acme auth   # another instance

トークンを設定して、ポート 8090 でサーバーを実行します。

docker run -d --name ymcp --restart unless-stopped \
  -p 127.0.0.1:8090:8090 -v ymcp:/config \
  -e YMCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  xlsoftware/ymcp
docker logs ymcp   # lists each profile and its URL

ボリュームを使わずに 1 つのインスタンスを実行する場合は、代わりに接続情報を渡します。 -e YOUTRACK_URL=https://youtrack.example.com -e YOUTRACK_LOGIN=… -e YOUTRACK_PASSWORD=…。

次に、Claude Code の例のように、トークンを指定してクライアントをプロファイルの URL に接続します。

claude mcp add --transport http youtrack http://127.0.0.1:8090/youtrack --header "Authorization: Bearer <token>"

または、JSON 設定を使います。

{ "mcpServers": { "youtrack": { "type": "http", "url": "http://127.0.0.1:8090/youtrack",
  "headers": { "Authorization": "Bearer <token>" } } } }

イメージは stdio にも対応しており、クライアントごとに 1 つのインスタンスを実行します。これは MCP Registry に io.github.xlsft/ymcp として登録されている実行方法です。レジストリからインストールしたクライアントは、次のコマンドを実行します。

docker run -i --rm -e YOUTRACK_URL -e YOUTRACK_LOGIN -e YOUTRACK_PASSWORD xlsoftware/ymcp serve

再試行

YouTrack が高負荷状態だったり再起動中だったりしても、ツール呼び出しはすぐには失敗しません。ymcp は最大 3 回再試行し、0.5 秒、1 秒、2 秒、または Retry-After で指定された時間（最大 10 秒）待機します。すべてのリクエストで 429 と 503 が対象となり、安全に繰り返せるリクエストでは 502、504、接続切断も対象となります。課題やコメントがすでに作成されている可能性がある POST は、2 回送信されることはありません。再試行のたびにログが記録されます。

ログ

サーバーは、起動時、接続するすべてのクライアント、およびすべてのツール呼び出しをログに記録します。起動時にはバックグラウンドで GitHub も確認し、新しいリリースがある場合は update available current=0.4.0 latest=0.5.0 run="ymcp update" と記録します。各行には引数、呼び出しにかかった時間、およびエラーがあればその内容が含まれます。サインインも記録されます。ログは stderr に出力され、Claude Desktop などのクライアントでは独自の MCP ログに記録されます。また、ファイルにも追記されるため、クライアントで ymcp を実行中に次のようにしてログを確認できます。

ymcp logs -f

ファイルは macOS では ~/Library/Logs/ymcp/ymcp.log、Linux では ~/.local/state/ymcp/ymcp.log、Windows では %LOCALAPPDATA%\ymcp\logs\ymcp.log です。5 MB でローテーションされます。

設定
ymcp -v serve または YMCP_LOG_LEVEL=debug	YouTrack と Hub のすべてのリクエストをステータスと所要時間とともにログに記録します
YMCP_LOG_LEVEL	debug、info（デフォルト）、warn、または error
YMCP_LOG_FILE	ログファイルの別のパス、または off
YMCP_UPDATE_CHECK=off	起動時に新しいリリースを確認しません

クライアントからデバッグレベルでログを記録するには、そのクライアントの ymcp エントリに "env": {"YMCP_LOG_LEVEL": "debug"} を追加します。

対応クライアント

Claude Code · Claude Desktop · Cursor · VS Code (Copilot) · Windsurf · Devin Desktop · Zed · Codex · Gemini CLI · Antigravity · JetBrains Junie · Cline · LM Studio · opencode · Kimi Code

Claude Desktop は実行中に設定をメモリから書き戻すため、その間に行った編集が失われます。そのため、ymcp setup では変更中に終了するかどうかを確認し、変更後に再起動します。

ymcp は各クライアントの設定を直接編集し、ほかのサーバー、キー、コメントを保持します。元のファイルと同じ場所に .ymcp.bak のコピーを作成します。そのほかのクライアントでは、プロファイルごとに、--profile <key> を指定して ymcp バイナリを実行する stdio サーバーを登録してください。

{ "mcpServers": { "youtrack": { "command": "/path/to/ymcp", "args": ["--profile", "youtrack"] } } }

サインインの仕組み

YouTrack の OAuth パスワードグラントにはサービスシークレットが必要ですが、通常のユーザーはそれを持っていません。そのため ymcp は、ログイン名とパスワードを使って Hub 経由でサインインします。

1. 公開されている /api/config から Hub の場所と YouTrack のサービス ID を読み取ります。
2. Hub のログインフォームを送信し、セッション Cookie を保持します。
3. YouTrack のウェブクライアントの暗黙的な OAuth フローを実行し、リダイレクトからベアラートークンを取得します。

期限切れのトークンは、パスワードを再送信せずにセッションから更新されます。パスワードが再送信されるのは、セッション自体が期限切れになった場合のみです。Hub API 用の Hub スコープ付きトークンは必要に応じて取得されます。このトークンはグループメンバーに必要です。二要素認証にはまだ対応していません。

開発

go build -o bin/ymcp ./cmd/ymcp
go test -race ./...
./bin/ymcp --env .env call get_current_user

単体テストではネットワークに接続しません。internal/youtrack/youtracktest は、ログインフォーム、OAuth リダイレクト、トークンの取り消しを含め、YouTrack と Hub をエミュレートします。ツールのテストでは、インメモリ MCP クライアントを介してツールを呼び出し、送信される REST リクエストを確認します。

E2E テスト（e2e/）では、ビルド済みバイナリを stdio 経由で起動し、実際の YouTrack に接続します。一時的なプロジェクトで 58 個すべてのツールを呼び出し、作成したものをすべて削除します。CI ではプッシュのたび、および毎晩実行されます。

コミットとリリースの手順については、CONTRIBUTING.md を参照してください。

ライセンス

MIT。JetBrains とは無関係です。YouTrack は JetBrains s.r.o. の商標です。