Skip to main content
Glama
DalilaMiglio

AcuMiglio MCP GitHub Agent

by DalilaMiglio

🪑 AcuMiglio MCP GitHub Agent

AcuMiglio MCP GitHub Agent es un servidor MCP (Model Context Protocol) desarrollado con TypeScript que permite a un agente de inteligencia artificial interactuar con GitHub mediante lenguaje natural. El usuario puede realizar operaciones sobre GitHub sin ejecutar manualmente llamadas a la API. El LLM interpreta la solicitud, selecciona el tool MCP apropiado y el servidor ejecuta la operación mediante Octokit y GitHub API.

Related MCP server: mcp-server-github

🎯 Objetivo

El objetivo del proyecto es implementar un MCP Server funcional capaz de conectar un agente de IA con GitHub. AcuMiglio utiliza una identidad inspirada en una tienda de muebles ficticia, mientras que el objetivo técnico del proyecto es demostrar la integración: Usuario → Antigravity → LLM → MCP Server → Tools → Octokit → GitHub API.

✨ ¿Por qué es útil?

Permite realizar tareas habituales de GitHub utilizando lenguaje natural. Ejemplos:

  • Crear repositorios.

  • Consultar repositorios.

  • Crear issues.

  • Consultar issues.

  • Crear o actualizar archivos mediante commits. En lugar de interactuar directamente con la API de GitHub, el usuario puede escribir una instrucción como:

Creá un issue en mi repositorio indicando que debemos actualizar el catálogo de muebles. El LLM interpreta la intención y selecciona el tool correspondiente.


🏗️ Arquitectura

Usuario
   ↓
Antigravity (Host)
   ↓
LLM
   ↓
MCP Client
   ↓
AcuMiglio MCP Server
   ↓
Tools
   ↓
Schemas Zod
   ↓
GitHub Operations
   ↓
Octokit
   ↓
GitHub API

Flujo de una solicitud

  1. El usuario escribe una instrucción en lenguaje natural.

  2. El LLM interpreta la intención.

  3. El LLM analiza las descripciones de los tools disponibles.

  4. Selecciona el tool apropiado.

  5. Zod valida los parámetros.

  6. El MCP Server ejecuta la operación.

  7. Octokit realiza la solicitud a GitHub API.

  8. GitHub devuelve el resultado.

  9. El MCP Server transforma la respuesta.

  10. El agente comunica el resultado al usuario.


🧰 Tecnologías

  • Node.js

  • TypeScript

  • Model Context Protocol (MCP)

  • MCP TypeScript SDK

  • Zod

  • Octokit

  • GitHub REST API

  • Vitest

  • Antigravity

  • MCP Inspector

  • dotenv


📁 Estructura

M5-MCP/
├── .agents/
│   └── mcp_config.json
├── src/
│   ├── tools/
│   │   ├── create-repository.ts
│   │   ├── create-issue.ts
│   │   ├── list-repositories.ts
│   │   ├── create-commit.ts
│   │   └── list-issues.ts
│   ├── schemas/
│   │   └── index.ts
│   ├── github/
│   │   ├── client.ts
│   │   └── operations.ts
│   ├── errors/
│   │   └── index.ts
│   ├── utils/
│   │   ├── logging.ts
│   │   └── retry.ts
│   ├── server.ts
│   └── types.ts
├── tests/
│   ├── tools.test.ts
│   ├── github.test.ts
│   └── errors.test.ts
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

⚙️ Requisitos

  • Node.js 20 o superior

  • npm

  • Git

  • Cuenta de GitHub

  • Personal Access Token de GitHub

  • Antigravity


🚀 Instalación

1. Clonar el repositorio

git clone URL_DEL_REPOSITORIO

Entrar al proyecto:

cd M5-MCP

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Crear un archivo .env en la raíz:

GITHUB_PERSONAL_ACCESS_TOKEN=tu_token

Nunca se debe subir .env al repositorio. El proyecto incluye .env.example como referencia.

4. Compilar

npm run build

5. Desarrollo

npm run dev

🔐 GitHub Personal Access Token

El servidor necesita autenticarse con GitHub.

El token utilizado debe disponer de los permisos necesarios para las operaciones que se quieran ejecutar, incluyendo acceso de lectura/escritura a repositorios, contenidos e issues. El token debe almacenarse exclusivamente en .env. Nunca debe:

  • hardcodearse en el código;

  • incluirse en el README;

  • almacenarse en commits;

  • exponerse mediante logs.

Si un token se publica accidentalmente, debe revocarse inmediatamente.


🤖 Configuración con Antigravity

El proyecto utiliza Antigravity como host del MCP Server.

Ejemplo:

{
  "mcpServers": {
    "acumiglio-mcp": {
      "command": "node",
      "args": ["dist/src/server.js"],
      "cwd": "RUTA_ABSOLUTA_AL_PROYECTO"
    }
  }
}

cwd establece la raíz desde la que se ejecuta el servidor, permitiendo que dotenv encuentre correctamente el archivo .env. No debe colocarse el token real dentro de este archivo. Antes de utilizar Antigravity:

npm install
npm run build

🛠️ Tools

1. create-repository

Crea un repositorio en la cuenta autenticada.

Parámetros

  • name: string — nombre del repositorio.

  • description: string opcional — descripción.

  • private: boolean — determina su visibilidad.

Prompt

Creá un repositorio público llamado acumiglio-catalogo para almacenar el catálogo digital de muebles.


2. list-repositories

Lista los repositorios de la cuenta autenticada.

Parámetros

  • per_page: number — cantidad de resultados.

  • page: number — página solicitada.

Prompt

Mostrame mis últimos 5 repositorios de GitHub.


3. create-issue

Crea un issue en un repositorio.

Parámetros

  • owner: string — propietario.

  • repo: string — repositorio.

  • title: string — título.

  • body:string opcional — descripción.

Prompt

Creá un issue en acumiglio-catalogo llamado "Agregar colección de sillones" indicando que debemos incorporar los nuevos modelos.


4. list-issues

Consulta los issues de un repositorio.

Parámetros

  • owner: string — propietario.

  • repo: string — repositorio.

  • state: open, closed o all.

  • per_page: number — cantidad máxima.

Prompt

Mostrame los issues abiertos de acumiglio-catalogo.


5. create-commit

Crea o actualiza un archivo y genera un commit.

Parámetros

  • owner: string — propietario.

  • repo: string — repositorio.

  • path: string — ruta del archivo.

  • message: string — mensaje del commit.

  • content: string — contenido.

  • branch: string opcional — rama.

Prompt

Creá README.md en acumiglio-catalogo con una presentación de AcuMiglio y hacé el commit con el mensaje "docs: agregar README".


🛡️ Validación y manejo de errores

Los inputs se validan mediante Zod antes de ejecutar las operaciones. El servidor transforma errores técnicos de GitHub en mensajes comprensibles. Se contemplan, entre otros:

  • 401 — autenticación.

  • 403 — permisos o rate limit.

  • 404 — recurso no encontrado.

  • 422 — datos rechazados.

  • 429 — rate limit. El sistema incorpora retry con exponential backoff para errores temporales y evita ciclos de reintentos inmediatos. Los logs utilizan stderr para evitar interferir con la comunicación MCP mediante stdio.


🧪 Tests

Los tests utilizan Vitest. Ejecutar:

npm run test

El proyecto incluye tests para:

  • schemas de Zod;

  • inputs válidos;

  • inputs inválidos;

  • operaciones de GitHub;

  • mocks de Octokit;

  • autenticación;

  • permisos;

  • recursos inexistentes;

  • transformación de errores. Las operaciones de los tests utilizan mocks y no dependen de llamadas reales a GitHub.


🔍 MCP Inspector

Para probar el servidor sin utilizar un LLM:

npx @modelcontextprotocol/inspector node dist/src/server.js

Inspector permite verificar los tools y ejecutar llamadas directamente.

🧯 Troubleshooting

El MCP Server no inicia

Ejecutar:

npm run build

y revisar errores de TypeScript.

Antigravity no encuentra el servidor

Verificar:

  • ruta del proyecto;

  • cwd;

  • existencia de dist/src/server.js;

  • que el proyecto haya sido compilado.

Falta GITHUB_PERSONAL_ACCESS_TOKEN

Comprobar que existe:

M5-MCP/.env

y que contiene:

GITHUB_PERSONAL_ACCESS_TOKEN=...

GitHub devuelve 401

El token puede ser inválido o haber expirado.

GitHub devuelve 403

El token puede no disponer de permisos suficientes o se alcanzó un rate limit.

GitHub devuelve 404

Comprobar owner y repo.

Los tests fallan

Ejecutar:

npm install
npm run test

🔒 Seguridad

  • .env está excluido mediante .gitignore.

  • El token no está hardcodeado.

  • Los logs evitan exponer credenciales.

  • .env.example no contiene valores reales.

  • Los errores enviados al LLM no incluyen stack traces.

📜 Licencia

MIT

👩‍💻 Proyecto académico

Proyecto Integrador M5 — Especialización Backend. AcuMiglio MCP GitHub Agent.

Available Tools

5 tools
create-commitCrear commit en GitHubA

Crea o actualiza un archivo en un repositorio de GitHub y genera un commit. Usa este tool cuando el usuario quiera crear un archivo, modificar su contenido o guardar cambios mediante un commit.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRuta del archivo dentro del repositorio. Ejemplo: docs/catalogo.md
repoYesRepositorio donde se realizará el commit.
ownerYesUsuario u organización propietaria del repositorio.
branchNoRama donde se realizará el commit. Si no se indica, se utilizará la rama principal.
contentYesContenido completo que se escribirá dentro del archivo.
messageYesMensaje que describe el cambio realizado en el commit.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It discloses that it creates or updates a file and generates a commit, which is useful, but it does not state permission requirements, whether existing files are overwritten, whether the commit is pushed, or any rate limits. A mutation tool needs more disclosure than this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The primary action is front-loaded and the usage condition follows immediately; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The schema is rich and no output schema exists, so return values need not be explained. However, for a mutation operation with no annotations, the description omits important context such as authorization needs, overwrite behavior, and default branch handling, leaving meaningful gaps for an agent calling the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Crea o actualiza un archivo... y genera un commit'), clearly distinguishing it from siblings like create-repository or create-issue, which operate on different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool ('Usa este tool cuando el usuario quiera crear un archivo, modificar su contenido o guardar cambios mediante un commit'), covering the main scenarios. However, it does not name any alternative tools or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-issueCrear issue de GitHubB

Crea un nuevo issue dentro de un repositorio de GitHub. Usa este tool cuando el usuario quiera registrar un problema, tarea, mejora, bug o solicitud dentro de un repositorio.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoDescripción opcional del problema, tarea o mejora del issue.
repoYesNombre del repositorio donde se creará el issue.
ownerYesUsuario u organización propietaria del repositorio en GitHub.
titleYesTítulo claro y breve del issue que se desea crear.

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It implies a write operation but says nothing about authentication requirements, required scopes/permissions, rate limits, idempotency, or what the tool returns after creation — significant gaps for a mutating GitHub tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no padding, with the action front-loaded before the usage cue. Efficient and appropriately sized for a simple four-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All parameters are self-documented and no output schema exists, so the schema side is complete. But with zero annotations on a mutation tool, the description should at minimum note the auth/permission requirement and that the issue is created in the specified repo; that behavioral layer is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so owner, repo, title and body are already documented in the schema. The description adds no format, constraint or usage detail beyond what the schema supplies, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Crea un nuevo issue dentro de un repositorio de GitHub'. That is unambiguous and clearly separable from list-issues/create-commit/create-repository. It lacks any explicit contrast with siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives concrete trigger contexts — registering a problem, task, improvement, bug or request — which is real when-to-use guidance. However it never states when NOT to use it or names an alternative sibling (e.g. list-issues for reading), so it falls short of the 5 bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create-repositoryCrear repositorio de GitHubA

Crea un nuevo repositorio en la cuenta de GitHub autenticada. Usa este tool cuando el usuario solicite crear, generar o iniciar un nuevo repositorio de GitHub.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesNombre del nuevo repositorio de GitHub. Ejemplo: acumiglio-catalogo
privateNoIndica si el repositorio debe ser privado. false crea un repositorio público.
descriptionNoDescripción opcional que explica el propósito del repositorio.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it only hints at auth context via 'cuenta de GitHub autenticada'. It says nothing about side effects, what happens on a duplicate/invalid name, whether the repo name is claimed immediately, or what permissions are required for this write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and followed by the trigger condition, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple 3-parameter create tool with no output schema, and the schema covers parameters well. However, for a mutation tool with zero annotations the description omits failure behavior and any indication of what the call yields (e.g., the created repository), leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter (name, private, description) documented including pattern, length limits and a default, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Crea un nuevo repositorio') and scopes it to the authenticated GitHub account. It is clearly distinguishable from list-repositories/create-issue/create-commit by resource type, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit trigger conditions with synonyms ('cuando el usuario solicite crear, generar o iniciar un nuevo repositorio'), which is solid when-to-use guidance. It offers no when-not conditions, prerequisites, or named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-issuesListar issues de GitHubB

Obtiene los issues de un repositorio de GitHub. Usa este tool cuando el usuario quiera consultar, revisar o listar issues abiertos, cerrados o todos los issues de un repositorio.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesRepositorio cuyos issues se desean consultar.
ownerYesUsuario u organización propietaria del repositorio.
stateNoEstado de los issues a consultar: open, closed o all.open
per_pageNoCantidad máxima de issues a devolver.

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it only says the tool 'obtiene' issues. It does not state that the operation is read-only, whether permissions are required, how pagination works beyond the per_page parameter, or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and followed by a usage trigger. It is efficient, though 'consultar, revisar o listar' is slightly redundant and the state options restate the schema enum.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter list tool with no annotations and no output schema, the description covers purpose and basic usage. It omits behavioral details such as read-only safety and pagination expectations, leaving some gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description hints at filtering by state ('abiertos, cerrados o todos') but adds no format, default, or usage detail beyond what the schema provides. A baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Obtiene los issues de un repositorio de GitHub.' It clearly distinguishes itself from write-oriented siblings like create-issue, but does not explicitly name or contrast with any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear usage context: 'Usa este tool cuando el usuario quiera consultar, revisar o listar issues abiertos, cerrados o todos.' This tells the agent when to invoke it. However, it offers no when-not conditions or explicit alternatives such as create-issue.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-repositoriesListar repositorios de GitHubA

Obtiene y muestra los repositorios de la cuenta de GitHub autenticada. Usa este tool cuando el usuario quiera ver, consultar, buscar o listar sus repositorios.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoNúmero de página de resultados que se desea consultar.
per_pageNoCantidad máxima de repositorios que se desean obtener por página.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. It implicitly conveys read-only behavior ('Obtiene y muestra') and states that a GitHub account must be authenticated, which is useful context, but it says nothing about rate limits, result volume, or pagination behavior. For a tool with zero annotation coverage, this leaves meaningful gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose before the usage trigger, with no redundant filler. The synonym list ('ver, consultar, buscar o listar') is slightly padded but serves keyword-based tool matching, so it largely earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with two fully documented, optional parameters and no output schema, the description covers the essential what-and-when. The main omission is pagination/return-volume context, which is only lightly implied by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (page, per_page) are fully documented with defaults, ranges and meanings in the schema itself. The description adds no additional parameter guidance, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Obtiene y muestra los repositorios') and scopes it to 'la cuenta de GitHub autenticada'. It is clearly distinguishable from the sibling write tools (create-repository, create-issue, create-commit), though it does not name or contrast with any of them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives explicit trigger conditions ('cuando el usuario quiera ver, consultar, buscar o listar sus repositorios'), which is strong when-to-use guidance. However, it offers no when-not-to-use conditions and does not route to alternatives such as list-issues for issue-related queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedcreate-commit
    • First observedcreate-issue
    • First observedcreate-repository
    • First observedlist-issues
    • First observedlist-repositories

TDQS

A3.7/5.0

Scored across 5 tools

Disambiguation5/5

Each tool pairs a distinct verb with a distinct resource (repository, issue, commit), so create-repository vs create-commit vs list-repositories are easy to tell apart with no overlap.

Naming Consistency5/5

All five tools follow a strict verb-noun pattern in lowercase with hyphens (create-repository, list-repositories, create-issue, list-issues, create-commit), giving a fully predictable convention.

Tool Count4/5

Five tools is a lean but well-scoped set for a GitHub agent; each earns its place, though it is slightly thin and would benefit from a few more operations.

Completeness3/5

The surface covers create/list for repositories and issues plus file commits, but lacks any update or delete operations and no pull-request support, so common tasks like closing issues or editing repos would dead-end an agent.

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers