erm-github-mcp

A barebones Model Context Protocol (MCP) server written in TypeScript. Designed to be built from source, containerized with Docker, and deployed to IBM Code Engine.

Table of Contents

• Overview

• Project Structure

• Tools

• Local Development

• Running with Docker

• GitHub Actions CI/CD

• Deploying to IBM Code Engine

• Connecting to Bob (IBM Bob Desktop)

• Extending the Server

Related MCP server: My Awesome MCP

Overview

This server supports two transports:

The HTTP transport exposes a /health endpoint at GET /health for liveness probes.

Project Structure

.
├── 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

Tools

Local Development

Prerequisites

• Node.js 20+

• npm 10+

Install and build

npm install
npm run build

Run in stdio mode (for use with Bob desktop)

node build/index.js

Run in HTTP mode locally

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

Test the health endpoint:

curl http://localhost:3000/health

Running with Docker

Build the image

docker build -t erm-github-mcp .

Run the container

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

Using Docker Compose

docker compose up --build

GitHub Actions CI/CD

The workflow at .github/workflows/build-push.yml runs on every push to main and on version tags (v*):

1. TypeScript build — npm ci + tsc (fails fast on type errors)

2. Docker build & push — multi-platform image (linux/amd64, linux/arm64) pushed to the GitHub Container Registry (GHCR)

The image is published as:

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

No secrets need to be configured — the workflow uses the built-in GITHUB_TOKEN.

Making the package public

After the first push, go to GitHub → Packages → erm-github-mcp → Package settings and set visibility to Public so Code Engine can pull it without credentials.

Deploying to IBM Code Engine

Prerequisites

• IBM Cloud CLI with the Code Engine plugin:

  ibmcloud plugin install code-engine

• An IBM Cloud account and a Code Engine project

Steps

1 — Target your project

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

2 — Deploy the application

Replace <tag> with the image tag you want to deploy (e.g. main or 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 — Get the public URL

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

4 — Update after a new image push

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

Environment variables

Connecting to Bob (IBM Bob Desktop)

HTTP (remote — after deploying to Code Engine)

Add the following to your Bob mcp.json:

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

stdio (local — for development)

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

Extending the Server

Add new tools in src/index.ts using 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}` }],
  })
);

Then rebuild:

npm run build

License

Apache 2.0