Graft

Graft サーバーの作成または改善、既存 API の Graft プロキシモードによるラッピング、または現在の graft パッケージの動作に合わせた貢献者向けドキュメントと例の更新が必要な場合に、このスキルを使用してください。

プロダクトのコンセプト

Graft のコア価値には 3 つの側面があります：

1. 一度の定義 — 名前、スキーマ、ハンドラーを持つツール。
2. HTTP と MCP として提供 — 同じサーバーから、単一の共有パイプライン（同じ認証、バリデーション、ミドルウェア）を通じて。
3. ディスカバリーは自動 — エージェントは agent.json、mcp.json、llms.txt 経由でツールを検出します。ユーザーはインタラクティブなドキュメント（/docs）と OpenAPI スペック（/openapi.json）を取得します。ゼロ設定。

Graft を説明する際は、3 つすべての側面をリードします。例を示すときは、両方のアクセスパターン（MCP と HTTP）を実演し、サーバーが自動提供するものについて言及してください。これは、ソースベースのアプリとプロキシモードの両方に適用されます。

ワークフロー

1. 変更を提案する前にモードを特定します：

• アプリオーサリング：createApp(...)、ツール、リソース、プロンプト、HTTP ルート、Node または fetch インテグレーション。
• プロキシ/OpenAPI：graft serve --openapi ... または graft.proxy.yaml。
• ドキュメント/リリースの衛生：README、インストール手順、スキル、例、貢献者チェック。

2. メモリを使用する前に現在のリポジトリを確認します：

• ツールアクセスが利用可能な場合は、現在のソース、パブリックエクスポート、CLI コマンド、スキャッフォルドテンプレート、テストを検査します。
• ツールアクセスが利用不可の場合は、推測を避けるために必要な最小限のファイルまたは例セットを要求してください。

3. 例とレビューで現在のパブリックコントラクトに従います：

• インラインツール例：app.tool('name', config) を優先します。
• モジュラーツール例：defineTool(...) と app.tool(definedTool) を優先します。
• 認証形状：true、['role']、または { roles: [...] }。
• MCP Streamable HTTP エンドポイント：POST /mcp。
• 自動提供フレームワークエンドポイント：/.well-known/agent.json、/.well-known/mcp.json、/openapi.json、/docs、/llms.txt、/llms-full.txt、/health。
• フル CLI：serve、dev、check、test、studio、install、add-tool。
• ツール例を示すときは、MCP tools/call の呼び出しと同等の HTTP リクエスト（例：GET /list-items?q=hello または POST /create-entry）を実演してください。

4. 正確性を実質的に向上させる場合はツールを使用しますが、ポータビリティを保ちます：

• リポジトリまたはシェルアクセスがある場合は、変更後にファイルを検査し、バリデーションコマンドを実行します。
• リポジトリまたはシェルアクセスがない場合は、仮定を明示的に述べ、推奨事項を目に見えるソースまたはユーザーが提供したスニペットに結びつけておきます。

5. 必要な参照のみを読み込みます：

• アプリオーサリング：references/app-authoring.md
• プロキシ/OpenAPI ラッピング：references/proxy-openapi.md
• バリデーション、ドキュメント、リリース衛生：references/validation-release.md

クイック例

インラインツール — 両方のアクセスパターン

import { createApp } from '@schrepa/graft'
import { z } from 'zod'

const app = createApp()

app.tool('list_items', {
  description: 'クエリに一致するアイテムをリストします。',
  params: z.object({ q: z.string() }),
  auth: true,
  handler: async ({ q }) => ({
    items: ['hello', 'world'].filter((item) => item.includes(q)),
  }),
})

export default app

MCP (tools/call):

{ "method": "tools/call", "params": { "name": "list_items", "arguments": { "q": "hello" } } }

HTTP 等価:

GET /list-items?q=hello
Authorization: Bearer <token>

同じハンドラー、認証ミドルウェア、バリデーションが両方に対して実行されます。

プロキシモード — graft.proxy.yaml

target: https://petstore3.swagger.io/api/v3
tools:
  - method: GET
    path: /pet/findByStatus
    name: find_pets_by_status
    description: ステータス別にペットを検索します。
    parameters:
      type: object
      properties:
        status:
          type: string
  - method: POST
    path: /pet
    name: create_pet
    description: ペットを作成します。
    parameters:
      type: object
      properties:
        name:
          type: string
      required: [name]

プロキシサーバーを起動します：

graft serve --config graft.proxy.yaml

Graft は設定された各操作を HTTP エンドポイントと MCP ツール両方として公開し、/openapi.json、/docs、およびディスカバリーファイルを自動生成します。

直接 OpenAPI パスの場合は、以下を使用します：

graft serve --openapi ./openapi.yaml --target https://api.example.com

ガードレール

• 古い例に言及されているからという理由だけで、サポートされていない動作をドキュメント化しないでください。
• 例は実行可能で小さい状態に保ちます；多くのバリアントより 1 つの正しいパターンを優先します。
• 古いノート、ブログ記事、またはメモリより現在のソースとテストを優先します。
• 編集中のリポジトリに実際に存在しない限り、レジストリやパブリッシング成果物について言及しないでください。
• ドキュメントの主張がドリフトする可能性が高い場合は、自動チェックを追加または更新してください。