カスタム MCP ツール

定義済みの MCP ツールに加えて、独自のツールを作成し、YouTrack のユーザーが AI クライアントから YouTrack MCP サーバーに接続するときにそのツールにアクセスできるようにすることができます。

YouTrack にカスタム MCP ツールを追加するには、カスタムアプリパッケージに追加してください。そうすることで、YouTrack ユーザーは AI クライアントを操作する際にそのツールを活用できるようになります。カスタムアプリの作成方法については、アプリクイックスタートガイドを参照してください。

すべての MCP ツールは、YouTrack ワークフロー API を使用して JavaScript で記述されたスクリプトです。このスクリプトは、専用の aiTool ルールタイプを実装する必要があります。

カスタム MCP ツールを作成する

セキュリティ上の理由から、すべての定義済み MCP ツールは読み取り専用です。定義済み MCP ツールを変更または更新する場合は、対応するスクリプトをカスタムアプリパッケージのモジュールとしてコピーし、変更を加えることができます。

カスタム MCP ツールを作成するには:

アプリパッケージを作成します。詳細については、「アプリパッケージの作成」を参照してください。
アプリパッケージで、JavaScript モジュールを作成します。
カスタム MCP ツールの形式に従ってロジックを実装します。
必要に応じて、アプリの manifest.json ファイルにカスタムツール接頭辞を追加します。
アプリパッケージを保存し、YouTrack にアップロードします。

MCP ツールを含むアプリを YouTrack にアップロードすると、これらのツールはすべてのプロジェクトのすべてのユーザーが利用できるようになります。MCP ツールは、使用するユーザーと同じレベルの YouTrack データへのアクセス権限を持ちます。

セキュリティ上の理由から、カスタムツールは接続の MCP エンドポイント URL に明示的に含める必要があります。例: /mcp?customToolPackages=app-name1,app-name2 ここで、app-name1 と app-name2 はカスタムツールを定義するアプリの名前です。

YouTrack 管理者が新しいカスタム MCP ツールを追加するたびに、YouTrack MCP サーバーに接続したユーザーは、新しいツールの使用を開始するために、接続を無効にしてから再度有効にする必要があります。

カスタム MCP ツール形式

YouTrack MCP ツールは JavaScript で記述されています。YouTrack ワークフロー API を使用し、YouTrack ワークフロールールと同じ構文に従います。MCP ツールスクリプトは、専用の aiTool ルールタイプを実装します。

JavaScript のカスタム MCP ツールの主な要素は次のとおりです。

ツールオブジェクトは、JavaScript スクリプトから aiTool としてエクスポートする必要があります。例: exports.aiTool = { ... }
ツールオブジェクトは、ツール記述子とツールアクションの 2 つの部分で構成されます。

ツール記述子

ツール記述子には次の要素が含まれます。

要素	説明	必須
`name`	MCP ツールの名前。	必須
`description`	MCP ツールの説明。	オプションですが、強く推奨されます
`inputSchema`	ツール入力パラメーターの JSON スキーマ。	オプション
`outputSchema`	出力の JSON スキーマ。 MCP エンドポイントはデフォルトで出力スキーマを非表示にしていることに注意してください。必要に応じて、`/mcp?enableToolOutputSchema=true` クエリパラメーターを使用して有効にすることができます。	オプション
`annotations`	ツールアノテーション: `title` `readOnlyHint` `destructiveHint` `idempotentHint` `openWorldHint` `returnDirect` 参考までに MCP 仕様(英語)を参照してください。	オプション

これらの要素には、LLM に役立つ関数に関する情報が含まれています。

ツールアクション

ツールアクションは、ツールロジックを実装する JavaScript 関数です。この関数の入力と出力の説明は次のとおりです。

入力

ctx - スクリプトコンテキストオブジェクト。

コンテキストオブジェクトは、JSON 入力スキーマ (LLM によって提供されるツールパラメーター) に従って ctx.arguments オブジェクトを提供します。
issueId のような引数はコード内で解決する必要があります。例: entities.Issue.findById(ctx.arguments.issueId)
コンテキストオブジェクトは、ctx.issue、ctx.article、または ctx.user を提供しません。

出力

JavaScript 関数は、JSON object/array、string、null など何でも返すことができます。また、何も返さない場合もあります (つまり、undefined)。

YouTrack バージョン 2026.2 以降では、カスタム MCP ツールでも asyncFunctions オブジェクトを宣言できます。ツールが結果を AI クライアントに即座に返し、現在のトランザクションが完了した後に後続処理を継続する必要がある場合は、ツールアクションから ctx.invokeAsync() を使用してください。詳細は非同期関数を参照してください。

ツール接頭辞

すべてのカスタム MCP ツールの名前には特別な接頭辞が付きます。YouTrack では、カスタム MCP ツールを定義済みツールと区別し、他のカスタムツールとの名前の衝突を避けるために、ツール接頭辞が必要です。

マニフェストでツールの接頭辞を設定すると、ツールのリストでツールは <aiToolPrefix>_<tool_name> のように表示されます。

アプリマニフェストに aiToolPrefix 値を追加することで、カスタム MCP ツールの接頭辞を設定できます。以下に、この MCP ツールを含むアプリパッケージの manifest.json ファイルの例を示します。この例のツールは、ツールリストに test_<tool_name> として表示されます。

                {
                    "name": "my-tools",
                    "title": "My AI Tools",
                    "description": "App description",
                    "aiToolPrefix": "test"
                }
            

マニフェストでツール接頭辞を設定しない場合、YouTrack はアプリ名をツール接頭辞として使用します。そのため、ツールリストではツールは「<app_name>_<tool_name>」のように表示されます。

サンプルカスタム MCP ツール

カスタム MCP ツールを実装するサンプルアプリパッケージには、ロジックを記述する JavaScript ファイルとアプリマニフェストの 2 つのファイルが含まれています。

JavaScript モジュール

ここでは、カスタム MCP ツールを実装する JavaScript モジュールの例を示します。

            const entities = require('@jetbrains/youtrack-scripting-api/entities');

            exports.aiTool = {
              name: "get_issue_content",
              description: "Returns information about an issue by its ID",
              inputSchema: { // JSON Schema
                type: "object",
                properties: {
                  issueId: {
                    type: "string",
                    description: "The issue ID (e.g. TEST-1234)"
                  }
                },
                required: ["issueId"]
              },
              annotations: {
                title: "Get issue content",
                readOnlyHint: true,
                destructiveHint: false,
                idempotentHint: false,
                openWorldHint: false,
                returnDirect: false
              },
              execute: (ctx) => {
                const issue = entities.Issue.findById(ctx.arguments.issueId);
                return {
                  id: issue.id,
                  description: issue.description,
                  state: issue.fields.State,
                  assignee: issue.fields.Assignee?.login,
                  project: {
                    name: issue.project.name,
                    key: issue.project.key
                  }
                }
              },
              outputSchema: { // JSON Schema
                type: "object",
                properties: {
                  id: {
                    type: "string",
                    description: "The issue ID"
                  },
                  description: {
                    type: "string",
                    description: "The issue description"
                  },
                  //...
                },
                required: ["id"]
              }
            }
        

2026 年 7 月 06 日

YouTrack および Hub ヘルプの開発者ポータル