MCP de la API GraphQL de GitHub

Una herramienta basada en MCP (Protocolo de Control de Modelos) para consultar y usar la API GraphQL de GitHub. Este proyecto proporciona un servidor que permite explorar el esquema GraphQL de GitHub y ejecutar consultas GraphQL mediante herramientas cliente MCP (como Claude AI).

¿Por qué usar la API GraphQL de GitHub?

La API GraphQL de GitHub ofrece ventajas significativas sobre las API REST tradicionales:

Recuperación precisa de datos : GraphQL permite a los clientes especificar exactamente qué campos necesitan, evitando el exceso de datos.
Consumo de tokens reducido : al solicitar solo los campos necesarios, el tamaño de la respuesta de la API se reduce significativamente, lo que disminuye el consumo de tokens del modelo de IA.
Solicitud única de datos relacionados : una consulta puede recuperar varios recursos relacionados, lo que reduce la cantidad de solicitudes
Autodocumentación : a través de su sistema de documentación integrado, puede consultar y comprender directamente el esquema de API sin documentación externa.
Sistema de tipos fuerte : proporciona verificación de tipos, lo que reduce errores

Este proyecto aprovecha estas ventajas para proporcionar herramientas que lo ayuden a explorar de manera efectiva el esquema de API GraphQL de GitHub y ejecutar consultas optimizadas, proporcionando a los asistentes de IA capacidades eficientes de recuperación de datos de GitHub.

Escenarios de aplicación

Funciones básicas

Esta herramienta implementa fácilmente las siguientes operaciones comunes:

Consulta de información básica del repositorio : obtenga el nombre del repositorio, la descripción, el número de estrellas, la lista de ramas y otra información básica
Recuperación de datos de problemas : consulte listas de problemas, detalles o contenido de comentarios para repositorios específicos
Acceso al perfil de usuario : recupera perfiles personales de los usuarios, estadísticas de contribución y otra información pública
Vista del estado de la solicitud de extracción : obtenga el estado básico de la solicitud de extracción, el contenido de los comentarios y la información de combinación
Consulta de dependencias del proyecto : recupera listas de paquetes de dependencia del proyecto e información de la versión

Funciones avanzadas exploratorias

Con las capacidades de consulta flexibles de GraphQL, también puedes intentar implementar las siguientes funciones de análisis avanzadas:

Análisis de tendencias de contribución del repositorio : analice la frecuencia de actualización del código y la participación de los contribuyentes agregando datos de confirmación y evaluando la actividad del proyecto.
Gestión y clasificación de problemas : organice los datos de los problemas según las condiciones personalizadas, descubra problemas que necesitan un manejo prioritario y mejore la eficiencia de la gestión de proyectos.
Análisis de patrones de revisión de código : analice los comentarios de PR y revise los procesos, identifique patrones de problemas comunes y optimice el flujo de trabajo de revisión de código
Visualización de la red de colaboradores : cree relaciones de colaboración entre los colaboradores del proyecto, descubra colaboradores clave y áreas de especialización
Evaluación del estado de las dependencias : evaluar la frecuencia de actualización y los posibles problemas de seguridad de las dependencias del proyecto, brindando sugerencias para la gestión de las dependencias.

Características

Consulta de tipos de raíz de esquema GraphQL de GitHub (Consulta/Mutación)
Obtenga documentación detallada para tipos específicos
Consultar documentación y parámetros para campos específicos
Ejecute consultas de API GraphQL de GitHub directamente, recuperando con precisión los datos necesarios y reduciendo el consumo de tokens
Soporte bilingüe (inglés/chino)

Prerrequisitos

Python 3.10 o superior
Token de acceso personal de GitHub (para acceder a la API de GitHub)
Poesía (herramienta de gestión de dependencias recomendada)

Instalación

Clonar el repositorio:

git clone https://github.com/wanzunz/github_graphql_api_mcp.git
cd github_graphql_api_mcp

Instalar dependencias usando Poetry:

# If you haven't installed Poetry yet, install it first:
# curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies using Poetry
poetry install

# Activate the virtual environment
poetry shell

Si no utilizas poesía, puedes utilizar el método tradicional:

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/MacOS
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

Configurar variables de entorno:

Crea un archivo .env y agrega tu token de acceso personal de GitHub:

GITHUB_TOKEN="your_github_token_here"

Puedes crearlo copiando el archivo .env.example :

cp .env.example .env

Luego edita el archivo .env , reemplazando your_github_token_here con tu token de GitHub real.

Uso

Iniciando el servidor

Asegúrate de tener activado el entorno virtual Poetry ( poetry shell ), luego:

Correr

python github_graphql_api_mcp_server.py

Una vez iniciado el servidor, puedes conectarte a él a través de un cliente MCP (como Claude AI).

Configurar en Claude Desktop

Puede configurar este servidor MCP en la aplicación de escritorio Claude para iniciarlo con un solo clic:

Abra la aplicación de escritorio de Claude
Vaya a configuración, busque la sección de configuración del servidor MCP
Agregue la siguiente configuración (modifique según su ruta actual):

{
    "mcpServers": {
        "github_mcp": {
            "command": "<your Python interpreter path>",
            "args": [
                "--directory",
                "<project path>",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

Ejemplo de configuración:

{
    "mcpServers": {
        "github_mcp": {
            "command": "/usr/bin/python3",
            "args": [
                "--directory",
                "/home/user/projects/github_graphql_api_mcp/",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

Si utiliza conda u otras herramientas de gestión del entorno:

{
    "mcpServers": {
        "github_mcp": {
            "command": "/opt/miniconda3/bin/python",
            "args": [
                "--directory",
                "/Users/username/github/github_graphql_api_mcp/",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

Después de la configuración, puede iniciar el servidor MCP directamente desde la aplicación de escritorio Claude sin tener que iniciarlo manualmente.

Herramientas disponibles

El servidor proporciona las siguientes herramientas:

print_type_field : Campos de consulta de tipos raíz del esquema GraphQL de GitHub
graphql_schema_root_type : Obtener documentación para tipos raíz (Consulta/Mutación)
graphql_schema_type : consulta la documentación para tipos específicos
call_github_graphql : Ejecutar consultas de la API GraphQL de GitHub

Ejemplos de uso

Después de conectarse al servidor con un cliente MCP, puede:

Documentación del tipo raíz de consulta:
Use the graphql_schema_root_type tool, parameter type_name="QUERY"
Campos de consulta de tipos específicos:
Use the print_type_field tool, parameters type_name="QUERY", type_fields_name="repository"
Consultar documentación para tipos específicos:
Use the graphql_schema_type tool, parameter type_name="Repository"
Ejecutar consultas GraphQL:
Use the call_github_graphql tool, parameter: graphql=""" query { viewer { login name } } """

Ejemplo de captura de pantalla

A continuación se muestra un ejemplo del uso de la API GraphQL de GitHub MCP con Claude:

Notas

Asegúrese de que su token de GitHub tenga los permisos adecuados antes de usarlo
El token se almacena en el archivo .env , que no debe enviarse a los sistemas de control de versiones.
Las consultas deben cumplir con los límites de uso de la API de GitHub

Licencia

Este proyecto está licenciado bajo la Licencia MIT, una licencia muy permisiva que permite a los usuarios usar, modificar, distribuir y comercializar libremente este software, siempre que conserven el aviso de copyright y la declaración de licencia.

Consulte la licencia MIT para conocer los términos detallados.

GitHub GraphQL API MCP

Integrations