agent-friend

Adaptador universal de herramientas — el decorador @tool exporta funciones de Python a OpenAI, Claude, Gemini, MCP, JSON Schema. Audita costos de tokens.

GitHub

Prueba este MCPPatrocinado

Documentación

agent-friend

Los esquemas MCP inflados degradan la precisión de selección de herramientas en 3x — y queman tokens antes de que tu agente haga algo útil. El benchmark de Scalekit: la precisión cae del 43% al 14% con esquemas verbosos. El servidor MCP promedio desperdicia más de 2,500 tokens solo en descripciones.

pip install agent-friend
agent-friend fix server.json > server_fixed.json

El MCP oficial de GitHub: 20,444 tokens → ~14,000. Mismas herramientas. Más precisión. Sin configuración.

Corrección

Corrige automáticamente problemas de esquema — nombres, descripciones verbosas, restricciones faltantes:

agent-friend fix tools.json > tools_fixed.json

# agent-friend fix v0.59.0
#
#   Applied fixes:
#     ✓ create-page -> create_page (name)
#     ✓ Stripped "This tool allows you to " from search description
#     ✓ Trimmed get_database description (312 -> 198 chars)
#     ✓ Added properties to undefined object in post_page.properties
#
#   Summary: 12 fixes applied across 8 tools
#   Token reduction: 2,450 -> 2,180 tokens (-11.0%)

6 reglas de corrección: nombres (kebab→snake_case), prefijos verbosos, descripciones largas, descripciones de parámetros largas, parámetros redundantes, esquemas indefinidos. Usa --dry-run para previsualizar, --diff para ver cambios, --only names,prefixes para seleccionar reglas.

Calificación

Mira cómo tu servidor puntúa frente a otros 201 (A+ hasta F):

agent-friend grade --example notion

# Overall Grade: F
# Score: 19.8/100
# Tools: 22 | Tokens: 4483

El servidor MCP oficial de Notion. 22 herramientas. Calificación F. Cada nombre de herramienta viola las convenciones de nomenclatura de MCP. 5 esquemas indefinidos.

5 servidores reales incluidos — espectro de calificaciones de F a A+:

Servidor	Herramientas	Calificación	Tokens
`--example notion`	22	F (19.8)	4,483
`--example filesystem`	11	D+ (64.9)	1,392
`--example github`	12	C+ (79.6)	1,824
`--example puppeteer`	7	A- (91.2)	382
`--example slack`	8	A+ (97.3)	721

Hemos calificado 201 servidores MCP — los 4 más populares obtienen D o menos. 3,991 herramientas, 512K tokens analizados.

Pruébalo en vivo: Mira la calificación F de Notion — pega tu propio esquema, obtén A–F al instante.

Validar

Detecta errores de esquema antes de que fallen en producción:

agent-friend validate tools.json

# agent-friend validate — schema correctness report
#
#   ✓ 3 tools validated, 0 errors, 0 warnings
#
#   Summary: 3 tools, 0 errors, 0 warnings — PASS

13 verificaciones: nombres faltantes, tipos inválidos, parámetros requeridos huérfanos, enums malformados, nombres duplicados, objetos anidados sin tipo, detección de anulación de prompts. Usa --strict para tratar advertencias como errores, --json para CI.

O usa el validador web gratuito — sin necesidad de instalación.

Auditoría

Mira exactamente a dónde van tus tokens:

agent-friend audit tools.json

# agent-friend audit — tool token cost report
#
#   Tool                    Description      Tokens (est.)
#   get_weather             67 chars        ~79 tokens
#   search_web              145 chars       ~99 tokens
#   send_email              28 chars        ~79 tokens
#   ──────────────────────────────────────────────────────
#   Total (3 tools)                        ~257 tokens
#
#   Format comparison (total):
#     openai        ~279 tokens
#     anthropic     ~257 tokens
#     google        ~245 tokens  <- cheapest
#     mcp           ~257 tokens

Acepta formatos OpenAI, Anthropic, MCP, Google o JSON Schema. Detección automática.

El pipeline de calidad: validate (¿correcto?) → audit (¿costoso?) → optimize (sugerencias) → fix (reparación automática) → grade (boletín de calificaciones).

Escribe una vez, despliega en todas partes

from agent_friend import tool

@tool
def get_weather(city: str, units: str = "celsius") -> dict:
    """Get current weather for a city."""
    return {"city": city, "temp": 22, "units": units}

get_weather.to_openai()      # OpenAI function calling
get_weather.to_anthropic()   # Claude tool_use
get_weather.to_google()      # Gemini
get_weather.to_mcp()         # Model Context Protocol
get_weather.to_json_schema() # Raw JSON Schema

Una definición de función. Cinco formatos de frameworks. Sin bloqueo de proveedor.

from agent_friend import tool, Toolkit

kit = Toolkit([search, calculate])
kit.to_openai()   # Both tools, OpenAI format
kit.to_mcp()      # Both tools, MCP format

CI / GitHub Action

Verificación de presupuesto de tokens para tu pipeline — como verificaciones de tamaño de bundle, pero para esquemas de herramientas de IA:

- uses: 0-co/agent-friend@main
  with:
    file: tools.json
    validate: true        # check schema correctness first
    threshold: 1000       # fail if total tokens exceed budget
    grade: true           # combined report card (A+ through F)
    grade_threshold: 80   # fail if score < 80

agent-friend grade tools.json --threshold 90  # exit code 1 if below 90
agent-friend audit tools.json --threshold 500  # exit code 2 if over budget

Hook de pre-commit

Califica y valida tu esquema MCP en cada commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/0-co/agent-friend
    rev: v0.209.0
    hooks:
      - id: agent-friend-grade      # fail if score < 60 (default)
      - id: agent-friend-validate   # fail on any structural error

Anula el umbral:

      - id: agent-friend-grade
        args: ["--threshold", "80"]  # fail if score < 80

Hook de Claude Code

Verifica automáticamente las calificaciones cuando agregas servidores MCP a Claude Code:

mkdir -p ~/.claude/hooks
curl -sL https://0-co.github.io/company/claude-code-hook.sh -o ~/.claude/hooks/af-check.sh
chmod +x ~/.claude/hooks/af-check.sh

Agrega a ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [{
      "matcher": ".",
      "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/af-check.sh"}]
    }]
  }
}

Ahora cada vez que agregas un servidor MCP a Claude Code, ves su calificación. Consulta Discusión #191 para más detalles.

Inicia un nuevo servidor MCP

Usa mcp-starter — un repositorio plantilla de GitHub que genera un nuevo servidor preconfigurado para A+. Incluye hook de pre-commit de agent-friend y calificación de CI.

API REST

Califica esquemas sin instalar el paquete. Disponible en http://89.167.39.157:8082:

# Grade tools from a JSON body
curl -X POST http://89.167.39.157:8082/v1/grade \
  -H 'Content-Type: application/json' \
  -d '[{"name": "search", "description": "Search the web", "parameters": {"type": "object", "properties": {"query": {"type": "string", "description": "Search query"}}, "required": ["query"]}}]'

# Grade a remote schema by URL
curl "http://89.167.39.157:8082/v1/grade?url=https://example.com/schema.json"

Devuelve {"score": 92.0, "grade": "A-", "tool_count": 1, "total_tokens": 43, ...}. CORS habilitado. Fuente: api_server.py.

# CI pass/fail check (200=pass, 422=fail)
curl "http://89.167.39.157:8082/v1/check?url=https://example.com/schema.json&threshold=80"

# README badge redirect (shields.io)
curl -L "http://89.167.39.157:8082/badge?repo=owner/repo-name"

Endpoints: /v1/grade, /v1/check?url=...&threshold=80, /v1/servers, /badge?repo=....

También incluido

51 herramientas integradas — memoria, búsqueda, ejecución de código, bases de datos, HTTP, caché, colas, máquinas de estado, búsqueda vectorial y más. Todo stdlib, cero dependencias externas. Consulta TOOLS.md para la lista completa.

Runtime de agente — clase Friend para conversaciones de múltiples turnos con uso de herramientas en 5 proveedores: OpenAI, Anthropic, OpenRouter, Ollama y BitNet (inferencia de CPU de 1 bit de Microsoft).

CLI — REPL interactivo, tareas de una sola ejecución, streaming. Ejecuta agent-friend --help.

¿Versión alojada?

La API REST en http://89.167.39.157:8082 es gratuita con límites de tasa. Si quieres acceso ilimitado a la API, webhooks de CI o alertas por correo cuando tu puntuación de esquema baje — cuéntanoslo en la Discusión #188. Lo construiremos si hay demanda.

Construido por una IA, en vivo en Twitch

Todo este proyecto es construido y mantenido por un agente de IA autónomo, transmitido 24/7 en twitch.tv/0coceo.

Discusiones · Tabla de clasificación · Herramientas web · Bluesky · Dev.to