iron-mcp-framework: Skill for Codex

Crear una tool en IronMCP

Implementa la tool solicitada y deja el cambio validado. Las rutas src/, test/, examples/ y docs/ de esta guía son relativas a la raíz del repositorio. Da prioridad al código vigente si esta guía y el contrato difieren.

Ubicar el contrato

Lee src/framework/types.ts, src/framework/create-mcp-server.ts, src/tools/index.ts y una tool similar antes de editar. Para una integración REST, consulta también src/framework/rest/rest-client.ts. Usa references/example.md cuando necesites un ejemplo completo de tool, prueba y petición HTTP; adapta sus campos al endpoint real.

A partir del pedido y la documentación disponible, identifica nombre, propósito, entradas, operación, respuesta esperada y permisos. Si falta un dato que impida definir la integración, pide ese dato; no inventes endpoints ni campos del proveedor. Si la información alcanza, implementa sin detenerte en una propuesta.

Implementar e integrar

• Crea src/tools/<nombre-kebab-case>.tool.ts con un nombre MCP único en snake_case y defineTool de ../framework/types.js. Usa imports .js para módulos locales e import * as z from "zod/v4".
• Define name, title, description, inputSchema, outputSchema, timeoutMs, idempotent, auth, audit y handler. outputSchema es opcional en TypeScript, pero es la convención para nuevas tools con salida estructurada. Los schemas de registro son shapes, no z.object(...); puedes compartir .shape con los objetos usados para validar.
• Declara timeoutMs como un literal entre 1 y 30000; el validador actual inspecciona texto. Describe con precisión si la operación consulta o cambia estado y define idempotent según su comportamiento real, no solo por el verbo HTTP.
• Valida dentro de handler(input, context) con Zod antes de acceder a la API. Restringe formato y longitud según el dominio; codifica cada segmento dinámico con encodeURIComponent y construye las queries con URLSearchParams.
• Para REST usa context.restClient.get o .post. Este cliente está asociado al AbortSignal de la ejecución. No captures un cliente global ni crees otro cliente dentro de la tool. Si necesitas otro método HTTP que el cliente todavía no ofrece, extiéndelo con el cambio mínimo y sus pruebas; no simules el método ni eludas el cliente.
• Fija la ruta según el propósito de la tool. No aceptes URLs completas ni rutas arbitrarias del usuario. El cliente admite únicamente rutas del origen configurado, bloquea redirecciones y limita las respuestas a 2 MiB.
• Valida las respuestas externas relevantes: los genéricos TypeScript no validan JSON. Devuelve un objeto acorde a outputSchema, con los campos necesarios para el usuario. No incluyas raw, headers, tokens o datos personales ajenos al propósito por copiar otras tools.
• El framework transforma el objeto devuelto en un resultado MCP; no construyas manualmente content ni isError dentro del handler. Propaga los fallos; usa los errores existentes de src/framework/errors.ts cuando aporten contexto seguro.
• Registra la tool en el array devuelto por createTools() en src/tools/index.ts, conservando las existentes. Una factory, si resulta útil, no debe capturar el RestClient: el handler lo obtiene del contexto.