AI导哈

LLM观测性平台服务器

MCP Langfuse Server是一个用于管理和分析LLM应用追踪、数据集及其运行的服务，提供详细的性能、成本和质量管理功能。

  • by ramanarupa
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 ramanarupa/mcp-langfuse

使用说明

MCP Langfuse Server

MCP сервер для работы с Langfuse - платформой для observability LLM приложений.

Возможности

Работа с трейсами

  • get_trace - получить детальную информацию о трейсе по ID
  • list_traces - получить список трейсов с фильтрами
  • analyze_trace - анализ трейса с метриками производительности, стоимости и качества
  • compare_traces - сравнение нескольких трейсов

Работа с датасетами

  • get_dataset - получить информацию о датасете
  • list_datasets - получить список всех датасетов
  • get_dataset_items - получить элементы датасета
  • analyze_dataset - анализ структуры и содержимого датасета
  • upload_dataset_from_json - загрузка датасета из JSON файла
  • upload_dataset_from_xlsx - загрузка датасета из Excel файла (XLSX/XLS)

Работа с раннерами датасетов

  • get_dataset_runs - получить все запуски датасета
  • get_dataset_run - получить детальную информацию о запуске
  • analyze_dataset_run - анализ метрик запуска
  • compare_dataset_runs - сравнение нескольких запусков

Установка

Глобальная установка из npm (рекомендуется)

npm install -g mcp-langfuse

После установки команда mcp-langfuse будет доступна глобально.

Установка из исходников

git clone https://github.com/yourusername/mcp-langfuse.git
cd mcp-langfuse
npm install
npm run build

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

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

1. Через конфигурацию Claude CLI (рекомендуется)

В файле ~/.config/claude/config.json укажите ключи в секции env:

{
  "mcpServers": {
    "langfuse": {
      "command": "node",
      "args": ["/home/rgaifiev/repo/mcp-langfuse/dist/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

2. Через .env файл

Создайте файл .env в корне проекта:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com

Примечание: Для самостоятельного развертывания Langfuse укажите свой URL в LANGFUSE_HOST.

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

После подключения сервера вы можете использовать естественный язык для взаимодействия с Langfuse:

Анализ трейсов

Проанализируй трейс с ID trace-abc123

Claude использует инструмент analyze_trace и возвращает:

  • Общую информацию о трейсе
  • Метрики производительности (latency)
  • Стоимость (total, input, output costs)
  • Использование токенов
  • Оценки качества (scores)
  • Структуру observations
Сравни трейсы trace-123, trace-456 и trace-789

Claude использует compare_traces и показывает сравнительную таблицу с метриками для каждого трейса.

Работа с датасетами

Покажи все мои датасеты

Загрузи датасет из файла /path/to/dataset.json с именем "qa-dataset"

Загрузи датасет из Excel файла Manual_GoldenDraft_45q_v1.2.xlsx с именем "legal-qa"

Claude автоматически определит колонки Question/Answer или input/expectedOutput и загрузит датасет.

Формат JSON файла для загрузки:

[
  {
    "input": "What is the capital of France?",
    "expectedOutput": "Paris",
    "metadata": {
      "category": "geography",
      "difficulty": "easy"
    }
  },
  {
    "input": "Explain quantum computing",
    "expectedOutput": "Quantum computing is...",
    "metadata": {
      "category": "technology",
      "difficulty": "hard"
    }
  }
]

Проанализируй датасет qa-dataset

Анализ запусков (раннеров)

Покажи все запуски датасета qa-dataset

Проанализируй запуск experiment-1 датасета qa-dataset

Возвращает:

  • Количество элементов
  • Агрегированные метрики (latency, cost)
  • Средние оценки качества
  • Детали по каждому элементу
Сравни запуски experiment-1, experiment-2 и experiment-3 для датасета qa-dataset

Фильтрация трейсов

Покажи трейсы пользователя user-123 за последнюю неделю

Найди все трейсы с тегом "production" с именем "gpt-4-chat"

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

Вариант 1: Установка из npm (проще)

  1. Установите пакет глобально:

    npm install -g mcp-langfuse

  2. Получите API ключи от Langfuse:

    • Перейдите на https://cloud.langfuse.com/settings
    • Создайте новый API ключ
    • Скопируйте Public Key и Secret Key

  3. Добавьте сервер в Claude CLI:

    Отредактируйте ~/.config/claude/config.json:

    {
  "mcpServers": {
    "langfuse": {
      "command": "mcp-langfuse",
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-ваш-ключ",
        "LANGFUSE_SECRET_KEY": "sk-lf-ваш-секрет",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

  4. Перезапустите Claude CLI и начните работать:

    claude

    Попробуйте команды:

    • "Покажи все мои датасеты в Langfuse"
    • "Загрузи датасет из файла"

Вариант 2: Установка из исходников

  1. Клонируйте репозиторий:

    git clone https://github.com/yourusername/mcp-langfuse.git
cd mcp-langfuse
npm install
npm run build

  2. Настройте Claude CLI с абсолютным путем:

    {
  "mcpServers": {
    "langfuse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-langfuse/dist/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-ваш-ключ",
        "LANGFUSE_SECRET_KEY": "sk-lf-ваш-секрет",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

Формат JSON для датасетов

Каждый элемент в массиве должен содержать:

  • input (обязательно) - входные данные (может быть строкой или объектом)
  • expectedOutput или expected_output (опционально) - ожидаемый выход
  • metadata (опционально) - метаданные элемента

Примеры:

Простой формат:

[
  {
    "input": "What is the capital of France?",
    "expectedOutput": "Paris",
    "metadata": {
      "difficulty": "easy",
      "topic": "geography"
    }
  }
]

Структурированный input:

[
  {
    "input": {
      "question": "What is 2+2?",
      "context": "Basic arithmetic"
    },
    "expectedOutput": "4",
    "metadata": {
      "difficulty": "easy",
      "topic": "math"
    }
  }
]

В проекте есть файл example-dataset.json с примерами.

Формат Excel (XLSX/XLS) для датасетов

MCP сервер автоматически распознает структуру Excel файлов и конвертирует их в датасеты Langfuse.

Автоматическое определение колонок

Сервер автоматически ищет колонки:

  • Input: Question, input, query, prompt (или первая колонка)
  • Expected Output: Answer, expectedOutput, expected_output, output, response
  • Metadata: все остальные колонки (кроме #, id, пустых колонок)

Пример структуры Excel файла

# Category/type Question Answer Related Docs Notes
1 multi-context Как маркируется бытовая техника? Закон 306... https://...
2 simple Что такое энергоэффективность? Энергоэффективность... https://... Важно

Этот файл будет преобразован в:

[
  {
    "input": "Как маркируется бытовая техника?",
    "expectedOutput": "Закон 306...",
    "metadata": {
      "Category/type": "multi-context",
      "Related Docs": "https://...",
      "Notes": ""
    }
  },
  ...
]

Ручная настройка маппинга

Если у вас нестандартные названия колонок, укажите их явно:

Загрузи датасет из Excel файла data.xlsx,
используй колонку "Вопрос" как input,
колонку "Ожидаемый ответ" как expectedOutput,
и добавь в метаданные колонки "Категория" и "Источник"

Поддерживаемые форматы

  • .xlsx (Excel 2007+)
  • .xls (Excel 97-2003)
  • Несколько листов (можно указать конкретный лист)
  • Автоматическая фильтрация пустых строк

Доступные инструменты (для справки)

Все инструменты вызываются автоматически через Claude CLI при использовании естественного языка. Эта документация для справки.

Трейсы

get_trace

Получает полную информацию о трейсе.

Параметры:

  • trace_id (string, required) - ID трейса

list_traces

Список трейсов с фильтрацией.

Параметры:

  • page (number, optional) - номер страницы
  • limit (number, optional) - количество на странице (max 100)
  • name (string, optional) - фильтр по имени
  • user_id (string, optional) - фильтр по пользователю
  • tags (string[], optional) - фильтр по тегам
  • from_timestamp (string, optional) - с какой даты (ISO 8601)
  • to_timestamp (string, optional) - по какую дату (ISO 8601)

analyze_trace

Анализирует трейс и возвращает агрегированные метрики.

Параметры:

  • trace_id (string, required) - ID трейса

Возвращает:

  • Информацию о трейсе
  • Метрики производительности
  • Стоимость
  • Токены
  • Scores
  • Структуру observations

compare_traces

Сравнивает несколько трейсов.

Параметры:

  • trace_ids (string[], required) - массив ID трейсов (2-10)

Возвращает:

  • Сводную статистику
  • Сравнительную таблицу
  • Детальную информацию по каждому трейсу

Датасеты

get_dataset

Получает информацию о датасете.

Параметры:

  • dataset_name (string, required) - имя датасета

list_datasets

Список всех датасетов.

Параметры:

  • page (number, optional)
  • limit (number, optional)

get_dataset_items

Получает элементы датасета.

Параметры:

  • dataset_name (string, required)
  • page (number, optional)
  • limit (number, optional)

analyze_dataset

Анализирует структуру датасета.

Параметры:

  • dataset_name (string, required)

upload_dataset_from_json

Загружает датасет из JSON файла.

Параметры:

  • dataset_name (string, required) - имя датасета
  • json_file_path (string, required) - путь к JSON файлу
  • description (string, optional) - описание
  • metadata (object, optional) - метаданные

upload_dataset_from_xlsx

Загружает датасет из Excel файла (XLSX/XLS) с автоматическим определением колонок.

Параметры:

  • dataset_name (string, required) - имя датасета
  • xlsx_file_path (string, required) - путь к Excel файлу
  • input_column (string, optional) - имя колонки для input (авто-определение: Question, input, query, prompt)
  • expected_output_column (string, optional) - имя колонки для expected output (авто-определение: Answer, expectedOutput, output)
  • metadata_columns (string[], optional) - список колонок для metadata (авто-определение: все остальные колонки)
  • sheet_name (string, optional) - имя листа (по умолчанию: первый лист)
  • description (string, optional) - описание датасета
  • dataset_metadata (object, optional) - метаданные датасета

Возвращает:

  • Количество загруженных элементов
  • Используемый лист
  • Автоматически определенные колонки
  • Список загруженных элементов

Раннеры

get_dataset_runs

Список запусков датасета.

Параметры:

  • dataset_name (string, required)
  • page (number, optional)
  • limit (number, optional)

get_dataset_run

Детальная информация о запуске.

Параметры:

  • dataset_name (string, required)
  • run_name (string, required)

analyze_dataset_run

Анализ метрик запуска.

Параметры:

  • dataset_name (string, required)
  • run_name (string, required)

compare_dataset_runs

Сравнение нескольких запусков.

Параметры:

  • dataset_name (string, required)
  • run_names (string[], required) - массив имен запусков (2-10)

Разработка

# Установка зависимостей
npm install

# Сборка
npm run build

# Разработка с автоматической пересборкой
npm run watch

# Запуск
npm run start

Устранение неполадок

Сервер не подключается

Убедитесь, что:

  1. Проект собран: npm run build
  2. Путь к dist/index.js в конфигурации правильный
  3. API ключи указаны корректно
  4. У вас установлен Node.js (рекомендуется v18+)

Ошибки API

Error: Langfuse API error: 401

Проверьте правильность LANGFUSE_PUBLIC_KEY и LANGFUSE_SECRET_KEY.

Error: Langfuse API error: 404

Проверьте, что LANGFUSE_HOST указан правильно (без trailing slash).

Проверка работы сервера

После добавления в конфигурацию Claude CLI, проверьте:

claude

Затем спросите:

Какие MCP серверы у меня подключены?

Claude должен показать langfuse в списке.

Логи

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

node dist/index.js

Сервер выведет сообщение при запуске: MCP Langfuse server running on stdio

Дополнительные ресурсы

Лицензия

MIT

相关 MCP