Seq MCP Server (Weselow)

Seq MCP Server

MCP (Model Context Protocol) сервер для Seq - позволяет LLM приложениям взаимодействовать с платформой структурированного логирования Seq.

CI/CD Status

✨ Возможности

• 7 MCP инструментов: Поиск событий, управление сигналами, SQL запросы, список приложений
• 9 MCP ресурсов: Быстрый доступ к последним событиям (seq://)
• 8 MCP промптов: Готовые шаблоны для анализа логов (на русском)
• HTTP Transport: Server-Sent Events (SSE) по спецификации MCP 2025-03-26
• Интеграция с Seq: Нативная интеграция с Seq.Api 2025.2.2
• Scope Filtering: Автоматическая фильтрация по проекту через HTTP заголовки/ENV
• Production-Ready HttpClient: Оптимизированный Singleton с connection pooling
• Health Check Endpoint: Мониторинг состояния сервера и Seq подключения
• Оптимизация токенов: Краткие описания для экономии контекста LLM (экономия ~70% токенов)
• Русский язык: Все описания и промпты на русском для удобства российских пользователей

🏗️ Архитектура

• Язык: C# / .NET 9 (ASP.NET Core)
• Протокол: MCP 2025-03-26 (Streamable HTTP/SSE)
• Тестирование: xUnit с покрытием 94.4% методов, 41.9% строк кода
• Дизайн: Clean Architecture со строгим TDD подходом
• DI: Microsoft.Extensions.DependencyInjection
• Логирование: ILogger со структурированным логированием

🚀 Быстрый старт

Запуск в Docker (рекомендуется)

Самый простой способ - использовать готовый Docker образ из GitHub Container Registry:

# 1. Запустить Seq MCP Server
docker run -d \
  --name seq-mcp \
  -p 5555:5555 \
  -e SEQ_URL=http://your-seq-server:5341 \
  -e SEQ_API_KEY=your-api-key-if-needed \
  ghcr.io/weselow/seq-mcp-server:latest

# 2. Проверить что запустился
curl http://localhost:5555/health

Обязательные параметры:

• SEQ_URL - адрес вашего Seq сервера (например, http://localhost:5341)

Опциональные параметры:

• SEQ_API_KEY - API ключ Seq (если требуется аутентификация)
• SEQ_PROJECT_SCOPE - имя проекта для фильтрации логов (например, "MyWebApp")
• SEQ_SCOPE_FIELD - поле в логах для фильтрации (по умолчанию "Application")
• PORT - порт MCP сервера (по умолчанию 5555)

Зачем нужна фильтрация (Scope Filtering)?

Если в ваш Seq пишут несколько проектов (WebApp, BackgroundService, API), то без фильтрации LLM получит логи ВСЕХ проектов, что:

• Тратит токены на ненужные логи
• Замедляет поиск нужной информации
• Перегружает контекст LLM

С фильтрацией по Application = 'MyWebApp' вы получите только логи вашего проекта, экономя токены и улучшая точность анализа.

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

После запуска MCP сервера (Docker или локально), добавьте его в конфигурацию Claude Desktop:

Минимальная конфигурация:

{
  "mcpServers": {
    "seq": {
      "url": "http://localhost:5555/sse"    // ОБЯЗАТЕЛЬНО: URL MCP сервера
    }
  }
}

Конфигурация с фильтрацией по проекту (рекомендуется):

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "seq": {
      "url": "http://localhost:5555/sse",                     // ОБЯЗАТЕЛЬНО: URL MCP сервера
      "headers": {
        "X-Seq-Project-Scope": "MyWebApp",                    // ОПЦИОНАЛЬНО: фильтр по проекту (экономит токены!)
        "X-Seq-Scope-Field": "Application"                    // ОПЦИОНАЛЬНО: поле для фильтрации (по умолчанию "Application")
      }
    }
  }
}

Linux/macOS (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "seq": {
      "url": "http://localhost:5555/sse",                     // ОБЯЗАТЕЛЬНО: URL MCP сервера
      "headers": {
        "X-Seq-Project-Scope": "MyWebApp",                    // ОПЦИОНАЛЬНО: фильтр по проекту (экономит токены!)
        "X-Seq-Scope-Field": "Application"                    // ОПЦИОНАЛЬНО: поле для фильтрации (по умолчанию "Application")
      }
    }
  }
}

Важно:

• Наш сервер использует HTTP/SSE транспорт, поэтому используется url, а не command
• Фильтрация через заголовки (X-Seq-Project-Scope) позволяет получать только логи нужного проекта - это экономит токены LLM и ускоряет анализ
• После изменения конфигурации перезапустите Claude Desktop
• Заголовки передаются в каждом HTTP запросе к MCP серверу

Примечание: Для запуска полного стека (Seq + MCP сервер) используйте Docker Compose - см. раздел .

Альтернатива: Запуск без Docker

Требования:

• .NET 9 SDK
• Запущенный Seq сервер

Шаг 1: Сборка и публикация

# Сборка
dotnet build

# Публикация
dotnet publish src/SeqMcp/SeqMcp.csproj -c Release -o ./publish

Шаг 2: Запуск MCP сервера

Запустите сервер в отдельном терминале:

Windows (PowerShell):

# Минимальная конфигурация (только обязательные параметры)
$env:SEQ_URL="http://localhost:5341"              # ОБЯЗАТЕЛЬНО: URL Seq сервера
$env:SEQ_API_KEY="your-api-key"                   # ОПЦИОНАЛЬНО: API ключ (если Seq требует аутентификацию)
.\publish\SeqMcp.exe

Linux/macOS:

# Минимальная конфигурация (только обязательные параметры)
export SEQ_URL="http://localhost:5341"            # ОБЯЗАТЕЛЬНО: URL Seq сервера
export SEQ_API_KEY="your-api-key"                 # ОПЦИОНАЛЬНО: API ключ (если Seq требует аутентификацию)
./publish/SeqMcp

Дополнительные переменные окружения (опционально):

export PORT="5555"                                # Порт MCP сервера (по умолчанию 5555)
export SEQ_PROJECT_SCOPE="MyProject"              # Фильтр по проекту (лучше задавать через headers в Claude Desktop)
export SEQ_SCOPE_FIELD="Application"              # Поле для фильтрации (лучше задавать через headers)

Шаг 3: Конфигурация Claude Desktop

После запуска сервера, добавьте его в конфигурацию Claude Desktop. Рекомендуется использовать фильтрацию через headers (см. раздел "Конфигурация Claude Desktop" выше):

{
  "mcpServers": {
    "seq": {
      "url": "http://localhost:5555/sse",
      "headers": {
        "X-Seq-Project-Scope": "MyWebApp",                    // ОПЦИОНАЛЬНО: фильтр по проекту - настройте под ваше приложение
        "X-Seq-Scope-Field": "Application"                    // ОПЦИОНАЛЬНО: поле для фильтрации (по умолчанию "Application")
      }
    }
  }
}

Преимущества фильтрации через headers:

• Не нужно перезапускать MCP сервер при изменении фильтра
• Можно быстро переключаться между проектами, меняя только конфиг Claude Desktop
• Фильтрация работает на уровне HTTP запросов

Примечание: Сервер должен быть запущен ПЕРЕД стартом Claude Desktop. Если вы перезапустите сервер, перезапустите также Claude Desktop для переподключения.

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

seq-mcp-server/
├── src/
│   └── SeqMcp/
│       ├── Configuration/      # Конфигурация (SeqServerConfig, SeqRequestContext)
│       ├── Services/           # Обёртка для Seq API клиента (SeqApiClient)
│       ├── Tools/              # MCP инструменты (SeqTools)
│       ├── Resources/          # MCP ресурсы (SeqResources)
│       ├── Prompts/            # MCP промпты (SeqPrompts)
│       ├── Models/             # Модели данных (DTO)
│       └── Program.cs          # Точка входа и DI конфигурация
├── tests/
│   └── SeqMcp.Tests/           # Unit и интеграционные тесты
└── docs/
    └── standards/              # Стандарты разработки

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

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

# Подключение к Seq серверу (поддерживаются оба варианта)
export SEQ_URL="http://localhost:8080"           # По умолчанию: http://localhost:8080
export SEQ_SERVER_URL="http://localhost:8080"    # Альтернативное имя (для совместимости)
export SEQ_API_KEY="your-api-key"                # Опционально, для Seq с аутентификацией

# Порт MCP сервера
export PORT="5555"                                # По умолчанию: 5555

# Фильтрация по проекту (опционально)
export SEQ_PROJECT_SCOPE="MyProject"             # Опционально: фильтр по имени проекта
export SEQ_SCOPE_FIELD="Application"             # По умолчанию: "Application"

Примечание: Можно использовать либо SEQ_URL, либо SEQ_SERVER_URL - они взаимозаменяемы. Приоритет имеет SEQ_URL.

Фильтрация по проекту (Scope Filtering)

Сервер поддерживает автоматическую фильтрацию событий по проекту/приложению. Это полезно когда несколько проектов логируют в один Seq сервер.

Приоритет конфигурации (от высшего к низшему):

1. HTTP заголовки (для HTTP MCP транспорта)
2. Переменные окружения (SEQ_PROJECT_SCOPE, SEQ_SCOPE_FIELD)
3. appsettings.json (Seq:ProjectScope, Seq:ScopeField)
4. Без фильтрации (если ничего не задано)

Примеры использования:

Через HTTP заголовки:

curl -H "X-Seq-Project-Scope: MyProject" \
     -H "X-Seq-Scope-Field: Application" \
     http://localhost:5555/mcp/v1

Через переменные окружения:

export SEQ_PROJECT_SCOPE="MyProject"
export SEQ_SCOPE_FIELD="Application"
dotnet run

Через appsettings.json:

{
  "Seq": {
    "Url": "http://localhost:8080",
    "ApiKey": "your-api-key",
    "ProjectScope": "MyProject",
    "ScopeField": "Application"
  }
}

При включенной фильтрации, все запросы автоматически добавляют условие:

Application = 'MyProject'

Если пользователь добавляет свой фильтр:

Level = 'Error'

Итоговый фильтр будет:

(Application = 'MyProject') and (Level = 'Error')

Health Check Endpoint

Сервер предоставляет /health endpoint для мониторинга состояния и проверки доступности Seq сервера.

URL: GET http://localhost:5555/health

Ответ при успешном состоянии (200 OK):

{
  "status": "healthy",
  "version": "1.0.0.0",
  "uptimeSeconds": 3600,
  "seqConnection": {
    "isHealthy": true,
    "message": "Connected to Seq server",
    "responseTimeMs": 45
  },
  "metrics": {
    "total_requests": 150,
    "uptime_seconds": 3600,
    "seq_response_time_ms": 45
  }
}

Ответ при проблемах (503 Service Unavailable):

{
  "status": "unhealthy",
  "version": "1.0.0.0",
  "uptimeSeconds": 3600,
  "seqConnection": {
    "isHealthy": false,
    "message": "Connection failed: Connection refused",
    "responseTimeMs": 1000
  },
  "metrics": {
    "total_requests": 150,
    "uptime_seconds": 3600,
    "seq_response_time_ms": 1000
  }
}

Метрики:

• total_requests - общее количество health check запросов с момента запуска
• uptime_seconds - время работы сервера в секундах
• seq_response_time_ms - время ответа Seq сервера в миллисекундах

Использование для мониторинга:

# Проверка доступности
curl http://localhost:5555/health

# Kubernetes liveness probe
livenessProbe:
  httpGet:
    path: /health
    port: 5555
  initialDelaySeconds: 10
  periodSeconds: 30

# Prometheus monitoring
http://localhost:5555/health

🐳 Docker

Быстрый старт с Docker Compose (рекомендуется)

Самый простой способ запустить Seq MCP Server вместе с Seq сервером:

# 1. Создайте .env файл (опционально)
cp .env.example .env
# Отредактируйте .env при необходимости

# 2. Запустите оба сервиса
docker-compose up -d

# 3. Проверьте логи
docker-compose logs -f seq-mcp

# 4. Проверьте health check
curl http://localhost:5555/health

# 5. Откройте Seq UI
http://localhost:8080

Что включено:

• seq - Seq log server (порт 8080 UI, 5341 ingestion)
• seq-mcp - Seq MCP Server (порт 5555)
• Health checks для обоих сервисов
• Автоматическая зависимость (MCP ждёт готовности Seq)
• Persistent volume для данных Seq

Управление:

# Остановить
docker-compose down

# Остановить и удалить данные
docker-compose down -v

# Перезапустить
docker-compose restart seq-mcp

# Посмотреть статус
docker-compose ps

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

# Собрать образ
docker build -t seq-mcp-server:latest .

# Запустить контейнер
docker run -d \
  --name seq-mcp \
  -p 5555:5555 \
  -e SEQ_URL=http://your-seq-server:80 \
  -e SEQ_API_KEY=your-api-key \
  seq-mcp-server:latest

# Проверить логи
docker logs -f seq-mcp

# Проверить health check
docker exec seq-mcp curl http://localhost:5555/health

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

Docker в production

Docker Compose файл для production:

version: '3.8'

services:
  seq-mcp:
    image: your-registry/seq-mcp-server:latest
    container_name: seq-mcp-prod
    ports:
      - "5555:5555"
    environment:
      - SEQ_URL=http://your-seq-server:80
      - SEQ_API_KEY=${SEQ_API_KEY}
      - SEQ_PROJECT_SCOPE=ProductionApp
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5555/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

Kubernetes Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: seq-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: seq-mcp
  template:
    metadata:
      labels:
        app: seq-mcp
    spec:
      containers:
      - name: seq-mcp
        image: your-registry/seq-mcp-server:latest
        ports:
        - containerPort: 5555
        env:
        - name: SEQ_URL
          value: "http://seq-service:80"
        - name: SEQ_API_KEY
          valueFrom:
            secretKeyRef:
              name: seq-credentials
              key: api-key
        livenessProbe:
          httpGet:
            path: /health
            port: 5555
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 5555
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 250m
            memory: 256Mi

Тесты

# Запуск всех тестов
dotnet test

# Запуск с покрытием
dotnet test --collect:"XPlat Code Coverage"

Разработка

Проект следует строгим практикам TDD. Смотрите docs/standards/:

• GLOBAL-implementation-standard.md - Основные принципы разработки
• tdd-standard.md - TDD процесс и правила

Ключевые принципы

1. Цикл RED → GREEN → REFACTOR
2. Тесты ПЕРВЫМИ, код вторым
3. Никогда не изменять тесты для исправления ошибок компиляции
4. Функции 1000ms (последние 50)

9. seq://stats/summary

Статистика событий за последний час по уровням (SQL агрегация)

💡 MCP промпты (шаблоны)

Готовые промпты для типичных задач анализа логов (на русском):

1. seq_analyze_errors

Параметр: period (1h, 24h, 7d)

Анализ ошибок за период с выводом топ-5, паттернов и рекомендаций

2. seq_top_exceptions

Параметр: count (по умолчанию: 10)

Топ исключений с группировкой и анализом

3. seq_activity_summary

Параметр: period (1h, 24h, 7d)

Сводка активности по уровням логирования

4. seq_check_signals

Проверка всех активных сигналов

5. seq_performance_check

Параметр: period (1h, 24h)

Анализ производительности и проблем

6. seq_trace_request

Параметр: requestId (обязательно)

Трассировка запроса по RequestId/CorrelationId

7. seq_security_audit

Параметр: period (1h, 24h, 7d)

Аудит событий безопасности (auth, unauthorized и т.д.)

8. seq_daily_report

Ежедневный отчёт о состоянии логов

🔌 Интеграция с Claude Desktop

Конфигурация Claude Desktop описана в разделе 🚀 Быстрый старт выше.

Два способа подключения:

1. Docker (рекомендуется) - запустите контейнер и укажите "url": "http://localhost:5555/sse" в конфиге
2. Без Docker - опубликуйте проект и укажите "command" с путём к .exe в конфиге

Подробные примеры конфигурации для Windows/Linux/macOS смотрите в разделе "Быстрый старт".

📋 TODO / Дорожная карта

• [x] ~~Завершить интеграцию с Seq.Api~~
• [x] ~~Добавить инструмент seq_list_signals~~
• [x] ~~Добавить инструмент seq_execute_sql~~
• [x] ~~Реализация MCP протокола~~
• [x] ~~HTTP/SSE транспорт~~
• [x] ~~Обработка ошибок с логированием~~
• [x] ~~MCP Resources (seq://events, seq://signals)~~
• [x] ~~MCP Prompts (шаблоны запросов)~~
• [x] ~~Scope filtering (фильтрация по проекту)~~
• [x] ~~Production-ready HttpClient с connection pooling~~
• [x] ~~Health Check endpoint~~
• [x] ~~Docker контейнеризация (Dockerfile, docker-compose, .dockerignore)~~
• [x] ~~Дополнительные MCP Resources (last-hour, today, slow, stats)~~
• [x] ~~Дополнительные MCP Tools (create_signal, update_signal, delete_signal, get_apps)~~
• [x] ~~Интеграционные тесты с живым Seq сервером (13 integration тестов)~~
• [x] ~~CI/CD pipeline (GitHub Actions) - 3 workflows: CI, Docker, Security~~

CI/CD Pipeline: См. docs/CICD.md для полной документации

📦 Зависимости

• ModelContextProtocol.AspNetCore 0.4.0-preview.2 - Официальный MCP SDK для ASP.NET Core
• Seq.Api 2025.2.2 - Официальный Seq HTTP API клиент
• Microsoft.Extensions.Logging 9.0.9 - Структурированное логирование
• xUnit - Фреймворк для тестирования
• FluentAssertions - Fluent утверждения для тестов
• Moq - Фреймворк для моков

🧪 Тестирование

Запуск тестов

# Запуск всех тестов
dotnet test

# Запуск с покрытием
dotnet test --collect:"XPlat Code Coverage"

# Запуск конкретного тестового класса
dotnet test --filter "FullyQualifiedName~SeqToolsTests"

Статистика тестов

• Unit тесты: 35 тестов (всегда выполняются)
• Integration тесты: 13 тестов (требуют Seq сервер, по умолчанию Skip)
• Всего: 48 тестов
• Успешность: 100% (35/35 unit тестов прошли)
• Покрытие: Scope filtering (7), Health Check (8), Signal Management (9 integration)

Запуск интеграционных тестов:

# 1. Запустить Seq через Docker
docker run -d --name seq-test -e ACCEPT_EULA=Y -p 5341:80 datalust/seq

# 2. Запустить тесты (integration тесты останутся Skip)
dotnet test

# 3. Для запуска integration тестов удалите атрибут Skip из тестов

Подробная документация: docs/INTEGRATION_TESTS.md

🤝 Участие в разработке

1. Следуйте TDD стандартам в docs/standards/
2. Всегда пишите тесты ПЕРВЫМИ (RED → GREEN → REFACTOR)
3. Поддерживайте >60% покрытие методов
4. Все тесты должны проходить перед PR
5. Используйте conventional commits

📄 Лицензия

MIT

🔗 Ссылки

• Спецификация Model Context Protocol
• Документация Seq
• ModelContextProtocol C# SDK

Статус: ✅ Готов к production - Полнофункциональный MCP сервер с 7 инструментами, 9 ресурсами, 8 промптами, HTTP транспортом, обработкой ошибок и полным тестированием