Pular para o conteúdo principal
Você expõe uma função como ferramenta MCP para agentes de IA invocarem. Com .describe() você informa ao agente o que cada parâmetro faz. Padrão: name claro + description + .describe() em cada campo + MCP ativo (padrão).
index.ts
import { define, z } from "@jelou/functions";

export default define({
  name: "search-products",
  description: "Searches the product catalog by name, category, or price range",
  input: z.object({
    query: z.string().min(1).describe("Search term: product name or keywords"),
    category: z.string().optional().describe("Filter by category: electronics, clothing, home, food"),
    minPrice: z.number().optional().describe("Minimum price in USD"),
    maxPrice: z.number().optional().describe("Maximum price in USD"),
    limit: z.number().default(5).describe("Maximum number of results (1-20)"),
  }),
  output: z.object({
    results: z.array(z.object({
      id: z.string(),
      name: z.string(),
      price: z.number(),
      category: z.string(),
      inStock: z.boolean(),
    })),
    total: z.number(),
  }),
  handler: async (input, ctx) => {
    ctx.log("Product search", {
      query: input.query,
      category: input.category,
      company: ctx.company.id,
    });

    const apiKey = ctx.env.get("CATALOG_API_KEY");
    const params = new URLSearchParams({ q: input.query });
    if (input.category) params.set("category", input.category);
    if (input.minPrice) params.set("min_price", String(input.minPrice));
    if (input.maxPrice) params.set("max_price", String(input.maxPrice));
    params.set("limit", String(input.limit));

    const res = await fetch(
      `https://catalog.example.com/api/search?${params}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    const data = await res.json();

    return {
      results: data.items.map((item: any) => ({
        id: item.id,
        name: item.name,
        price: item.price,
        category: item.category,
        inStock: item.stock > 0,
      })),
      total: data.total,
    };
  },
});

Testes locais

curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"query": "laptop", "category": "electronics", "maxPrice": 1500}'

Por que funciona dessa forma

  • name e description são o que o agente de IA vê para decidir quando usar esta ferramenta.
  • .describe() em cada campo gera as descrições dos parâmetros no schema MCP.
  • O schema output documenta qual estrutura a função retorna.
  • MCP está ativo por padrão (config.mcp: true), portanto o endpoint /mcp expõe a ferramenta automaticamente.
  • Um agente de IA pode chamar esta função quando o usuário perguntar “vocês têm laptops abaixo de $1500?”.