GitHub Assistant MCP

Небольшой автономный сервер Model Context Protocol (MCP), который предоставляет пять инструментов, ориентированных на чтение, для ИИ-ассистента программирования (например, OpenCode). Он позволяет ассистенту просматривать локальное рабочее пространство и получать публичный профиль GitHub через чистый изолированный stdio-транспорт.

«Простой GitHub MCP-сервер для OpenCode.»

Содержание

• Обзор

• Как это работает (архитектура)

• Транспорт и жизненный цикл

• Справочник инструментов

• Модель безопасности

• Разбор проекта

• Конфигурация

• Сборка и запуск

• Структура файлов

• Ограничения

Related MCP server: chatgpt-codex-local-mcp

Обзор

Сервер — это локальный MCP-сервер, запускаемый OpenCode как дочерний процесс. Он общается по протоколу MCP через stdio (stdin/stdout) и регистрирует пять инструментов. Ассистент вызывает эти инструменты; сервер выполняет работу (чтение файловой системы, git diff или вызов GitHub API) и возвращает структурированные текстовые результаты.

Всё, что касается файловой системы, ограничено одним каталогом WORKSPACE_ROOT, поэтому ассистент никогда не сможет прочитать или выйти за пределы папки проекта.

Как это работает (архитектура)

┌─────────────────────────┐         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

Поток данных для одного вызова инструмента:

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

Транспорт и жизненный цикл

• Тип: local — OpenCode запускает сервер как дочерний процесс.

• Транспорт: stdio через serveStdio() из @modelcontextprotocol/server/stdio.

• Последовательность запуска:

  1. Выполняется node dist/server.js (объявлено в opencode.json) с cwd = ".".

  2. createServer() создаёт McpServer с именем github-assistant (v1.0.0).

  3. registerTools(server) подключает пять инструментов.

  4. serveStdio(createServer) начинает читать JSON-RPC-сообщения из stdin и записывать результаты в stdout.

• Завершение: OpenCode завершает процесс, когда сеанс заканчивается.

Поскольку процесс наследует рабочий каталог OpenCode, WORKSPACE_ROOT разрешается в каталог проекта (path.resolve(process.cwd())).

Справочник инструментов

Все инструменты регистрируются в src/tools.ts и возвращают текстовые результаты MCP (JSON или обычный текст).

1. get_github_profile

Получает публичный профиль GitHub жёстко заданного пользователя (imshashwatsingh).

• Входные данные: нет

• Бэкенд: fetch() к https://api.github.com/users/imshashwatsingh с заголовком Accept: application/vnd.github+json и заголовком User-Agent.

• Возвращает: имя пользователя, имя, компанию, местоположение, био, публичные репозитории/гисты, подписчиков, подписки, URL профиля, временные метки создания/обновления.

• Файл: src/github.ts

2. list_files

Перечисляет файлы в каталоге рабочего пространства до заданной глубины.

• Входные данные: path (по умолчанию "."), maxDepth (0–10, по умолчанию 3)

• Бэкенд: рекурсивный collectFiles() в src/workspace.ts — пропускает символические ссылки (без циклов) и игнорирует настроенные каталоги (node_modules, .git, dist, .next, coverage, .cache). Ограничено MAX_RESULTS (500).

• Возвращает: корень рабочего пространства, количество файлов и относительные пути к файлам.

• Файл: src/workspace.ts

3. read_file

Читает текстовый файл UTF-8 с опциональным диапазоном строк.

• Входные данные: path (обязательно), startLine (опционально), endLine (опционально)

• Бэкенд: readWorkspaceFile() — обеспечивает песочницу, отклоняет не-файлы, отказывается от файлов больше MAX_FILE_SIZE (1 МБ) и от бинарных расширений. Возвращает строки с номерами.

• Возвращает: содержимое файла с префиксами line: text.

• Файл: src/workspace.ts

4. search_context

Поиск по ключевым словам в рабочем пространстве с окружающим контекстом.

• Входные данные: query (обязательно), path (по умолчанию "."), maxResults (1–100, по умолчанию 50), contextLines (0–10, по умолчанию 2)

• Бэкенд: searchContext() собирает файлы, фильтрует только текстовые файлы с ограничением размера, затем сканирует каждую строку (без учёта регистра) и захватывает contextLines выше/ниже каждого совпадения.

• Возвращает: запрос, путь поиска, количество совпадений и совпадения с файлом/строкой/контекстом.

• Файл: src/workspace.ts

5. summarize_diff

Проверяет текущий Git diff и возвращает структурированную сводку.

• Входные данные: staged (по умолчанию false), base (опциональная git-ссылка), path (опциональный файл/каталог), maxDiffChars (1000–200000, по умолчанию 50000)

• Бэкенд: summarizeDiff() выполняет git diff --no-ext-diff --unified=3 (с --cached / базовой ссылкой / фильтрами пути) из WORKSPACE_ROOT. Статистика извлекается из самого unified diff (без второго вызова git). Diff усекается, если превышает maxDiffChars.

• Возвращает: изменённые файлы, вставки, удаления, статистику по файлам и исходный diff — или { empty: true }, когда изменений нет.

• Файл: src/git.ts

Модель безопасности

Сервер намеренно только для чтения и изолирован:

Граница песочницы находится целиком в paths.ts. Любой новый инструмент, который касается файловой системы, обязан пропускать пути через resolveWorkspacePath().

Разбор проекта

1. Точка входа — src/server.ts createServer() создаёт экземпляр McpServer и вызывает registerTools(). serveStdio() связывает его с stdin/stdout.

2. Регистрация инструментов — src/tools.ts Пять вызовов server.registerTool(...). Каждый объявляет описание, проверяемую через zod inputSchema и асинхронный обработчик. Обработчики делегируют работу модулям ниже и оборачивают вывод с помощью помощников из result.ts.

3. Конфигурация — src/config.ts Центральные константы: WORKSPACE_ROOT (разрешается из process.cwd()), лимиты размера/результатов, имя пользователя/URL GitHub и наборы игнорируемых/бинарных файлов.

4. Безопасность путей — src/paths.ts resolveWorkspacePath() — это шлюз песочницы. toWorkspaceRelative() превращает абсолютные пути обратно в относительные строки рабочего пространства для отображения. isProbablyTextFile() классифицирует файлы по расширению.

5. Ввод-вывод рабочего пространства — src/workspace.ts collectFiles() (рекурсивное перечисление), readWorkspaceFile() (безопасное чтение) и searchContext() (сканирование по ключевым словам). Все проходят через resolveWorkspacePath().

6. GitHub — src/github.ts fetchGitHubProfile() вызывает публичный API и преобразует сырой GitHubUser в более удобную форму GitHubProfile.

7. Git — src/git.ts summarizeDiff() формирует и выполняет команду git diff; parseDiffStats() извлекает количество вставок/удалений по файлам прямо из текста diff.

8. Результаты — src/result.ts Небольшие помощники (textResult, errorResult, errorWithContext) стандартизируют конверт content MCP и флаги ошибок.

Конфигурация

opencode.json (корень проекта) объявляет сервер:

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

Внутри сервера поведение настраивается через константы в src/config.ts:

Сборка и запуск

# 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 автоматически подхватывает сервер из opencode.json после сборки (dist/server.js).

Структура файлов

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)

Ограничения

• get_github_profile нацелен на одного жёстко заданного пользователя; он не параметризован.

• summarize_diff сообщает только об изменениях в рабочем дереве — неотслеживаемые файлы не показываются командой git diff.

• Инструменты файловой системы ограничены WORKSPACE_ROOT; доступа к другим проектам нет.

• Все инструменты только для чтения по замыслу — никаких правок, удалений или выполнения команд в оболочке.

• Нет аутентификации: вызов GitHub использует неаутентифицированный публичный API (ограничение 60 запросов/час на IP).