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

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

• CONFIGURATION.md - Детальное руководство по конфигурации
• USAGE_EXAMPLES.md - Практические сценарии использования
• EXCEL_SUPPORT.md - Полное руководство по работе с Excel файлами
• PUBLISHING.md - Инструкции по публикации в npm
• Langfuse Documentation - Официальная документация Langfuse
• MCP Documentation - Документация Model Context Protocol

Лицензия

MIT