graft

Graft

Graft サーバーの作成や改良、既存の API を Graft プロキシモードでラップする作業、または現在の graft パッケージの動作に合わせてコントリビューター向けのドキュメントや例を更新する作業では、このスキルを使用してください。

製品の理念

Graft の中核的な価値は、次の 3 つです。

1. 一度定義する — 名前、スキーマ、ハンドラーを持つツール。
2. HTTP と MCP で提供する — 同じサーバーから、単一の共通パイプライン（同じ認証、検証、ミドルウェア）を通じて提供します。
3. 自動で検出できる — エージェントは agent.json、mcp.json、llms.txt を通じてツールを見つけます。人間向けには、インタラクティブなドキュメント（/docs）と OpenAPI 仕様（/openapi.json）を提供します。設定は不要です。

Graft を説明する際は、まずこの 3 つすべてを紹介してください。例を示すときは、2 つのアクセス方法（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

すぐに使える例

インラインツール — 2 つのアクセス方法

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

const app = createApp()

app.tool('list_items', {
  description: 'List items matching a query.',
  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: Find pets by status.
    parameters:
      type: object
      properties:
        status:
          type: string
  - method: POST
    path: /pet
    name: create_pet
    description: Create a pet.
    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 つ示すことを優先してください。
• 古いメモ、ブログ記事、記憶よりも、現在のソースやテストを優先してください。
• 編集対象のリポジトリに実在しない限り、レジストリや公開に関する成果物には触れないでください。
• ドキュメントの記述が古くなる可能性が高い場合は、自動チェックを追加または更新してください。