🌊🔍 Lenses MCP Server для Apache Kafka 🔎🌊

Name: Lenses MCP Server
Author: lensesio

Python 3.12+ FastMCP MCP License: Apache 2.0

Это MCP-сервер (Model Context Protocol) Lenses для Apache Kafka. Lenses предлагает решение для разработчиков, создающих приложения реального времени, подключенные к Kafka. Он создан для корпоративного использования и поддерживается мощной моделью IAM и управления.

С помощью Lenses вы можете находить, исследовать, преобразовывать, интегрировать и реплицировать данные в различных средах Kafka и от разных поставщиков. Теперь вся эта мощь доступна вашему ИИ-ассистенту или агенту через этот MCP-сервер Lenses для Kafka.

Посмотрите, как это работает, прогуливаясь по улицам Нью-Йорка!

Попробуйте сегодня бесплатную Lenses Community Edition (с ограничениями по количеству пользователей и корпоративным функциям). Lenses CE поставляется с предварительно настроенным одноброкерным кластером Kafka, что идеально подходит для локальной разработки или демонстрации. Подключите до двух собственных кластеров Kafka и используйте естественный язык для взаимодействия с вашими потоковыми данными.

Содержание

1. Установка uv и Python

Мы используем uv для управления зависимостями и настройки проекта. Если у вас не установлен uv, следуйте официальному руководству по установке.

Этот проект был создан с использованием Python 3.12. Чтобы убедиться, что Python установлен правильно, выполните следующую команду для проверки версии.

uv run python --version

2. Настройка переменных окружения

Скопируйте пример файла окружения.

cp .env.example .env

Откройте .env и заполните необходимые значения, такие как данные вашего экземпляра Lenses и API-ключ Lenses.

3. Добавление API-ключа Lenses

Создайте API-ключ Lenses, создав сервисную учетную запись IAM. Добавьте API-ключ в .env с именем переменной LENSES_API_KEY.

4. Установка зависимостей и запуск сервера

Используйте uv для создания виртуального окружения, установите в него зависимости проекта, а затем запустите MCP-сервер с помощью CLI FastMCP, используя транспорт stdio по умолчанию.

uv sync
uv run src/lenses_mcp/server.py

Для запуска в качестве удаленного сервера используйте транспорт http.

uv run fastmcp run src/lenses_mcp/server.py --transport=http --port=8000

Для запуска в Claude Desktop, Gemini CLI, Cursor и т.д. используйте следующую конфигурацию JSON.

{
  "mcpServers": {
    "Lenses.io": {
      "command": "uv",
      "args": [
        "run",
        "--project", "<ABSOLUTE_PATH_TO_THIS_REPO>",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "<ABSOLUTE_PATH_TO_THIS_REPO>/src/lenses_mcp/server.py"
      ],
      "env": {
        "LENSES_API_KEY": "<YOUR_LENSES_API_KEY>"
      },
      "transport": "stdio"
    }
  }
}

Примечание: некоторым клиентам может потребоваться абсолютный путь к uv в команде.

5. Опциональный MCP-сервер Context7

Документация Lenses доступна на Context7. Использование MCP-сервера Context7 является опциональным, но настоятельно рекомендуется. Настройте свои промпты с помощью use context7, чтобы документация, доступная LLM, была актуальной.

6. Запуск с помощью Docker

MCP-сервер Lenses доступен в виде Docker-образа lensesio/mcp. Вы можете запускать его с различными режимами транспорта в зависимости от вашего варианта использования.

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

Запуск сервера с транспортом stdio (по умолчанию):

docker run \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   lensesio/mcp

Запуск сервера с транспортом HTTP (слушает на http://0.0.0.0:8000/mcp):

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=http \
   lensesio/mcp

Запуск сервера с транспортом SSE (слушает на http://0.0.0.0:8000/sse):

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=sse \
   lensesio/mcp

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

Переменная	Обязательно	По умолчанию	Описание
`LENSES_API_KEY`	Да (если не используется OAuth)	-	Ваш API-ключ Lenses (создается через сервисную учетную запись IAM)
`LENSES_URL`	Нет	`http://localhost:9991`	URL экземпляра Lenses в формате `[scheme]://[host]:[port]`. Используйте `https://` для безопасных соединений (автоматически использует `wss://` для WebSockets)
`TRANSPORT`	Нет	`http`, если задан `MCP_ADVERTISED_URL`, иначе `stdio`	Режим транспорта: `stdio`, `http` или `sse`
`PORT`	Нет	`8000`	Порт для прослушивания (используется только с транспортом `http` или `sse`)
`MCP_ADVERTISED_URL`	Да для OAuth	-	Публичный базовый URL этого MCP-сервера, доступный клиентам. Установка этого параметра включает OAuth и устанавливает `TRANSPORT` в `http` по умолчанию (см. Аутентификация OAuth 2.1)
`LENSES_ADVERTISED_URL`	Нет	`LENSES_URL`	Публичный URL Lenses HQ, рекламируемый MCP-клиентам для входа через OAuth. Переопределяйте только в развертываниях с разделением плоскостей, где MCP-сервер достигает Lenses по внутреннему адресу
`MCP_SCOPES`	Нет	`read,write,delete`	Разделенные запятыми области OAuth (scopes), рекламируемые в метаданных защищенного ресурса
`INTROSPECTION_URL`	Нет	Обнаружено из метаданных `LENSES_ADVERTISED_URL`	Переопределение для URL конечной точки интроспекции токенов RFC 7662
`INTROSPECTION_CACHE_TTL`	Нет	`0` (отключено)	TTL кэша для результатов интроспекции в секундах

Устаревшие переменные окружения (для обратной совместимости):

LENSES_API_HTTP_URL, LENSES_API_HTTP_PORT
LENSES_API_WEBSOCKET_URL, LENSES_API_WEBSOCKET_PORT

Они автоматически выводятся из LENSES_URL, но могут быть явно заданы для переопределения.

Конечные точки транспорта

stdio: Стандартный ввод/вывод (без сетевой конечной точки)
http: Конечная точка HTTP по адресу /mcp
sse: Конечная точка Server-Sent Events по адресу /sse

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

Чтобы собрать Docker-образ локально:

docker build -t lensesio/mcp .

7. Аутентификация OAuth 2.1

Когда задан MCP_ADVERTISED_URL, MCP-сервер работает как защищенный ресурс OAuth 2.1 с полной интроспекцией токенов RFC 7662. Это заменяет статический подход LENSES_API_KEY на аутентификацию через bearer-токен для HTTP-транспортов, а также устанавливает TRANSPORT в http по умолчанию.

Как это работает

Процесс аутентификации включает трех участников: MCP-клиент, сервер авторизации (Lenses HQ по адресу LENSES_ADVERTISED_URL, который по умолчанию равен LENSES_URL) и этот MCP-сервер (сервер ресурсов).

MCP Client                    Auth Server                   MCP Server
    │                              │                             │
    │  1. GET /.well-known/        │                             │
    │     oauth-protected-resource │                             │
    │─────────────────────────────────────────────────────────►  │
    │  ◄── authorization_servers,                                │
    │      scopes_supported                                      │
    │                              │                             │
    │  2. POST /register (DCR)     │                             │
    │─────────────────────────────►│                             │
    │  ◄── client_id, secret       │                             │
    │                              │                             │
    │  3. /authorize + PKCE (S256) │                             │
    │─────────────────────────────►│                             │
    │  ◄── authorization_code      │                             │
    │                              │                             │
    │  4. POST /token              │                             │
    │─────────────────────────────►│                             │
    │  ◄── access_token            │                             │
    │                              │                             │
    │  5. MCP request + Bearer token                             │
    │─────────────────────────────────────────────────────────►  │
    │                              │  6. POST /oauth2/introspect │
    │                              │  ◄──────────────────────────│
    │                              │  ── active, scopes, exp ──► │
    │                              │                             │
    │  ◄── MCP response (or 401)                                 │
    │                              │                             │

Шаги 1–4 обрабатываются MCP-клиентом и сервером авторизации. MCP-сервер в них не участвует.

Шаги 5–6 — это проверка токена данным сервером:

Метаданные защищенного ресурса (RFC 9728) — RemoteAuthProvider обслуживает /.well-known/oauth-protected-resource/mcp, чтобы клиенты могли обнаружить, какой сервер авторизации использовать и какие области (scopes) доступны.
Автообнаружение — При первом входящем запросе DiscoveryTokenVerifier лениво извлекает {LENSES_ADVERTISED_URL}/.well-known/oauth-authorization-server для обнаружения introspection_endpoint. URL конечной точки также можно задать явно через INTROSPECTION_URL.
Интроспекция токена (RFC 7662) — Для каждого входящего bearer-токена верификатор отправляет POST-запрос на конечную точку интроспекции (/oauth2/introspect) без аутентификации клиента. Сервер авторизации отвечает:
- active — действителен ли токен
- scope — предоставленные области (например, read write)
- client_id — владелец токена
- exp — временная метка истечения срока действия
Неактивные или просроченные токены отклоняются до того, как они достигнут API Lenses.
Пересылка токена — Действительные токены пересылаются в API Lenses через Authorization: Bearer <token>, чтобы Lenses мог выполнить свои собственные проверки авторизации.

Области авторизации (scopes)

Сервер рекламирует три области в своих метаданных защищенного ресурса:

Область	Описание
`read`	Доступ только для чтения к ресурсам Lenses (топики, окружения, коннекторы и т.д.)
`write`	Создание и обновление ресурсов
`delete`	Удаление ресурсов

Области не применяются глобально на уровне интроспекции — токен с любым подмножеством этих областей принимается. Принудительное применение областей для конкретных инструментов можно добавить с помощью декоратора require_scopes в FastMCP.

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

В простом развертывании требуются только две переменные окружения:

LENSES_URL=https://lenses.example.com
MCP_ADVERTISED_URL=http://localhost:8000

TRANSPORT по умолчанию принимает значение http всякий раз, когда задан MCP_ADVERTISED_URL, поэтому вам не нужно задавать его явно. LENSES_ADVERTISED_URL по умолчанию равен LENSES_URL, поэтому его нужно задавать только в развертываниях с разделением плоскостей, где MCP-сервер достигает Lenses по внутреннему адресу, а клиенты — по публичному:

# Split-plane: MCP server → Lenses over internal DNS,
# MCP clients → Lenses over the public URL
LENSES_URL=http://lenses-hq.internal:9991
LENSES_ADVERTISED_URL=https://lenses.example.com
MCP_ADVERTISED_URL=https://mcp.example.com

Lenses HQ (доступный через LENSES_ADVERTISED_URL) должен поддерживать:

Метаданные сервера авторизации OAuth 2.0 (RFC 8414) по адресу /.well-known/oauth-authorization-server
Интроспекцию токенов (RFC 7662) на introspection_endpoint с отключенной аутентификацией клиента
PKCE с S256 (RFC 7636) для потоков авторизации клиентов

MCP-сервер не отправляет учетные данные клиента при интроспекции токена. На стороне Lenses HQ это требует:

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

в конфигурации Lenses HQ. Без этого флага конечная точка интроспекции отклонит неаутентифицированный POST-запрос MCP-сервера, и каждый bearer-токен будет отклонен как недействительный.

Запуск с OAuth

# Local development
LENSES_URL=https://lenses.example.com \
MCP_ADVERTISED_URL=http://localhost:8000 \
uv run src/lenses_mcp/server.py

# Docker
docker run -p 8000:8000 \
   -e LENSES_URL=https://lenses.example.com \
   -e MCP_ADVERTISED_URL=http://localhost:8000 \
   lensesio/mcp

Когда MCP_ADVERTISED_URL не задан, сервер возвращается к статическому LENSES_API_KEY для обратной совместимости, а TRANSPORT по умолчанию принимает значение stdio.

Lenses MCP Server