MCP Stdio Transport Setup — GNS-2 Integration

Этот документ описывает, как запускать и использовать MCP (Model Context Protocol) stdio transport для интеграции с Gitea в рамках GNS-2 (Gitea-Nervous-System v2).

Архитектура

┌──────────────────┐      JSON-RPC (stdin/stdout)      ┌──────────────┐
│ Kilo Code Agent  │  ◄──────────────────────────────►  │forgejo-mcp   │
│ (Task tool)      │         bunx @ric_/forgejo-mcp     │(stdio server)│
└──────────────────┘                                   └──────┬───────┘
                                                             │
                                                             │ HTTP Bearer
                                                             │
                                                             ▼
                                                    ┌────────────────┐
                                                    │  git.softuniq.eu│
                                                    │   (Gitea API)  │
                                                    └────────────────┘

Два варианта MCP сервера

Вариант 1: Удалённый HTTP MCP (Docker)

Запускается как Docker-контейнер и слушает HTTP на localhost:3001.

# Запуск
docker compose -f docker/mcp-gitea/docker-compose.yml up -d

# Проверка
curl http://localhost:3001/health
curl -H "Authorization: Bearer changeme" http://localhost:3001/mcp

Проблема: Kilo Code не поддерживает HTTP SSE transport напрямую. Поэтому этот режим используется только как fallback.

Вариант 2: Локальный stdio MCP (Рекомендуется)

Запускается как дочерний процесс через bunx @ric_/forgejo-mcp. Общается через stdin/stdout по JSON-RPC.

# Установка (выполняется автоматически при первом bunx)
bunx @ric_/forgejo-mcp --help

# Запуск stdio сервера
export FORGEJO_URL=https://git.softuniq.eu
export FORGEJO_TOKEN=your-token-here
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | bunx @ric_/forgejo-mcp

Как перезапустить

Перезапуск Docker контейнера (если нужен HTTP endpoint):
```
docker compose -f docker/mcp-gitea/docker-compose.yml restart
```
Перезапуск stdio bridge: Stdio bridge не нуждается в перезапуске — он запускается как дочерний процесс для каждого вызова. Если нужно перезапустить среду:
```
# Очистить кеш bunx
bunx --clear-cache @ric_/forgejo-mcp
# Перезапустить
bun scripts/mcp-gitea-stdio.cjs
```

Полный рестарт (после обновления кода):

docker compose -f docker/mcp-gitea/docker-compose.yml down
docker compose -f docker/mcp-gitea/docker-compose.yml up -d

Файлы проекта

Файл	Назначение
`src/kilocode/agent-manager/mcp-gitea-client.ts`	`MCPGiteaStdioClient`, `MCPGiteaHttpClient`, `HybridGiteaClient`
`scripts/mcp-gitea-stdio.cjs`	Обёртка для запуска `@ric_/forgejo-mcp` через stdin/stdout
`scripts/e2e-mcp-stdio-test-v3.py`	E2E тест: initialize → tools/list → get_issue
`docker/mcp-gitea/docker-compose.yml`	Docker-контейнер с HTTP MCP сервером

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

Переменная	Значение по умолчанию	Описание
`FORGEJO_URL`	`https://git.softuniq.eu`	URL Gitea/Forgejo инстанса
`FORGEJO_TOKEN`	—	Bearer токен или пароль для Basic Auth
`MCP_STDIO_COMMAND`	`bun scripts/mcp-gitea-stdio.cjs`	Команда для запуска stdio bridge
`MCP_GITEA_URL`	`http://localhost:3001`	URL HTTP MCP fallback

Использование в коде

import { MCPGiteaStdioClient } from "./mcp-gitea-client"

const client = new MCPGiteaStdioClient()
await client.connect()

// Получить issue
const issue = await client.callTool("get_issue", {
  owner: "UniqueSoft",
  repo: "APAW",
  index: 110
})

// Создать комментарий
await client.callTool("create_issue_comment", {
  owner: "UniqueSoft",
  repo: "APAW",
  index: 110,
  body: "## ✅ MCP Stdio Test\nAll tests passed."
})

Проверка работоспособности

cd /home/swp/Projects/APAW
python3 scripts/e2e-mcp-stdio-test-v3.py

Ожидаемый результат: ✅ ALL E2E MCP STDIO TESTS PASSED

Отличие от плагина Kilo Code

MCP сервер НЕ встроен в плагин Kilo Code. Вместо этого:

Kilo Code запускает @ric_/forgejo-mcp как внешний stdio процесс через Node.js child_process.spawn.
Плагин Kilo Code использует MCPGiteaStdioClient который порождает этот процесс и общается с ним по JSON-RPC через stdin/stdout.
forgejo-mcp сам делает HTTP вызовы к Gitea API с Bearer токеном.

Это соответствует спецификации MCP 2024-11-05 transport: stdio для локальных процессов, HTTP SSE для удалённых серверов.

5.9 KiB Raw Blame History Unescape Escape