botuyo-mcp: Skill for Claude Code

BotUyo MCP Server — Hard Rules & Architecture

READ THIS ENTIRE FILE before making changes to the codebase. These are immutable rules that MUST be followed.

Core stack: TypeScript (strict) · Node.js (native fetch) · @modelcontextprotocol/sdk · Zod · Vitest Module system: ESM ("type": "module") — all import paths MUST use .js extension Published as: @botuyo/mcp on npm

---

RULE 0: Scope — Exclusive Responsibility (DO NOT MIX)

@botuyo/mcp exists SOLELY to build and configure conversational AGENTS (agents, families, stages, tools, knowledge, avatars, templates, publishing).

• NEVER add Recruiting tooling here (org profile, vacancy templates, presets, pipelines, candidates, reports, etc.). Recruiting is a separate, isolated product with its own auth/tenant model.
• ALL conversational configuration of the Recruiting product is owned by the Recruiting copiloto, NOT by this agent-building MCP.
• Do NOT create configure_recruiting_*, create_vacancy_template, apply_recruiting_preset or any recruiting tool/command in this repo.

RULE 1: Project Architecture

src/
├── index.ts          # Entry point: CLI sub-command router + MCP server startup
├── client.ts         # BotuyoApiClient — thin HTTP wrapper (GET/POST/PUT/DELETE)
├── tools/            # MCP tool definitions + handlers (one file per tool)
│   ├── index.ts      # Registry: ALL_TOOLS[] + TOOL_HANDLERS{}
│   ├── {tool}.ts     # Each tool: definition const + handler function
│   └── __tests__/    # One .spec.ts per tool (MockClient pattern)
└── commands/         # CLI sub-commands (login, auth, tenants, setup, etc.)

Hard rules:

• src/tools/ = MCP tools (exposed to AI assistants)
• src/commands/ = CLI commands (exposed to human users)
• dist/ = compiled output — NEVER edit manually

RULE 2: Tool File Pattern (CRITICAL)

Every MCP tool follows the exact same structure — a Tool definition + a handler function:

import type { Tool } from '@modelcontextprotocol/sdk/types.js'
import type { BotuyoApiClient } from '../client.js'

export const MY_TOOL: Tool = {
  name: 'my_tool',
  description: 'What this tool does. Include role requirements.',
  inputSchema: { type: 'object', properties: { ... }, required: [...] }
}

export async function myToolHandler(
  client: BotuyoApiClient, args: Record<string, unknown>
): Promise<unknown> {
  return client.get(`/api/v1/mcp/...`)
}