Graft

Graft

Use this skill when the task is about creating or refining a Graft server, wrapping an existing API with Graft proxy mode, or updating contributor-facing docs and examples so they match the current graft package behavior.

Product thesis

Graft's core value has three parts:

1. Define once — tools with a name, schema, and handler. 2. Serve as HTTP and MCP — from the same server, through a single shared pipeline (same auth, validation, middleware). 3. Discovery is automatic — agents find tools via agent.json, mcp.json, llms.txt. Humans get interactive docs (/docs) and an OpenAPI spec (/openapi.json). Zero configuration.

When explaining Graft, lead with all three parts. When showing examples, demonstrate both access patterns (MCP and HTTP) and mention what the server auto-serves. This applies to both source-based apps and proxy mode.

Workflow

1. Identify the mode before proposing changes:

• App authoring: createApp(...), tools, resources, prompts, HTTP routes, Node or fetch integration.
• Proxy/OpenAPI: graft serve --openapi ... or graft.proxy.yaml.
• Docs/release hygiene: README, install instructions, skills, examples, contributor checks.

2. Ground in the current repo before using memory:

• If tool access is available, inspect the current source, public exports, CLI commands, scaffold templates, and tests.
• If tool access is not available, ask for the smallest set of files or examples needed to avoid guessing.

3. Follow the current public contract in examples and reviews:

• Inline tool examples: prefer app.tool('name', config).
• Modular tool examples: prefer defineTool(...) plus app.tool(definedTool).
• Auth shapes: true, ['role'], or { roles: [...] }.
• MCP Streamable HTTP endpoint: POST /mcp.
• Auto-served framework endpoints: /.well-known/agent.json, /.well-known/mcp.json, /openapi.json, /docs, /llms.txt, /llms-full.txt, /health.
• Full CLI: serve, dev, check, test, studio, install, add-tool.
• When showing tool examples, demonstrate both the MCP tools/call invocation and the equivalent HTTP request (e.g. GET /list-items?q=hello or POST /create-entry).

4. Use tools where they materially improve correctness, but stay portable:

• With repo or shell access, inspect files and run validation commands after making changes.
• Without repo or shell access, state assumptions explicitly and keep recommendations tied to visible source or user-provided snippets.

5. Load only the reference you need:

• App authoring: references/app-authoring.md
• Proxy/OpenAPI wrapping: references/proxy-openapi.md
• Validation, docs, and release hygiene: references/validation-release.md

Quick examples

Inline tool — both access patterns

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

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

The same handler, auth middleware, and validation run for both.

Proxy mode — 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]

Start the proxy server:

graft serve --config graft.proxy.yaml

Graft exposes each configured operation as both an HTTP endpoint and an MCP tool, and auto-generates /openapi.json, /docs, and discovery files.

For the direct OpenAPI path, use:

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

Guardrails

• Do not document unsupported behavior just because an older example mentioned it.
• Keep examples executable and small; prefer one correct pattern over many variants.
• Prefer current source and tests over stale notes, blog posts, or memory.
• Do not mention registry or publishing artifacts unless they actually exist in the repo being edited.
• When a docs claim is likely to drift, add or update an automated check.

App Authoring

Use this reference when the user is working on a source-based Graft app built with createApp(...).

Current patterns

• Start with createApp({ name, version, description, ... }).
• For small examples and README snippets, register tools inline with app.tool('name', config).
• For modular apps and scaffolded projects, define tools in separate modules with defineTool('name', config) and register them with app.tool(definedTool).
• Resources and prompts are still registered with object configs through app.resource(...), app.resourceTemplate(...), and app.prompt(...).
• Use app.route(...) for plain HTTP-only routes and app.webhook(...) for HTTP-only routes that should still go through the tool pipeline.
• When demonstrating a tool, show both surfaces: the MCP tools/call invocation and the equivalent HTTP request.

Tool design defaults

• Use stable, explicit names such as orders_create or inventory_get_stock.
• Write descriptions that say what the tool does, when to use it, and what it returns or changes.
• Keep input schemas simple and explicit; include examples for non-trivial tools.
• Mark mutations with sideEffects: true.
• Use expose: 'both', 'mcp', or 'http' intentionally.
• Use current auth shapes only:
• true
• ['admin']
• { roles: ['admin'] }

Demonstrating the dual surface

When writing docs, examples, or explaining Graft to users:

• Show the same tool accessed via MCP and HTTP side-by-side. For example:
• MCP: POST /mcp with { "method": "tools/call", "params": { "name": "list_items", "arguments": { "q": "hello" } } }
• HTTP: GET /list-items?q=hello
• Highlight that both go through the same pipeline: authenticate → check roles → validate params → middleware → handler.
• For mutations (sideEffects: true), note that the HTTP method changes from GET to POST.
• For expose: 'mcp' or expose: 'http' tools, explain what is visible on each surface.
• Mention that the server auto-serves discovery and docs endpoints (agent.json, mcp.json, openapi.json, /docs, llms.txt, llms-full.txt, /health) when relevant to the user's task.

Runtime and delivery surfaces

• app.build() returns { mcp, fetch }.
• app.toFetch() is the cleanest integration for Bun, Deno, and worker-style runtimes.
• app.toNodeHandler(), app.node(), and app.serve() cover Node integration and standalone serving.
• When writing docs for end users, prefer the simplest surface that matches the target runtime.

Documentation defaults

• Prefer one inline example plus one modular example instead of listing every registration overload.
• If the repo ships scaffolds, align docs with the scaffolded structure unless there is a strong reason not to.
• Keep MCP examples in actual JSON-RPC shape when showing request payloads.
• Always mention auto-served discovery and docs endpoints when documenting deployment or server startup.
• Reference the complete CLI command set: serve, dev, check, test, studio, install, add-tool.
• When documenting testing, show the examples property on tools and graft test -e src/app.ts as the smoke-test workflow.

Proxy and OpenAPI

Use this reference when the user wants to expose an existing HTTP API through Graft without writing a source-based app first.

Even in proxy mode, the generated Graft server exposes both MCP and HTTP surfaces from a single server, with auto-served discovery and docs endpoints — the same thesis as source-based apps.

Entry paths

• OpenAPI mode: graft serve --openapi ./openapi.yaml --target <base-url>
• Config mode: graft serve --config ./graft.proxy.yaml
• Check mode uses the same source inputs through graft check --openapi ... or graft check --config ...

Curation guidance

• Do not expose every upstream endpoint to MCP by default.
• Keep the MCP-visible surface focused on agent-relevant operations.
• Rename operations and tighten descriptions when the generated names are vague.
• Make mutating operations explicit and protect them with auth when needed.

Current proxy-facing realities

• The generated server exposes MCP over POST /mcp.
• The proxy server auto-serves the same framework endpoints as source-based apps: /.well-known/agent.json, /.well-known/mcp.json, /openapi.json, /docs, /llms.txt, /llms-full.txt, /health.
• If documenting parameterLocations.name, describe it only for header and query remapping, not body or path.
• --header defines caller-overridable defaults.
• --locked-header defines operator-controlled headers that callers cannot override.

Documentation defaults

• Show one minimal OpenAPI command example and one minimal graft.proxy.yaml example.
• If the task is docs or review work, compare examples against the current CLI flags and transport tests instead of assuming older behavior.
• Mention the auto-served discovery and docs surface when documenting proxy deployments — agents discover proxy tools the same way they discover source-app tools.
• Reference the CLI commands available in proxy mode: serve, dev, check, studio (note: test and add-tool are source-app only).

Validation and Release Hygiene

Use this reference when the task is docs cleanup, release readiness, contributor experience, or validating that a Graft change matches the current package behavior.

What to inspect first

• Public exports and top-level docs
• CLI command sources and help text
• Scaffold templates if the project ships generators
• Tests that define transport, auth, and example behavior

Validation loop

If shell or repo tools are available:

1. Run the narrowest relevant validation first. 2. For package changes, use the package-local checks such as:

• pnpm --filter graft test
• pnpm --filter graft typecheck
• pnpm --filter graft lint

3. For example or transport docs, compare against tests before finalizing the wording. 4. For app or proxy docs, use graft check and graft studio when that materially validates the documented workflow.

If tools are not available:

• State the exact files or tests that should be checked before publishing.
• Call out any assumption that could invalidate the docs or skill content.

Drift prevention

• Add lightweight docs contract tests for claims that are easy to regress:
• public API example shapes
• auth forms
• transport method claims
• required skill packaging artifacts
• Prefer string or contract assertions over large snapshots.

Release checklist

• README examples compile conceptually against the current public API.
• Skill instructions match the current package behavior and CLI.
• No unsupported registry or publishing metadata is documented unless the repo actually contains it.
• Examples and guidance reflect the current scaffold or recommended project structure.