Communitygithub.com

ASoudy/AGS

Guía para crear servidores MCP (Model Context Protocol) de alta calidad que permitan a los LLMs interactuar con servicios externos mediante herramientas bien diseñadas. Úsalo al construir servidores MCP para integrar APIs o servicios externos, ya sea en Python (FastMCP) o Node/TypeScript (MCP SDK).

¿Qué es AGS?

Esta habilidad proporciona una guía completa y detallada para el desarrollo de servidores MCP (Model Context Protocol) de alta calidad. Está diseñada para desarrolladores que desean construir servidores que permitan a modelos de lenguaje grandes (LLMs) interactuar con servicios externos a través de herramientas bien diseñadas. La guía cubre todo el proceso, desde la investigación y planificación inicial, pasando por la implementación con TypeScript (recomendado) o Python, hasta la revisión, pruebas y creación de evaluaciones. Se enfatiza la importancia de un diseño centrado en el agente, con nombres de herramientas descriptivos, mensajes de error accionables y un equilibrio entre la cobertura completa de la API y herramientas de flujo de trabajo especializadas. La habilidad incluye referencias a las mejores prácticas de MCP, guías de implementación específicas para cada lenguaje, y una guía para crear evaluaciones integrales que verifiquen la efectividad del servidor. Es compatible con los SDKs oficiales de TypeScript y Python, y los transportes Streamable HTTP y stdio.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Guía de Desarrollo de Servidores MCP

Resumen

Crea servidores MCP (Model Context Protocol) que permitan a los LLMs interactuar con servicios externos a través de herramientas bien diseñadas. La calidad de un servidor MCP se mide por lo bien que permite a los LLMs realizar tareas del mundo real.


Proceso

🚀 Flujo de Trabajo de Alto Nivel

La creación de un servidor MCP de alta calidad implica cuatro fases principales:

Fase 1: Investigación y Planificación Profunda

1.1 Comprender el Diseño Moderno de MCP

Cobertura de API vs. Herramientas de Flujo de Trabajo: Equilibra la cobertura completa de endpoints de API con herramientas de flujo de trabajo especializadas. Las herramientas de flujo de trabajo pueden ser más convenientes para tareas específicas, mientras que la cobertura completa brinda a los agentes flexibilidad para componer operaciones. El rendimiento varía según el cliente: algunos clientes se benefician de la ejecución de código que combina herramientas básicas, mientras que otros funcionan mejor con flujos de trabajo de nivel superior. Cuando no estés seguro, prioriza la cobertura completa de la API.

Nombres y Descubrimiento de Herramientas: Los nombres de herramientas claros y descriptivos ayudan a los agentes a encontrar las herramientas adecuadas rápidamente. Usa prefijos consistentes (por ejemplo, github_create_issue, github_list_repos) y nombres orientados a la acción.

Gestión de Contexto: Los agentes se benefician de descripciones de herramientas concisas y la capacidad de filtrar/paginar resultados. Diseña herramientas que devuelvan datos enfocados y relevantes. Algunos clientes admiten la ejecución de código, lo que puede ayudar a los agentes a filtrar y procesar datos de manera eficiente.

Mensajes de Error Accionables: Los mensajes de error deben guiar a los agentes hacia soluciones con sugerencias específicas y próximos pasos.

1.2 Estudiar la Documentación del Protocolo MCP

Navegar por la especificación MCP:

Comienza con el mapa del sitio para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml

Luego obtén páginas específicas con el sufijo .md para formato markdown (por ejemplo, https://modelcontextprotocol.io/specification/draft.md).

Páginas clave a revisar:

  • Resumen de la especificación y arquitectura
  • Mecanismos de transporte (HTTP transmisible, stdio)
  • Definiciones de herramientas, recursos y avisos

1.3 Estudiar la Documentación del Framework

Stack recomendado:

  • Lenguaje: TypeScript (soporte SDK de alta calidad y buena compatibilidad en muchos entornos de ejecución, por ejemplo, MCPB. Además, los modelos de IA son buenos generando código TypeScript, beneficiándose de su amplio uso, tipado estático y buenas herramientas de linting)
  • Transporte: HTTP transmisible para servidores remotos, usando JSON sin estado (más simple de escalar y mantener, en oposición a sesiones con estado y respuestas en streaming). stdio para servidores locales.

Cargar documentación del framework:

Para TypeScript (recomendado):

  • SDK TypeScript: Usa WebFetch para cargar https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • ⚡ Guía de TypeScript - Patrones y ejemplos de TypeScript

Para Python:

  • SDK Python: Usa WebFetch para cargar https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Guía de Python - Patrones y ejemplos de Python

1.4 Planificar tu Implementación

Entender la API: Revisa la documentación de la API del servicio para identificar endpoints clave, requisitos de autenticación y modelos de datos. Usa búsqueda web y WebFetch según sea necesario.

Selección de Herramientas: Prioriza la cobertura completa de la API. Enumera los endpoints a implementar, comenzando con las operaciones más comunes.


Fase 2: Implementación

2.1 Configurar la Estructura del Proyecto

Consulta las guías específicas de cada lenguaje para la configuración del proyecto:

2.2 Implementar la Infraestructura Principal

Crea utilidades compartidas:

  • Cliente API con autenticación
  • Ayudantes para el manejo de errores
  • Formateo de respuestas (JSON/Markdown)
  • Soporte de paginación

2.3 Implementar Herramientas

Para cada herramienta:

Esquema de Entrada:

  • Usa Zod (TypeScript) o Pydantic (Python)
  • Incluye restricciones y descripciones claras
  • Agrega ejemplos en las descripciones de los campos

Esquema de Salida:

  • Define outputSchema cuando sea posible para datos estructurados
  • Usa structuredContent en las respuestas de las herramientas (característica del SDK de TypeScript)
  • Ayuda a los clientes a comprender y procesar las salidas de las herramientas

Descripción de la Herramienta:

  • Resumen conciso de la funcionalidad
  • Descripciones de los parámetros
  • Esquema del tipo de retorno

Implementación:

  • Async/await para operaciones de E/S
  • Manejo adecuado de errores con mensajes accionables
  • Soporte de paginación cuando corresponda
  • Devuelve tanto contenido de texto como datos estructurados al usar SDKs modernos

Anotaciones:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

Fase 3: Revisar y Probar

3.1 Calidad del Código

Revisa:

  • Sin código duplicado (principio DRY)
  • Manejo de errores consistente
  • Cobertura total de tipos
  • Descripciones claras de las herramientas

3.2 Compilar y Probar

TypeScript:

  • Ejecuta npm run build para verificar la compilación
  • Prueba con MCP Inspector: npx @modelcontextprotocol/inspector

Python:

  • Verifica la sintaxis: python -m py_compile tu_servidor.py
  • Prueba con MCP Inspector

Consulta las guías específicas de cada lenguaje para enfoques de prueba detallados y listas de verificación de calidad.


Fase 4: Crear Evaluaciones

Después de implementar tu servidor MCP, crea evaluaciones integrales para probar su efectividad.

Carga la ✅ Guía de Evaluación para obtener pautas completas de evaluación.

4.1 Comprender el Propósito de la Evaluación

Usa las evaluaciones para probar si los LLMs pueden usar efectivamente tu servidor MCP para responder preguntas realistas y complejas.

4.2 Crear 10 Preguntas de Evaluación

Para crear evaluaciones efectivas, sigue el proceso descrito en la guía de evaluación:

  1. Inspección de Herramientas: Enumera las herramientas disponibles y comprende sus capacidades
  2. Exploración de Contenido: Usa operaciones de SOLO LECTURA para explorar los datos disponibles
  3. Generación de Preguntas: Crea 10 preguntas complejas y realistas
  4. Verificación de Respuestas: Resuelve cada pregunta tú mismo para verificar las respuestas

4.3 Requisitos de Evaluación

Asegúrate de que cada pregunta sea:

  • Independiente: Que no dependa de otras preguntas
  • Solo lectura: Que solo requiera operaciones no destructivas
  • Compleja: Que requiera múltiples llamadas a herramientas y exploración profunda
  • Realista: Basada en casos de uso reales que interesarían a los humanos
  • Verificable: Respuesta única y clara que pueda verificarse mediante comparación de cadenas
  • Estable: La respuesta no cambiará con el tiempo

4.4 Formato de Salida

Crea un archivo XML con esta estructura:

<evaluation>
  <qa_pair>
    <question>Encuentra discusiones sobre lanzamientos de modelos de IA con nombres en código de animales. Un modelo necesitaba una designación de seguridad específica que usa el formato ASL-X. ¿Qué número X se estaba determinando para el modelo nombrado después de un gato salvaje manchado?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Más qa_pairs... -->
</evaluation>

Archivos de Referencia

📚 Biblioteca de Documentación

Carga estos recursos según sea necesario durante el desarrollo:

Documentación Principal de MCP (Cargar Primero)

  • Protocolo MCP: Comienza con el mapa del sitio en https://modelcontextprotocol.io/sitemap.xml, luego obtén páginas específicas con el sufijo .md
  • 📋 Mejores Prácticas MCP - Pautas universales de MCP que incluyen:
    • Convenciones de nombres de servidores y herramientas
    • Pautas de formato de respuestas (JSON vs Markdown)
    • Mejores prácticas de paginación
    • Selección de transporte (HTTP transmisible vs stdio)
    • Estándares de seguridad y manejo de errores

Documentación del SDK (Cargar Durante la Fase 1/2)

  • SDK Python: Obtener de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • SDK TypeScript: Obtener de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guías de Implementación Específicas por Lenguaje (Cargar Durante la Fase 2)

  • 🐍 Guía de Implementación de Python - Guía completa de Python/FastMCP con:

    • Patrones de inicialización del servidor
    • Ejemplos de modelos Pydantic
    • Registro de herramientas con @mcp.tool
    • Ejemplos funcionales completos
    • Lista de verificación de calidad
  • ⚡ Guía de Implementación de TypeScript - Guía completa de TypeScript con:

    • Estructura del proyecto
    • Patrones de esquema Zod
    • Registro de herramientas con server.registerTool
    • Ejemplos funcionales completos
    • Lista de verificación de calidad

Guía de Evaluación (Cargar Durante la Fase 4)

  • ✅ Guía de Evaluación - Guía completa de creación de evaluaciones con:
    • Pautas para la creación de preguntas
    • Estrategias de verificación de respuestas
    • Especificaciones de formato XML
    • Preguntas y respuestas de ejemplo
    • Ejecución de una evaluación con los scripts proporcionados

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Skills relacionados