generate-codeful-mcp-tool

トリガー： コード記述型 MCP ツール、MCP サーバーツール、runTool の生成、MCP ツール JavaScript、 Dataverse MCP ツール、MCP App のサーバーロジック

キーワード： mcp apps、コード記述型ツール、runTool、dataApi、Dataverse、サーバーランタイム

エイリアス： /generate-codeful-mcp-tool、/codeful-tool

参考資料：

• ホスト API 型： codeful-tool-host-data-api.d.ts
• 正常動作するツール： account-summary.tool.js
• 正常動作するメタデータ： account-summary.tool.json
• ウィジェット生成： generate-mcp-app-ui

---

1 つの MCP ツールに対応するファイルのペアを生成します。

• <tool-name>.tool.js：完全な JavaScript サーバー実装。
• <tool-name>.tool.json：ツール名、説明、入力スキーマ、出力スキーマ、MCP ツールアノテーションを含む宣言型登録メタデータ。

ホストは JavaScript モジュールをインポートし、次を呼び出します。

await runTool({ toolInput, dataApi });

必要な情報

生成を始める前に、次の情報を確認してください。

1. ツールの目的とケバブケースのツール名。目的に基づいて、簡潔でモデルが実行可能なツールの説明を作成してください。意図された動作が曖昧な場合に限り、質問してください。
2. 入力フィールド、型、必須フィールド、制約。JSON Schema、代表的な入力オブジェクト、またはフィールドの正確な説明を受け付けます。入力の形状を推測してはいけません。
3. 期待される結果。代表的な出力オブジェクトがあると望ましいです。
4. Dataverse の読み取りまたは書き込みを行うか、業務用語で指定したテーブル、書き込みによって状態を作成、追加、更新、上書き、削除するかどうか。
5. ユーザーが MCP App ウィジェットも必要としているかどうか。

不足している情報についてのみ質問してください。ユーザーが同程度に正確な仕様を提示している場合、入出力のサンプルは必須ではありませんが、提示されていることが望ましいです。

フェーズ 1：ランタイムとメタデータの仕様を読む

次を読んでください。

${PLUGIN_ROOT}/references/codeful-tool-host-data-api.d.ts
${PLUGIN_ROOT}/samples/account-summary.tool.js
${PLUGIN_ROOT}/samples/account-summary.tool.json

生成するランタイムはプレーンな ESM JavaScript で、サイドカーはプレーンな JSON です。型ファイルは生成時の参照用であり、出力からインポートしてはいけません。

フェーズ 2：必要に応じて Dataverse スキーマを確認する

Dataverse を使用しないツールの場合は、このフェーズをスキップしてください。

Dataverse を使用するツールの場合：

1. PAC CLI が対象環境に認証済みであることを確認します。

2. 候補となるテーブルを検索します。

   pac model list-tables --search "table terms"
   

   --search は部分文字列ベースです。出力を絞り込み、選択した結果と論理名が完全に一致するテーブルのみを採用してください。候補となるテーブルが複数残る場合は、ユーザーに選択を求めてください。

3. 最終的な出力先の外に一意な一時ディレクトリを作成し、型を生成します。

   pac model genpage generate-types --data-sources "logical1,logical2" --output-file "<temp>/RuntimeTypes.ts"
   

4. RuntimeTypes.ts を読みます。登録済みテーブル、読み取り／書き込み可能な正確な論理列、ルックアップの形状、選択肢名、選択肢の数値の生値を抽出してください。

5. そのファイルで確認された名前と値のみを使用してください。カスタム列は予測できないため、表示名から導き出してはいけません。

検索または型生成に失敗した場合は処理を中止し、エラーを報告してください。作り上げたテーブルや列に代替してはいけません。検証後、一時的な型とディレクトリを削除し、最終出力には要求された .tool.js、.tool.json、および任意のウィジェットファイルのみを残してください。

フェーズ 3：ツール成果物のペアを生成する

ユーザーが別の出力先を指定していない限り、ユーザーの作業ディレクトリに <tool-name>.tool.js と <tool-name>.tool.json を書き込みます。両ファイルのベース名は同一で、確認済みのケバブケースのツール名と一致していなければなりません。

JavaScript ファイルは、次の要件を満たさなければなりません。

• runTool という名前の MCP エントリーポイントをちょうど 1 つだけエクスポートします。できれば次の形式を使用してください。

  export async function runTool({ toolInput, dataApi }) {
    // complete implementation
  }
  

• 実行時インポート、パッケージ、ネットワーク呼び出し、ファイルシステムアクセス、環境変数へのアクセス、生成型への依存がない、自己完結した JavaScript にしてください。

• 外部から渡されるすべての toolInput は、使用前に検証してください。件数には上限を設定し、OData フィルターに埋め込む値はエスケープしてください。

• Dataverse のエンティティ論理名は単数形を使用してください。select、filter、orderBy、行オブジェクトでは、正確な論理列名を使用してください。

• 選択肢ラベルとルックアップラベルは、"<column>@OData.Community.Display.V1.FormattedValue" から読み取ってください。

• クエリ行には page.rows 経由でアクセスしてください。page.hasMoreRows が true であり、関数が存在する場合に限り、page.loadMoreRows() を呼び出してください。

• ルックアップの設定には、RuntimeTypes.ts で検証済みの _<field>_value 形式を使用してください。生の Web API @odata.bind キーは出力しないでください。

• dataApi の失敗はそのまま送出してください。有用なコンテキストを追加する場合に限り捕捉し、元のエラーを原因として再送出してください。読み取りまたは書き込みに失敗した後、成功を装うフォールバック値を返さないでください。

• プレースホルダー、TODO、三点リーダー、テスト用認証情報、実際の環境 ID を含めないでください。

• JSON にシリアライズ可能な値のみを返してください。loadMoreRows、関数、クラスインスタンス、循環参照を返さないでください。

• ユーザーが明示的に求めた場合に限りテレメトリを出力し、テレメトリのプロパティにはツール入力、行の内容、識別子、その他のユーザーデータを決して含めないでください。

JSON サイドカーは、次の最上位フィールドを正確に含む有効な JSON でなければなりません。

{
  "name": "account-summary",
  "description": "Search accounts and return revenue and status summaries.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "outputSchema": {
    "type": "object",
    "properties": {}
  }
}

• name：確認済みのツール名および共有ファイルのベース名と完全に一致させてください。
• description：ツールの機能と呼び出すタイミングを説明する、簡潔でモデルが実行に移しやすいガイダンスにしてください。ユーザーのプロンプトをそのままコピーしたり、実装の詳細を含めたりしないでください。
• annotations：MCP の ToolAnnotations を使って、ツールの動作を説明してください。次の4つのブール値ヒントは必ずすべて出力してください。
  • readOnlyHint：ツールが Dataverse やその他の状態を変更できない場合に限り true にしてください。
  • destructiveHint：ツールが削除、上書き、その他の破壊的な更新を行う可能性がある場合は true にしてください。読み取り専用のツールと、破壊的でない作成や追加書き込みでは false にしてください。
  • idempotentHint：同じ有効な入力で繰り返し呼び出しても、追加の効果がない場合は true にしてください。読み取り、決定的な計算、同じ値を設定する更新は冪等です。作成と追記型の操作は冪等ではありません。
  • openWorldHint：コード実行環境から任意の外部システムにはアクセスできないため、常に false にしてください。 これらの値は、生成する実装と要求された動作から判断してください。書き込みの意味が本当に曖昧な場合は、推測せず生成前に確認してください。アノテーションは参考情報として扱い、実行時の検証や認可の代わりにしないでください。
• inputSchema：toolInput 用の完全な JSON Schema にしてください。ルートはオブジェクトとし、properties に受け付けるすべてのフィールドを列挙し、required で必須フィールドを指定してください。上限、形式、列挙値、配列項目の形状など、実行時の制約を記述し、ユーザーが拡張可能な入力を明示的に要求しない限り additionalProperties: false にしてください。
• outputSchema：モデルから見える structuredContent の業務ペイロード用 JSON Schema にしてください。プレーンオブジェクトを返す場合は、ホストがそのオブジェクトを structuredContent に昇格するため、返されるオブジェクト全体を記述してください。エンベロープを返す場合は、その structuredContent プロパティのみを記述してください。content、作成者が指定する meta、ランタイムの _meta は outputSchema に含めないでください。

標準の JSON Schema キーワードのみを使用してください。サイドカーには、認証情報、環境識別子、Dataverse の検出結果、ホスト設定、JavaScript 式、コメント、プレースホルダーを含めないでください。

結果チャネルの契約

最小限で適切な結果の形状を選んでください。

シンプルな構造化結果

有用な出力がすべてモデルから見える構造化データに含まれる場合は、プレーンオブジェクトを返してください。

return { records, totalCount: records.length };

ホストは、そのオブジェクトを MCP の structuredContent に昇格します。

パーティション化された MCP 結果

各チャネルの対象者が異なる場合は、エンベロープを返します。

return {
  content: `Found ${records.length} records.`,
  structuredContent: { records },
  meta: { preferredView: "table" },
};

• content：モデルから参照できる会話テキスト。文字列またはテキストコンテンツブロックです。
• structuredContent：モデルから参照できる機械可読オブジェクトです。
• meta：ウィジェット専用のオブジェクトです。ホストはこれを MCP _meta にマッピングし、ウィジェットは result._meta を読み取ります。

content、structuredContent、meta の各キーは、エンベロープ用に予約されています。業務ペイロードにこれらのキーが自然に含まれる場合は、ペイロード全体を明示的にラップしてください。

return { structuredContent: businessPayload };

エンベロープのキーを、無関係なトップレベルの業務フィールドと混在させないでください。

フェーズ 4：検証

完了を報告する前に、以下を確認してください。

1. このスキル用に、最終的な .tool.js ファイルが 1 つだけ作成され、それに対応する .tool.json ファイルも 1 つだけ作成されていることを確認します。
2. Node.js でファイルを ESM データ URL としてインポートし、runTool が関数であることをアサートします。インポート時に、データアクセスやその他のトップレベルの副作用を実行してはいけません。
3. サイドカーを JSON.parse で解析します。name、description、annotations、inputSchema、outputSchema のみが含まれていること、名前が両方のファイル名と一致すること、4 つのアノテーションヒントがすべてブール値であること、openWorldHint が false であること、その他のヒントが実装の実際の動作と一致すること、両方のスキーマのルートがオブジェクトであること、実行時に適用されるすべての入力制約が inputSchema に記載されていることを確認します。
4. 出力を grep して、インポート、require、プレースホルダー、推測した列、サポートされていないホストアクセスがないことを確認します。
5. 代表的な入出力が提供されている場合は、インラインの Node スクリプトからインメモリのモック dataApi を使って runTool を呼び出します。永続的なテストファイルは作成しないでください。
6. 返された値が要求された結果の契約に一致し、関数やシリアライズ不可能な値を含まず、その構造化ペイロードが outputSchema に準拠していることを確認します。代表的な入力が inputSchema に準拠していることも確認します。
7. 一時的なスキーマ関連の成果物をすべて削除します。

MCP App への任意の引き継ぎ

ユーザーがウィジェットを求めている場合：

1. 対応する .tool.js と .tool.json を先に完成させ、検証します。
2. 代表的な結果サンプルを作成します。
   • 通常のツール戻り値の場合は、structuredContent として扱います。
   • エンベロープの戻り値の場合は、content、structuredContent、および _meta（記述した meta フィールドから名前を変更したもの）を渡します。
3. 視覚要件、ツール名、入力サンプル、代表的な完全な結果を指定して generate-mcp-app-ui を呼び出します。ユーザーのリクエストに明示的な CDN ポリシーがある場合は、それを引き継ぎます。指定がない場合は、UI スキルに必須の CDN ポリシーに関する質問をさせます。公開 URL が許可されていると想定しないでください。
4. 出力は分けて保持します。選択した CDN ポリシーを使用した、.tool.js 1 つ、.tool.json 1 つ、単一ファイルの .html 1 つです。

改良

既存のコードを含むツールを編集する場合は、対応する両方のファイルを読み、要求された動作のみを変更します。実行時の検証とメタデータスキーマの整合性を保ちます。テーブル、列、ルックアップ、選択肢の値を追加し、それが当該ファイルについてまだ検証されていない場合は、スキーマ検証を再実行します。

完了時の応答

生成した両方のツールファイルのパスを示し、説明、ツールのアノテーション、入力の契約、構造化結果の契約を要約します。ウィジェットを求められた場合は、HTML のパスと、どの結果チャネルを使用するかも示します。