graft

Graft

当任务涉及创建或优化 Graft 服务、使用 Graft 代理模式封装现有 API，或更新面向贡献者的文档和示例以匹配当前 graft 软件包行为时，请使用此技能。

产品理念

Graft 的核心价值包含三部分：

1. 定义一次 — 定义具有名称、架构和处理程序的工具。
2. 同时提供 HTTP 和 MCP 服务 — 通过同一服务和单一共享流水线提供（使用相同的身份验证、验证和中间件）。
3. 自动发现 — Agent 通过 agent.json、mcp.json、llms.txt 找到工具。用户可以使用交互式文档（/docs）和 OpenAPI 规范（/openapi.json）。无需配置。

介绍 Graft 时，要先说明这三部分。展示示例时，要同时演示两种访问方式（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. 在能显著提升准确性的地方使用工具，同时保持可移植性：

• 如果可以访问仓库或 shell，请检查文件，并在完成更改后运行验证命令。
• 如果无法访问仓库或 shell，请明确说明假设，并确保建议基于可见源代码或用户提供的片段。

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: '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

注意事项

• 不要仅仅因为旧示例提到过某种行为，就记录当前不支持的行为。
• 示例应简短且可执行；优先采用一种正确模式，而不是提供多种变体。
• 相较于过时的笔记、博客文章或记忆，优先参考当前源代码和测试。
• 除非正在编辑的仓库中确实存在相关内容，否则不要提及注册表或发布产物。
• 对于可能过时的文档声明，请添加或更新自动化检查。