erm-github-mcp

Минималистичный Model Context Protocol (MCP) сервер, написанный на TypeScript. Разработан для сборки из исходного кода, контейнеризации с помощью Docker и развертывания в IBM Code Engine.

Содержание

• Обзор

• Структура проекта

• Инструменты

• Локальная разработка

• Запуск в Docker

• GitHub Actions CI/CD

• Развертывание в IBM Code Engine

• Подключение к Bob (IBM Bob Desktop)

• Расширение сервера

Related MCP server: My Awesome MCP

Обзор

Этот сервер поддерживает два транспорта:

HTTP-транспорт предоставляет конечную точку /health по адресу GET /health для проверок жизнеспособности (liveness probes).

Структура проекта

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

Инструменты

Локальная разработка

Предварительные требования

• Node.js 20+

• npm 10+

Установка и сборка

npm install
npm run build

Запуск в режиме stdio (для использования с Bob desktop)

node build/index.js

Локальный запуск в режиме HTTP

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

Проверьте health-эндпоинт:

curl http://localhost:3000/health

Запуск в Docker

Сборка образа

docker build -t erm-github-mcp .

Запуск контейнера

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

Использование Docker Compose

docker compose up --build

GitHub Actions CI/CD

The workflow по адресу .github/workflows/build-push.yml запускается при каждом push в ветку main и по тегам версий (v*):

1. Сборка TypeScript — npm ci + tsc (быстро останавливается при ошибках типов)

2. Docker build & push — мультиплатформенный образ (linux/amd64, linux/arm64) публикуется в GitHub Container Registry (GHCR)

Образ публикуется как:

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

Настраивать секреты не нужно — рабочий процесс использует встроенный GITHUB_TOKEN.

Как сделать пакет публичным

После первого push перейдите в GitHub → Пакеты → erm-github-mcp → Настройки пакета и установите видимость Public, чтобы Code Engine мог получать образ без учетных данных.

Развертывание в IBM Code Engine

Предварительные требования

• IBM Cloud CLI with the Code Engine plugin:

  ibmcloud plugin install code-engine

• Учетная запись IBM Cloud и проект Code Engine

Шаги

1 — Укажите свой проект

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

2 — Разверните приложение

Замените <tag> на тег образа, который необходимо развернуть (например, main или 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 — Получите публичный URL

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

4 — Обновите после публикации нового образа

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

Переменные окружения

Подключение к Bob (IBM Bob Desktop)

HTTP (удалённо — после развертывания в Code Engine)

Добавьте в файл mcp.json в Bob следующее:

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

stdio (локально — для разработки)

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

Расширение сервера

Добавляйте новые инструменты в файл src/index.ts через 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}` }],
  })
);

Затем пересоберите:

npm run build

Лицензия

Apache 2.0