Custom Tools

Custom Tools

Aperio exposes 38 built-in MCP tools, but you can easily add your own.

---

Adding a custom MCP tool

Each tool is a file in mcp/tools/ that exports a register(server, ctx) function.

Minimal example

Create mcp/tools/weather.js:

import { z } from "zod";

export function register(server, ctx) {
  server.tool(
    "get_weather",
    "Get current weather for a city",
    {
      city: z.string().describe("City name"),
    },
    async ({ city }) => {
      const res = await fetch(
        `https://wttr.in/${encodeURIComponent(city)}?format=%C+%t`
      );
      const text = await res.text();
      return { content: [{ type: "text", text }] };
    }
  );
}

Then register it in mcp/index.js:

import { register as registerWeather } from "./tools/weather.js";
registerWeather(server, ctx);

Tool context (ctx)

Every tool receives the same ctx object:

{
  store,                // DB instance (SQLite or Postgres)
  generateEmbedding,    // Vector embedding function
  vectorEnabled(),      // Whether vector search is active
  embeddingQueue,       // Batched background embedding processor
  providerIsLocal,      // Whether current model runs locally (privacy gate)
}

Best practices

• Use zod for input validation
• Return { content: [{ type: "text", text }] } format
• Respect path guards for file operations
• Use confirm-before-write pattern for destructive actions
• Keep tools focused — one function, one responsibility

---

Adding custom skills

Skills live in skills/<skill-name>/SKILL.md. Each skill is a set of local instructions loaded by the skill matcher.

Add your own:

mkdir -p skills/my-custom-skill
touch skills/my-custom-skill/SKILL.md

See Skills reference for the format.

---

Customizing agent identity

Edit id/whoami.md to change how the AI agent introduces itself and behaves.

For round-table mode, edit:

• id/whoami-primary.md — Agent A
• id/whoami-verifier.md — Agent B