Проблемы подключения

Большинство проблем подключения связаны с сетевой конфигурацией Docker. Контейнер работает в изолированной сети и не имеет прямого доступа к localhost хост-машины.

localhost не работает внутри контейнера

Симптом

MCP-сервер не может подключиться к Neo4j, LM Studio или другим сервисам по адресу localhost.

Причина

localhost внутри контейнера указывает на сам контейнер, а не на хост-машину. Сервисы на хосте недоступны по этому адресу.

Решение

Используйте специальный адрес host.docker.internal:

# Неправильно
OPENAI_API_BASE=http://localhost:1234/v1
NEO4J_URI=bolt://localhost:7687

# Правильно
OPENAI_API_BASE=http://host.docker.internal:1234/v1
NEO4J_URI=bolt://host.docker.internal:7687

Если сервис (например, Neo4j) тоже запущен в Docker, используйте имя сервиса из docker-compose:

# docker-compose.yml
services:
  neo4j:
    ...
  mcp-app:
    environment:
      - NEO4J_URI=bolt://neo4j:7687  # имя сервиса, не localhost!

Cursor не видит MCP-сервер

Проверка 1: Контейнер запущен

docker ps --filter name=<container_name>

Проверка 2: Порт доступен

Test-NetConnection -ComputerName localhost -Port 8002

Проверка 3: Файл mcp.json

Get-Content "$env:APPDATA\Cursor\User\globalStorage\mcp.json"

Проверка 4: JSON валиден

$content = Get-Content "$env:APPDATA\Cursor\User\globalStorage\mcp.json" -Raw
try {
    $json = $content | ConvertFrom-Json
    Write-Host "JSON валиден" -ForegroundColor Green
} catch {
    Write-Host "Ошибка JSON: $_" -ForegroundColor Red
}

Решение

1. Перезапустите Cursor (закройте все окна)

2. Проверьте правильность URL в mcp.json

3. Убедитесь, что контейнер запущен и порт доступен

Ошибка "Connection refused"

Симптом

ECONNREFUSED 127.0.0.1:8002

Причины

1. Контейнер не запущен

2. Контейнер всё ещё инициализируется

3. Порт неправильный

Решение

# Проверить статус
docker ps -a --filter name=<container_name>

# Проверить логи
docker logs <container_name>

# Перезапустить
docker restart <container_name>

Порт уже занят

Симптом

Error: port is already allocated

Найти процесс

netstat -ano | findstr :8002
# Найти PID и завершить процесс
taskkill /PID <PID> /F

Использовать другой порт

docker run -d -p 8102:8002 `
    --name 1c_syntaxcheck_mcp `
    -e LICENSE_KEY=YOUR_LICENSE_KEY `
    comol/1c_syntaxcheck_mcp:latest

Обновите mcp.json:

{
  "mcpServers": {
    "1c-syntax-checker-mcp": {
      "url": "http://localhost:8102/mcp",
      "connection_id": "1c_lsp_service_001"
    }
  }
}

Windows Firewall блокирует

Проверка

Get-NetFirewallRule -DisplayName "*Docker*" | Format-Table Name, Enabled

Добавление правила

# От администратора
New-NetFirewallRule -DisplayName "MCP Servers" `
    -Direction Inbound `
    -LocalPort 8000,8002,8003,8004,8006,8007,8008 `
    -Protocol TCP `
    -Action Allow

MCP работает, но ИИ не использует инструменты

Причина 1: Нет Cursor Rules

Добавьте правила, указывающие ИИ использовать MCP:

При работе с кодом 1С используй MCP-серверы:
- 1c-syntax-checker-mcp для проверки синтаксиса
- 1c-docs-mcp для поиска по справке

Причина 2: Неявный запрос

Попробуйте явно указать:

• "Проверь синтаксис этого кода через MCP"

• "Найди в справке метод Запрос.Выполнить"

Причина 3: Сервер не подключён

Проверьте список подключённых серверов в Cursor.

Timeout при запросах

Симптом

Запросы к MCP-серверу зависают или возвращают timeout.

Причины

1. Сервер перегружен (идёт индексация)

2. Недостаточно ресурсов

3. Проблемы с embedding моделью

Решение

# Проверить состояние
docker stats <container_name>

# Проверить логи
docker logs --tail 50 <container_name>

Сервер «отваливается» после простоя: 404 Session not found

Симптом

Сервер долго не использовался (от 15–30 минут) или клиент держит одну сессию много часов, и следующий вызов падает с HTTP 404: Session not found или, у 1CCodeChecker, session_expired. Контейнер при этом здоров, /health отвечает 200, а сервер в клиенте остаётся недоступным до ручного переподключения.

Причина

Сервер закрыл сессию MCP по простою или по максимальному времени жизни, либо контейнер перезапускался. Это штатное поведение: по спецификации MCP клиент в ответ на 404 должен сам начать новую сессию. Некоторые клиенты этого пока не делают.

Решение

1. Переподключите сервер в клиенте — этого достаточно, контейнер перезапускать не нужно.

2. Для IDE-плагинов и долгих агентных прогонов увеличьте простой, например до 8 часов:

# 1CCodeChecker
-e MCP_TRANSPORT_SESSION_IDLE_TIMEOUT=28800
# SSLSearchServer
-e SESSION_IDLE_TTL=28800

Значения по умолчанию и имена переменных всех серверов — в разделе Сессии MCP и ответ 404.

Включение SSE транспорта

Симптом

Некоторые клиенты требуют SSE (Server-Sent Events) вместо стандартного HTTP транспорта.

Решение

Добавьте переменную окружения USESSE=true. Для Graph Metadata Search используйте MCP_USE_SSE=true:

docker run -d -p 8002:8002 `
  --name 1c_syntaxcheck_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e USESSE=true `
  comol/1c_syntaxcheck_mcp:latest

SSE обычно нужен только для legacy-клиентов. Cursor работает со стандартным HTTP транспортом.

Скрипт полной диагностики

Write-Host "=== Диагностика MCP серверов ===" -ForegroundColor Cyan

# Docker
Write-Host "`nDocker:" -ForegroundColor Yellow
docker --version

# Контейнеры
Write-Host "`nКонтейнеры:" -ForegroundColor Yellow
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Порты
Write-Host "`nПорты:" -ForegroundColor Yellow
@(8000, 8002, 8003, 8004, 8006, 8007, 8008) | ForEach-Object {
    $result = Test-NetConnection -ComputerName localhost -Port $_ -WarningAction SilentlyContinue
    if ($result.TcpTestSucceeded) {
        Write-Host "  ✓ Порт $_ доступен" -ForegroundColor Green
    } else {
        Write-Host "  ✗ Порт $_ недоступен" -ForegroundColor Red
    }
}

# mcp.json
Write-Host "`nmcp.json:" -ForegroundColor Yellow
$mcpPath = "$env:APPDATA\Cursor\User\globalStorage\mcp.json"
if (Test-Path $mcpPath) {
    Write-Host "  Файл существует" -ForegroundColor Green
    try {
        Get-Content $mcpPath -Raw | ConvertFrom-Json | Out-Null
        Write-Host "  JSON валиден" -ForegroundColor Green
    } catch {
        Write-Host "  JSON невалиден!" -ForegroundColor Red
    }
} else {
    Write-Host "  Файл не найден!" -ForegroundColor Red
}