langsmith-mcp-server-js: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TypeScript MCP (Model Context Protocol) server for LangSmith. It is a direct port of the official Python LangSmith MCP Server with 100% functional parity. It exposes 16 tools that give LLM clients access to LangSmith's observability platform (prompts, traces, datasets, experiments, billing). Uses stdio transport.

Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript (tsc → dist/)
npm run dev          # Run with tsx (development, requires LANGSMITH_API_KEY)
npm start            # Run compiled dist/index.js (production)
npm test             # Run all tests (vitest run)

Debug interactively with MCP Inspector:

LANGSMITH_API_KEY=your-key npx @modelcontextprotocol/inspector npx .

Architecture

Entry flow: src/index.ts creates a StdioServerTransport, src/server.ts creates the McpServer and calls registerTools().

Tool registration: src/services/register-tools.ts registers all 16 MCP tools with Zod input schemas. Each tool delegates to an implementation in src/services/tools/ organized by domain:

• prompts.ts — list/get prompts
• traces.ts — fetch runs, list projects, get thread history, project stats
• datasets.ts — list/read datasets and examples
• experiments.ts — list experiments with metrics
• usage.ts — billing usage via direct REST API (not LangSmith SDK)

Common utilities (src/common/):

• helpers.ts — LangSmith client creation (getLangSmithClient()), data serialization (Date/BigInt → JSON-safe), recursive field search, trace tree building
• pagination.ts — Stateless character-budget pagination. Pages are built by JSON character count (not item count), max 30000 chars/page. Uses binary search for optimal truncation. No server-side state — just integer page numbers.
• formatters.ts — Message extraction from runs (supports multiple formats including OpenAI-style choices[].message), deduplication by message ID