Skip to main content
Glama
Soller211

github-updates

by Soller211
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-agent-sol

Un servidor MCP que da a una IA acceso de lectura a los issues y pull requests de GitHub, y un agente (Claude Agent SDK) que lo usa para redactar project updates automáticamente.

 "update de owner/repo de octubre"
            │
            ▼
 ┌──────────────────────┐   herramientas MCP   ┌─────────────────────┐   HTTPS   ┌────────────┐
 │  agent.py            │ ───────────────────▶ │  server.py          │ ────────▶ │ GitHub API │
 │  Claude Agent SDK    │ ◀─────────────────── │  MCP Python SDK     │ ◀──────── │            │
 │  decide y redacta    │       JSON           │  search_issues      │           └────────────┘
 └──────────────────────┘                      │  get_issue          │
                                               └─────────────────────┘

Cómo funciona

  1. agent.py arranca server.py como subproceso y se conecta a él por stdio usando el protocolo MCP.

  2. El servidor anuncia sus herramientas (nombre, descripción, parámetros). Claude las ve como cualquier otra herramienta.

  3. Claude lee tu petición y decide qué buscar, por ejemplo search_issues(repo, "is:pr is:merged merged:2022-10-01..2022-10-31").

  4. El servidor traduce la llamada a la API REST de GitHub, recorta la respuesta a los campos útiles y la devuelve como JSON.

  5. Claude repite los pasos 3–4 las veces que haga falta (hecho, en curso, pendiente, riesgos) y redacta el informe.

La separación es la idea clave: el servidor sabe cómo acceder a GitHub; el agente decide qué hacer. Por eso el servidor sirve también para otros clientes (Claude Code, Claude Desktop, modelos locales).

Related MCP server: AI Project Explorer

Instalación

Requisitos: Python ≥ 3.10 y un token de GitHub.

git clone https://github.com/Soller211/mcp-agent-sol && cd mcp-agent-sol
uv sync                                   # o: python -m venv .venv && .venv/bin/pip install -e .

Token de GitHub: se usa GITHUB_TOKEN; si no existe, el de la CLI gh (gh auth login). Recomendado: un token de solo lectura, ver Seguridad.

Claude: el agente usa tu sesión de Claude Code o la variable ANTHROPIC_API_KEY. Cada informe consume tokens (unos $0.05–0.10 con el modelo por defecto).

Uso del agente

uv run python agent.py "update de Soller211/customTenisDev de octubre 2022"
uv run python agent.py "update semanal de owner/repo" > update.md
uv run python agent.py "¿qué bugs abiertos tiene owner/repo?"

El informe sale por stdout; las llamadas a herramientas y el coste, por stderr. Ejemplo real:

→ search_issues({'query': 'is:pr is:merged merged:2026-09-20..2026-09-27', ...})
→ search_issues({'query': 'is:issue closed:2026-09-20..2026-09-27', ...})
→ search_issues({'query': 'is:pr is:open', ...})
→ search_issues({'query': 'is:issue is:open', ...})
→ get_issue({'number': 18})
→ get_issue({'number': 15})
→ get_issue({'number': 14})
[8 turnos · $0.0628]
# Update: Soller211/customTenisDev (2026-09-20 → 2026-09-27)
**Resumen:** Esta semana se cerró 1 issue de documentación (README) y no se mergeó ningún PR. No hay PRs abiertos. Quedan 5 issues abiertos: 2 bugs, 2 mejoras y 1 bloqueado, que es la integración de la pasarela de pago y está esperando las credenciales del proveedor.

## ✅ Hecho
- [#19](...) Actualizar README con capturas y cómo ejecutar el proyecto (`documentation`), cerrado el 2026-09-27.
...
## ⚠️ Riesgos / bloqueos
- [#18](...) Pasarela de pago bloqueada: según el último comentario, está "esperando credenciales del proveedor de pagos".

El agente solo abre el detalle (get_issue) de lo que parece bloqueado o es un bug: el número de llamadas se adapta a los datos.

Cambiar de modelo: ANTHROPIC_MODEL=claude-sonnet-5 uv run python agent.py "...".

Usar solo el servidor MCP

Claude Code:

claude mcp add github-updates -- /ruta/absoluta/.venv/bin/python /ruta/absoluta/server.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "github-updates": {
      "command": "/ruta/absoluta/.venv/bin/python",
      "args": ["/ruta/absoluta/server.py"]
    }
  }
}

Probarlo a mano con el MCP Inspector: npx @modelcontextprotocol/inspector@0.15.0 .venv/bin/python server.py (ciérralo con Ctrl+C al terminar: puede lanzar comandos). En WSL, abre http://localhost:6274 en el navegador de Windows (con 127.0.0.1 la conexión puede ser rechazada).

Herramientas

Herramienta

Parámetros

Devuelve

search_issues

repo, query (sintaxis de búsqueda de GitHub), limit (≤100)

total_count + lista compacta de issues/PRs

get_issue

repo, number

cuerpo completo + comentarios

Modelos locales (Qwen, vLLM, Ollama)

No probado en este repo todavía; son las vías conocidas.

El servidor es independiente del modelo: cualquier cliente MCP lo puede usar. Ejemplo con Qwen-Agent y un vLLM local:

from qwen_agent.agents import Assistant

bot = Assistant(
    llm={"model": "Qwen/Qwen3-30B-A3B", "model_server": "http://localhost:8000/v1", "api_key": "EMPTY"},
    function_list=[{"mcpServers": {"github": {"command": ".venv/bin/python", "args": ["server.py"]}}}],
)

El agente habla el formato de la API de Anthropic. Para usarlo con un modelo local, pon delante un proxy que lo traduzca, como LiteLLM:

litellm --model hosted_vllm/Qwen/Qwen3-30B-A3B --api_base http://localhost:8000/v1 --port 4000
export ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_API_KEY=local ANTHROPIC_MODEL=hosted_vllm/Qwen/Qwen3-30B-A3B
uv run python agent.py "update semanal de owner/repo"

Modelos pequeños (7B–14B) suelen fallar al encadenar llamadas a herramientas; usa uno de ~30B o más con buen tool calling.

Seguridad

La IA decide qué herramientas llamar, pero solo dentro de lo que este código permite:

  • Solo lectura. El servidor solo hace GET a api.github.com (sin redirecciones) y el agente solo tiene search_issues y get_issue: sin Bash, sin escritura de archivos (tools=[]).

  • Entradas validadas. repo debe tener formato owner/nombre (bloquea rutas como a/b/../../user), y query no admite repo:/org:/user:, OR/AND/NOT ni paréntesis, que permitirían buscar fuera del repo.

  • Aislado de tu configuración. setting_sources=[] y strict_mcp_config=True: el agente ignora ~/.claude, .claude/ del proyecto (y sus hooks) y otros servidores MCP.

  • Contenido no confiable. Issues y comentarios los escribe cualquiera y pueden intentar prompt injection. El prompt le indica tratarlos como datos; al ser de solo lectura, lo peor posible es un informe engañoso. Revisa el informe antes de publicarlo.

Usa un token de mínimo privilegio. El token de gh suele tener permisos de escritura y administración. Crea un fine-grained token con acceso solo a los repos que quieras y permisos Issues: Read y Pull requests: Read, y expórtalo:

export GITHUB_TOKEN=github_pat_...

Así, aunque el código cambiara, GitHub no permitiría escribir ni leer otros repos.

Lo que el agente envía al modelo (títulos, cuerpos y comentarios de issues) sale de tu máquina hacia Anthropic, o hacia el servidor del modelo que configures.

Límites y siguientes pasos

  • Una sola página de búsqueda (máx. 100 resultados por consulta). Siguiente paso: paginación.

  • La búsqueda de GitHub permite ~30 peticiones/minuto con token. Siguiente paso si se usa a escala: caché.

  • Solo lectura. Siguiente paso posible: herramienta para publicar el informe como comentario en un issue.

  • Los informes los redacta un LLM: revísalos antes de compartirlos.

Desarrollo

uv run pytest -q

Licencia

MIT

Available Tools

2 tools
get_issueC

Detalle de un issue o pull request: cuerpo completo y comentarios.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYes
numberYes

TDQS

C2.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It does disclose the return content (full body plus comments), which is useful behavioral context beyond a bare read. However, it says nothing about read-only nature, permissions, or not-found/error behavior.

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?

A single tight sentence with the resource and returned payload front-loaded. No filler, though it is arguably too terse given the undocumented parameters.

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

Completeness2/5

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

For a two-required-parameter fetch tool with no annotations, no output schema, and no parameter descriptions, the definition is under-specified. It omits parameter formats, error cases, and any relation to the sibling search tool.

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

Parameters2/5

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

Schema description coverage is 0% and neither 'repo' nor 'number' is explained in the description. The agent gets no hint about accepted repo format (owner/name?) or whether 'number' is the issue/PR identifier, so the description fails to compensate for the coverage gap.

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 ('get' implied by 'Detalle de') and resource (issue or pull request), and enumerates the payload ('cuerpo completo y comentarios'). It is clear what the tool returns, though it does not explicitly distinguish itself from the sibling search_issues.

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

Usage Guidelines2/5

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

There is no statement of when to use this tool versus search_issues, nor any precondition or exclusion. An agent must infer that 'Detalle' means single-item retrieval by number, but no routing guidance is given.

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

search_issuesA

Busca issues y pull requests de un repo con la sintaxis de búsqueda de GitHub.

repo: "owner/nombre". query: filtros de GitHub tal cual. Ejemplos: "is:pr is:merged merged:2022-10-01..2022-10-31", "is:issue is:open", "is:issue closed:>=2026-09-20", "label:bug", texto libre. Incluye siempre is:issue o is:pr (GitHub lo exige con tokens fine-grained). No admite repo:/org:/user:, OR/AND/NOT ni paréntesis: haz una búsqueda por cada consulta. limit: máximo de resultados (tope 100). Devuelve total_count (total real en GitHub) e items (como mucho limit).

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYes
limitNo
queryNo

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations the description carries the full burden and does well: it discloses the required is:issue/is:pr token constraint, the unsupported qualifiers, the limit cap of 100, and the return shape (total_count vs items). It does not state read-only/no-side-effect behavior or rate limits, which keeps it short of a 5.

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?

Purpose is front-loaded, then parameters are described in a compact per-field layout. The query examples are numerous but each illustrates a distinct supported qualifier, so the length is mostly earned.

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

Completeness5/5

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

For a 3-param search tool with no output schema and no annotations, the description supplies query syntax, constraints, limits, and even the return structure (total_count, items). An agent has everything needed to call it correctly.

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

Parameters5/5

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

Schema coverage is 0%, yet the description documents all three parameters: repo format ('owner/nombre'), the full query syntax with examples, and limit ('máximo de resultados, tope 100'). It fully compensates for the empty schema.

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?

States a specific verb ('Busca') and resource ('issues y pull requests de un repo') plus the mechanism (sintaxis de búsqueda de GitHub). It is inherently distinguishable from the sibling get_issue, which fetches a single item, while this searches many.

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 concrete query examples and explicit exclusions (no repo:/org:/user:, no OR/AND/NOT, no parentheses — run one search per query). It does not explicitly compare against get_issue, but the constraints on how to use it are unusually thorough.

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. 2 tool updatesv0.1.0
    • First observedget_issue
    • First observedsearch_issues
Deploy Server
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct roles: search_issues performs broad filtered queries and returns summaries, while get_issue fetches full detail (body + comments) for a single item. There is no realistic way to confuse them.

Naming Consistency5/5

Both names follow a consistent snake_case verb_noun pattern (search_issues, get_issue), which matches well-known GitHub API conventions. Adding a read_ or fetch_ variant would be the only nitpick, but the set is fully consistent.

Tool Count3/5

Only 2 tools is thin even for a read-only server; a list/get pair for a repo's issues (without resorting to search syntax) would be a natural third tool. It is defensible as a focused search-and-read helper, but it sits at the borderline of being under-scoped.

Completeness3/5

The surface covers search and single-item retrieval, but has notable gaps for a server named 'github-updates': no way to comment, create, edit, or close issues/PRs, and no straightforward list-issues-in-repo tool for users who don't know GitHub search qualifiers. It is usable as a read-only viewer but incomplete as a lifecycle surface.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • github-issues-mcp

    nukathotipoojitha
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to list, search, and inspect issues on any public GitHub repository via natural language.
    MIT

  • AI Project Explorer

    shravanthivr
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to discover and interact with GitHub repositories through standardized MCP tools, allowing exploration and retrieval of project information without direct API calls.
    -

  • io.github.DJeswar/github

    DJeswar
    A
    license
    A
    quality
    B
    maintenance
    Lets agents read a GitHub repository's live issues through read-only tools for listing, filtering, fetching details with comments and cross-references, searching, and exploring labels and milestones, with transparent pagination and provenance notes.
    5
    MIT