erm-github-mcp

Un servidor básico del Model Context Protocol (MCP) escrito en TypeScript. Diseñado para compilarse a partir del código fuente, empaquetarse en un contenedor con Docker y desplegarse en IBM Code Engine.

Tabla de contenidos

• Visión general

• Estructura del proyecto

• Herramientas

• Desarrollo local

• Ejecución con Docker

• CI/CD con GitHub Actions

• Despliegue en IBM Code Engine

• Conexión con Bob (IBM Bob Desktop)

• Ampliación del servidor

Related MCP server: My Awesome MCP

Visión general

Este servidor admite dos transportes:

El transporte HTTP expone un endpoint /health en GET /health para las sondas de liveness.

Estructura del proyecto

.
├── src/
│   └── index.ts          # Server entry point — add tools here
├── build/                # Compiled output (git-ignored)
├── .github/
│   └── workflows/
│       └── build-push.yml  # CI: typecheck → build → push to GHCR
├── Dockerfile            # Multi-stage build (builder + runtime)
├── docker-compose.yml    # Local container testing
├── tsconfig.json
└── package.json

Herramientas

Desarrollo local

Requisitos previos

• Node.js 20+

• npm 10+

Instalar y compilar

npm install
npm run build

Ejecutar en modo stdio (para usar con Bob desktop)

node build/index.js

Ejecutar en modo HTTP localmente

MCP_TRANSPORT=http PORT=3000 node build/index.js

Prueba el endpoint de salud:

curl http://localhost:3000/health

Ejecución con Docker

Compilar la imagen

docker build -t erm-github-mcp .

Ejecutar el contenedor

docker run -p 3000:3000 erm-github-mcp

Usar Docker Compose

docker compose up --build

CI/CD con GitHub Actions

El flujo de trabajo que se encuentra en .github/workflows/build-push.yml se ejecuta en cada push a main y en las etiquetas de versión (v*):

1. Compilación de TypeScript — npm ci + tsc (falla rápido ante errores de tipo)

2. Compilación y push de Docker — imagen multiplataforma (linux/amd64, linux/arm64) publicada en el GitHub Container Registry (GHCR)

La imagen se publica como:

ghcr.io/<your-github-username>/erm-github-mcp:<tag>

No es necesario configurar secretos: el flujo de trabajo usa el GITHUB_TOKEN integrado.

Hacer público el paquete

Después del primer push, ve a GitHub → Paquetes → erm-github-mcp → Configuración del paquete y establece la visibilidad en Public para que Code Engine pueda extraerla sin credenciales.

Despliegue en IBM Code Engine

Requisitos previos

• IBM Cloud CLI con el plugin de Code Engine:

  ibmcloud plugin install code-engine

• Una cuenta de IBM Cloud y un proyecto de Code Engine

Pasos

1 — Selecciona tu proyecto

ibmcloud ce project select --name <your-project-name>

2 — Despliega la aplicación

Reemplaza <tag> con la etiqueta de la imagen que quieras desplegar (por ejemplo, main o v0.1.0):

ibmcloud ce application create \
  --name erm-github-mcp \
  --image ghcr.io/<your-github-username>/erm-github-mcp:<tag> \
  --port 3000 \
  --min-scale 0 \
  --max-scale 5 \
  --env MCP_TRANSPORT=http \
  --env PORT=3000

3 — Obtén la URL pública

ibmcloud ce application get --name erm-github-mcp --output url

4 — Actualiza después de un nuevo push de la imagen

ibmcloud ce application update \
  --name erm-github-mcp \
  --image ghcr.io/<your-github-username>/erm-github-mcp:<new-tag>

Variables de entorno

Conexión con Bob (IBM Bob Desktop)

HTTP (remoto — después de desplegar en Code Engine)

Añade lo siguiente a tu mcp.json de Bob:

{
  "mcpServers": {
    "erm-github-mcp": {
      "url": "https://<your-code-engine-url>"
    }
  }
}

stdio (local — para desarrollo)

{
  "mcpServers": {
    "erm-github-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/erm-github-mcp/build/index.js"]
    }
  }
}

Ampliación del servidor

Añade nuevas herramientas en src/index.ts usando server.tool():

server.tool(
  "my_tool",
  "Description shown to the AI",
  {
    input_field: z.string().describe("What this field does"),
  },
  async ({ input_field }) => ({
    content: [{ type: "text", text: `Result: ${input_field}` }],
  })
);

A continuación, vuelve a compilar:

npm run build

Licencia

Apache 2.0