mcp-tool-authoring

Tool Authoring Guide — mcp/

What is a tool?

A tool is one user-visible MCP action that wraps exactly one Kaminari Ad /api/v1 endpoint call. If you need two API calls, you need a domain service (in mcp/src/domain/services/), not a single tool.

File layout — one tool per file

mcp/src/application/tools/<domain>/<tool-name>.tool.ts

Template

import { z } from "zod";
import { ok, err, type Result } from "neverthrow";

import type { Tool } from "../_shared/tool.js";
import type { ToolError } from "../_shared/tool-result.js";

// 1. Input schema. Every field has .describe() for the agent.
const ListScansInput = z.object({
  status: z
    .string()
    .optional()
    .describe("Comma-separated statuses: pending,running,done,failed."),
  date_from: z.string().date().optional().describe("ISO date, inclusive."),
  date_to: z.string().date().optional().describe("ISO date, inclusive."),
  page: z.number().int().min(1).max(500).default(1).describe("1-indexed page number."),
  limit: z.number().int().min(1).max(200).default(50).describe("Page size."),
});
type ListScansInput = z.infer<typeof ListScansInput>;

// 2. Output type — the shape the agent sees in the tool result.
interface ListScansOutput {
  readonly total: number;
  readonly items: readonly ScanSummary[];
}

// 3. The tool. Named export = camelCase of filename + "Tool".
export const listScansTool: Tool<ListScansInput, ListScansOutput> = {
  name: "list_scans",
  description: "List scans for the caller's organization, with filters.",
  inputSchema: ListScansInput,
  handler: async (input, ctx): Promise<Result<ListScansOutput, ToolError>> => {
    const apiResult = await ctx.api.listScans(input);
    if (apiResult.isErr()) {
      return err(apiResult.error);
    }
    return ok({
      total: apiResult.value.total,
      items: apiResult.value.items.map(toScanSummary),
    });
  },
};