Skip to content

feat: Add observability tools (traces, scores, datasets, sessions)#15

Open
JaviMaligno wants to merge 1 commit into
langfuse:mainfrom
JaviMaligno:feat/observability-tools
Open

feat: Add observability tools (traces, scores, datasets, sessions)#15
JaviMaligno wants to merge 1 commit into
langfuse:mainfrom
JaviMaligno:feat/observability-tools

Conversation

@JaviMaligno

Copy link
Copy Markdown

Summary

This PR adds 22 new tools for accessing Langfuse observability data, addressing Issue #14 and Discussion #5646.

Tools Added

Category Tools Description
Traces (2) list-traces, get-trace List and retrieve traces with filtering
Observations (2) list-observations, get-observation List and retrieve observations
Scores (4) create-score, list-scores, get-score, delete-score Full CRUD for scores
Score Configs (3) create-score-config, list-score-configs, get-score-config Manage score configurations
Datasets (9) create-dataset, list-datasets, get-dataset, create-dataset-item, list-dataset-items, get-dataset-item, create-dataset-run-item, list-dataset-runs, get-dataset-run Complete dataset management
Sessions (2) list-sessions, get-session List and retrieve sessions

Key Features

  • Uses Langfuse SDK api namespace for type-safe API calls (as suggested by @marcklingen)
  • Type coercion with z.coerce.number() to handle MCP clients that pass strings
  • includeIO parameter on get operations to control response size (prevents exceeding LLM context limits)
  • Modular structure in src/tools/ directory for maintainability

Structure

src/
├── index.ts              (modified: imports and registers tools)
└── tools/
    ├── index.ts          (exports registerAllObservabilityTools)
    ├── traces.ts         (2 tools)
    ├── observations.ts   (2 tools)
    ├── scores.ts         (4 tools)
    ├── score-configs.ts  (3 tools)
    ├── datasets.ts       (9 tools)
    └── sessions.ts       (2 tools)

Testing

  • Tested against self-hosted Langfuse instance (v3.124.1)
  • All tools verified working with MCP Inspector
  • Integration tests passing (36/36)

Test Plan

  • Build passes (npm run build)
  • MCP Inspector shows 24 tools (2 prompt + 22 observability)
  • list-traces returns paginated trace list
  • get-trace returns trace with observations and scores
  • create-score creates a score on a trace
  • list-datasets returns dataset list
  • get-session returns session with traces

Closes #14

🤖 Generated with Claude Code

Add 22 new tools for accessing Langfuse observability data:

Traces (2 tools):
- list-traces: List traces with filtering and pagination
- get-trace: Get a specific trace with observations and scores

Observations (2 tools):
- list-observations: List observations with filtering
- get-observation: Get a specific observation

Scores (4 tools):
- create-score: Create scores (numeric, boolean, categorical)
- list-scores: List scores with filtering
- get-score: Get a specific score
- delete-score: Delete a score

Score Configs (3 tools):
- create-score-config: Create score configuration templates
- list-score-configs: List all score configurations
- get-score-config: Get a specific score configuration

Datasets (9 tools):
- create-dataset: Create a new dataset
- list-datasets: List all datasets
- get-dataset: Get a dataset by name
- create-dataset-item: Create or update dataset items
- list-dataset-items: List items in a dataset
- get-dataset-item: Get a specific dataset item
- create-dataset-run-item: Link traces to dataset items
- list-dataset-runs: List runs for a dataset
- get-dataset-run: Get a specific dataset run

Sessions (2 tools):
- list-sessions: List all sessions
- get-session: Get a session with its traces

Key features:
- Uses Langfuse SDK api namespace for type-safe API calls
- Type coercion with z.coerce.number() for MCP string parameters
- includeIO parameter on get operations to control response size
- Modular structure in src/tools/ directory

Closes langfuse#14

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@CLAassistant

CLAassistant commented Dec 27, 2025

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Add traces, scores, datasets, and sessions tools

2 participants