GitHub Assistant MCP

Un pequeño servidor Model Context Protocol (MCP) autocontenido que expone cinco herramientas centradas en lectura a un asistente de codificación con IA (p. ej. OpenCode). Permite al asistente inspeccionar un espacio de trabajo local y obtener un perfil público de GitHub a través de un transporte stdio limpio y aislado.

"Un servidor MCP de GitHub simple para OpenCode."

Tabla de contenidos

• Descripción general

• Cómo funciona (Arquitectura)

• Transporte y ciclo de vida

• Referencia de herramientas

• Modelo de seguridad

• Recorrido por el proyecto

• Configuración

• Compilación y ejecución

• Estructura de archivos

• Limitaciones

Related MCP server: chatgpt-codex-local-mcp

Descripción general

El servidor es un servidor MCP local que OpenCode inicia como proceso hijo. Habla el protocolo MCP a través de stdio (stdin/stdout) y registra cinco herramientas. El asistente llama a esas herramientas; el servidor realiza el trabajo (lecturas del sistema de archivos, un git diff o una llamada a la API de GitHub) y devuelve resultados de texto estructurados.

Todo lo que toca el sistema de archivos está confinado a un único directorio WORKSPACE_ROOT, por lo que el asistente nunca puede leer ni escapar fuera de la carpeta del proyecto.

Cómo funciona (Arquitectura)

┌─────────────────────────┐         stdio (MCP/JSON-RPC)        ┌──────────────────────────────┐
│                         │  ───────────────────────────────▶  │   github-assistant  (this)   │
│     OpenCode / AI       │  tool call: get_github_profile     │                              │
│     Assistant           │                                    │  ┌────────────────────────┐  │
│                         │  ◀───────────────────────────────  │  │      McpServer          │  │
│  - sees 5 tools         │     result (JSON text)             │  │  (server.ts)            │  │
│  - calls them           │                                    │  └───────────┬────────────┘  │
│  - sandbox enforced     │                                    │              │ registerTools  │
└─────────────────────────┘                                    └──────────────┼──────────────┘
                                                                          ▼
                                                         ┌────────────────────────────────┐
                                                         │  tools.ts  (5 tool handlers)   │
                                                         └───┬──────┬──────┬──────┬─────┬──┘
                                          ┌───────────────┘      │      │      │     │
                                          ▼                      ▼      ▼      ▼     ▼
                                   ┌────────────┐        ┌────────────┐ ┌─────────┐ ┌────────────┐
                                   │ github.ts  │        │ workspace.ts│ │ git.ts │ │ paths.ts   │
                                   │ GitHub API │        │ list/read/  │ │ git diff│ │ resolve    │
                                   │ (fetch)   │        │ search      │ │         │ │ sandbox    │
                                   └─────┬──────┘        └─────┬──────┘ └────┬────┘ └─────┬──────┘
                                         │                    │            │           │
                                         ▼                    ▼            ▼           ▼
                                 api.github.com       WORKSPACE_ROOT/*   git CLI    config.ts
                                                        (files only)   (cwd=root)  WORKSPACE_ROOT

Flujo de datos para una sola llamada a herramienta:

Assistant ──JSON-RPC request──▶ McpServer
                                     │
                                     ▼
                               tool handler (tools.ts)
                                     │  validates args with zod
                                     ▼
                          business logic (github / workspace / git / paths)
                                     │  resolveWorkspacePath() enforces sandbox
                                     ▼
                          result helper (result.ts) → { content: [{ type:"text", text }] }
                                     │
                                     ▼
Assistant ◀──JSON-RPC response── McpServer

Transporte y ciclo de vida

• Tipo: local — OpenCode lanza el servidor como proceso hijo.

• Transporte: stdio mediante serveStdio() de @modelcontextprotocol/server/stdio.

• Secuencia de inicio:

  1. Se ejecuta node dist/server.js (declarado en opencode.json) con cwd = ".".

  2. createServer() construye un McpServer llamado github-assistant (v1.0.0).

  3. registerTools(server) conecta las cinco herramientas.

  4. serveStdio(createServer) comienza a leer mensajes JSON-RPC desde stdin y a escribir resultados en stdout.

• Apagado: OpenCode termina el proceso cuando finaliza la sesión.

Debido a que el proceso hereda el directorio de trabajo de OpenCode, WORKSPACE_ROOT se resuelve al directorio del proyecto (path.resolve(process.cwd())).

Referencia de herramientas

Todas las herramientas están registradas en src/tools.ts y devuelven resultados de texto MCP (JSON o texto plano).

1. get_github_profile

Obtiene el perfil público de GitHub del usuario fijo (imshashwatsingh).

• Entradas: ninguna

• Backend: fetch() a https://api.github.com/users/imshashwatsingh con Accept: application/vnd.github+json y una cabecera User-Agent.

• Devuelve: nombre de usuario, nombre, empresa, ubicación, biografía, repositorios/gists públicos, seguidores, siguiendo, URL del perfil, marcas de tiempo de creación/actualización.

• Archivo: src/github.ts

2. list_files

Lista archivos bajo un directorio del espacio de trabajo hasta una profundidad.

• Entradas: path (por defecto "."), maxDepth (0–10, por defecto 3)

• Backend: collectFiles() recursivo en src/workspace.ts — omite enlaces simbólicos (sin bucles) e ignora directorios configurados (node_modules, .git, dist, .next, coverage, .cache). Limitado a MAX_RESULTS (500).

• Devuelve: raíz del espacio de trabajo, número de archivos y rutas de archivo relativas.

• Archivo: src/workspace.ts

3. read_file

Lee un archivo de texto UTF-8 con rango de líneas opcional.

• Entradas: path (obligatorio), startLine (opcional), endLine (opcional)

• Backend: readWorkspaceFile() — aplica el sandbox, rechaza no archivos, rechaza archivos mayores que MAX_FILE_SIZE (1 MB) y rechaza extensiones binarias. Devuelve líneas numeradas.

• Devuelve: contenido del archivo con prefijos línea: texto.

• Archivo: src/workspace.ts

4. search_context

Búsqueda de palabras clave en todo el espacio de trabajo con contexto circundante.

• Entradas: query (obligatorio), path (por defecto "."), maxResults (1–100, por defecto 50), contextLines (0–10, por defecto 2)

• Backend: searchContext() recopila archivos, filtra solo texto y archivos con límite de tamaño, luego escanea cada línea (sin distinción de mayúsculas) y captura contextLines arriba/abajo de cada coincidencia.

• Devuelve: consulta, ruta de búsqueda, número de coincidencias y coincidencias con archivo/línea/contexto.

• Archivo: src/workspace.ts

5. summarize_diff

Inspecciona el diff de Git actual y devuelve un resumen estructurado.

• Entradas: staged (por defecto false), base (referencia git opcional), path (archivo/directorio opcional), maxDiffChars (1000–200000, por defecto 50000)

• Backend: summarizeDiff() ejecuta git diff --no-ext-diff --unified=3 (con --cached / referencia base / filtros de ruta) desde WORKSPACE_ROOT. Las estadísticas se analizan del propio diff unificado (sin una segunda llamada a git). El diff se trunca si supera maxDiffChars.

• Devuelve: archivos modificados, inserciones, eliminaciones, estadísticas por archivo y el diff sin procesar — o { empty: true } cuando no hay cambios.

• Archivo: src/git.ts

Modelo de seguridad

El servidor es intencionalmente de solo lectura y aislado:

El límite del sandbox reside enteramente en paths.ts. Cualquier nueva herramienta que toque el sistema de archivos debe enrutar las rutas a través de resolveWorkspacePath().

Recorrido por el proyecto

1. Punto de entrada — src/server.ts createServer() instancia McpServer y llama a registerTools(). serveStdio() lo conecta a stdin/stdout.

2. Registro de herramientas — src/tools.ts Cinco llamadas a server.registerTool(...). Cada una declara una descripción, un inputSchema validado con zod y un manejador asíncrono. Los manejadores delegan en los módulos siguientes y envuelven la salida con los ayudantes de result.ts.

3. Configuración — src/config.ts Constantes centrales: WORKSPACE_ROOT (resuelto desde process.cwd()), límites de tamaño/resultados, nombre de usuario/URL de GitHub y conjuntos de ignorados/binarios.

4. Seguridad de rutas — src/paths.ts resolveWorkspacePath() es la puerta del sandbox. toWorkspaceRelative() convierte rutas absolutas de nuevo a cadenas relativas al espacio de trabajo para mostrar. isProbablyTextFile() clasifica archivos por extensión.

5. E/S del espacio de trabajo — src/workspace.ts collectFiles() (listado recursivo), readWorkspaceFile() (lectura segura) y searchContext() (escaneo de palabras clave). Todos pasan por resolveWorkspacePath().

6. GitHub — src/github.ts fetchGitHubProfile() llama a la API pública y mapea el GitHubUser sin procesar a la forma más amigable GitHubProfile.

7. Git — src/git.ts summarizeDiff() construye y ejecuta el comando git diff; parseDiffStats() deriva recuentos de inserciones/eliminaciones por archivo directamente del texto del diff.

8. Resultados — src/result.ts Pequeños ayudantes (textResult, errorResult, errorWithContext) estandarizan el sobre content de MCP y el marcado de errores.

Configuración

opencode.json (raíz del proyecto) declara el servidor:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github-assistant": {
      "type": "local",
      "command": ["node", "dist/server.js"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Dentro del servidor, el comportamiento se ajusta mediante constantes en src/config.ts:

Compilación y ejecución

# install dependencies
npm install

# compile TypeScript -> dist/
npm run build

# start the server (used by opencode.json)
npm start

# run directly from source (no build step)
npm run dev

# the workspace must be a git repo for summarize_diff to work
git init

OpenCode detecta el servidor automáticamente desde opencode.json una vez compilado (dist/server.js).

Estructura de archivos

github_assistant_mcp/
├── opencode.json          # MCP server declaration for OpenCode
├── package.json           # scripts + dependencies
├── tsconfig.json          # TypeScript config
├── src/
│   ├── server.ts          # Entry point: create + serve McpServer
│   ├── tools.ts           # Registers the 5 tools + handlers
│   ├── config.ts          # Constants, limits, GitHub target
│   ├── paths.ts           # Sandbox path resolution + helpers
│   ├── workspace.ts       # list / read / search filesystem
│   ├── github.ts          # GitHub profile fetch
│   ├── git.ts             # git diff summary + stat parsing
│   └── result.ts          # MCP result/error helpers
└── dist/                  # Compiled output (npm run build)

Limitaciones

• get_github_profile apunta a un único usuario fijo; no está parametrizado.

• summarize_diff informa solo cambios en el árbol de trabajo — los archivos sin seguimiento no se muestran con git diff.

• Las herramientas del sistema de archivos están confinadas a WORKSPACE_ROOT; no hay acceso entre proyectos.

• Todas las herramientas son de solo lectura por diseño — sin ediciones, eliminaciones ni ejecución de shell.

• Sin autenticación: la llamada a GitHub usa la API pública no autenticada (limitada a 60 solicitudes/hora por IP).