docs(gns-2): MCP stdio transport setup instructions

2026-05-09 00:33:21 +01:00
parent af08e74f72
commit 81e4708b5f
1 changed files with 134 additions and 0 deletions
--- a/MCP-STDIO-SETUP.md
+++ b/MCP-STDIO-SETUP.md
@@ -0,0 +1,134 @@
+# 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`.
+
+```bash
+# Запуск
+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.
+
+```bash
+# Установка (выполняется автоматически при первом 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
+```
+
+## Как перезапустить
+
+1. **Перезапуск Docker контейнера (если нужен HTTP endpoint):**
+   ```bash
+   docker compose -f docker/mcp-gitea/docker-compose.yml restart
+   ```
+
+2. **Перезапуск stdio bridge:**
+   Stdio bridge не нуждается в перезапуске — он запускается как дочерний процесс для каждого вызова. Если нужно перезапустить среду:
+   ```bash
+   # Очистить кеш bunx
+   bunx --clear-cache @ric_/forgejo-mcp
+   # Перезапустить
+   bun scripts/mcp-gitea-stdio.cjs
+   ```
+
+3. **Полный рестарт (после обновления кода):**
+   ```bash
+   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 |
+
+## Использование в коде
+
+```typescript
+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."
+})
+```
+
+## Проверка работоспособности
+
+```bash
+cd /home/swp/Projects/APAW
+python3 scripts/e2e-mcp-stdio-test-v3.py
+```
+
+Ожидаемый результат: `✅ ALL E2E MCP STDIO TESTS PASSED`
+
+## Отличие от плагина Kilo Code
+
+**MCP сервер НЕ встроен в плагин Kilo Code.** Вместо этого:
+
+1. **Kilo Code запускает** `@ric_/forgejo-mcp` как внешний stdio процесс через Node.js `child_process.spawn`.
+2. **Плагин Kilo Code** использует `MCPGiteaStdioClient` который порождает этот процесс и общается с ним по JSON-RPC через stdin/stdout.
+3. **forgejo-mcp** сам делает HTTP вызовы к Gitea API с Bearer токеном.
+
+Это соответствует спецификации MCP 2024-11-05 transport: stdio для локальных процессов, HTTP SSE для удалённых серверов.