langsmith-mcp-server 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LangChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# LangSmith MCP Server (TypeScript)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js 18+](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org/)
+
+A TypeScript implementation of the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server for [LangSmith](https://smith.langchain.com). This is a full port of the official [Python LangSmith MCP Server](https://github.com/langchain-ai/langsmith-mcp-server) with 100% functional parity.
+
+## Example Use Cases
+
+The server enables powerful capabilities including:
+
+- **Conversation History**: "Fetch the history of my conversation from thread 'thread-123' in project 'my-chatbot'" (paginated by character budget)
+- **Prompt Management**: "Get all public prompts in my workspace" / "Pull the template for the 'legal-case-summarizer' prompt"
+- **Traces & Runs**: "Fetch the latest 10 root runs from project 'alpha'" / "Get all runs for trace \<uuid\> (page 2 of 5)"
+- **Datasets**: "List datasets of type chat" / "Read examples from dataset 'customer-support-qa'"
+- **Experiments**: "List experiments for dataset 'my-eval-set' with latency and cost metrics"
+- **Billing**: "Get billing usage for September 2025"
+
+## Quick Start
+
+```bash
+LANGSMITH_API_KEY=your-key npx langsmith-mcp-server
+```
+
+## Available Tools
+
+The LangSmith MCP Server provides the following tools for integration with LangSmith.
+
+### Conversation & Threads
+
+| Tool Name | Description |
+|-----------|-------------|
+| `get_thread_history` | Retrieve message history for a conversation thread. Uses **char-based pagination**: pass `page_number` (1-based), and use returned `total_pages` to request more pages. Optional `max_chars_per_page` and `preview_chars` control page size and long-string truncation. |
+
+### Prompt Management
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_prompts` | Fetch prompts from LangSmith with optional filtering by visibility (public/private) and limit. |
+| `get_prompt_by_name` | Get a specific prompt by its exact name, returning the prompt details and template. |
+| `push_prompt` | Documentation-only: how to create and push prompts to LangSmith. |
+
+### Traces & Runs
+
+| Tool Name | Description |
+|-----------|-------------|
+| `fetch_runs` | Fetch LangSmith runs (traces, tools, chains, etc.) from one or more projects. Supports filters (run_type, error, is_root), FQL (`filter`, `trace_filter`, `tree_filter`), and ordering. All results are **automatically paginated** by character budget. Always pass `limit` and `page_number`. |
+| `list_projects` | List LangSmith projects with optional filtering by name, dataset, and detail level (simplified vs full). |
+
+### Datasets & Examples
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_datasets` | Fetch datasets with filtering by ID, type, name, name substring, or metadata. |
+| `list_examples` | Fetch examples from a dataset by dataset ID/name or example IDs, with filter, metadata, splits, and optional `as_of` version. |
+| `read_dataset` | Read a single dataset by ID or name. |
+| `read_example` | Read a single example by ID, with optional `as_of` version. |
+| `create_dataset` | Documentation-only: how to create datasets in LangSmith. |
+| `update_examples` | Documentation-only: how to update dataset examples in LangSmith. |
+
+### Experiments & Evaluations
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_experiments` | List experiment projects (reference projects) for a dataset. Requires `reference_dataset_id` or `reference_dataset_name`. Returns key metrics (latency, cost, feedback stats). |
+| `run_experiment` | Documentation-only: how to run experiments and evaluations in LangSmith. |
+
+### Usage & Billing
+
+| Tool Name | Description |
+|-----------|-------------|
+| `get_billing_usage` | Fetch organization billing usage (e.g. trace counts) for a date range. Optional workspace filter; returns metrics with workspace names inline. |
+
+### Pagination (char-based)
+
+Several tools use **stateless, character-budget pagination** so responses stay within a size limit and work well with LLM clients:
+
+- **Where it's used:** `get_thread_history` and `fetch_runs`.
+- **Parameters:** You send `page_number` (1-based) on every request. Optional: `max_chars_per_page` (default 25000, cap 30000) and `preview_chars` (truncate long strings with "... (+N chars)").
+- **Response:** Each response includes `page_number`, `total_pages`, and the page payload (`result` for messages, `runs` for runs). To get more, call again with `page_number = 2`, then `3`, up to `total_pages`.
+- **Why it's useful:** Pages are built by JSON character count, not item count, so each page fits within a fixed size. No cursor or server-side state -- just integer page numbers.
+
+## Installation
+
+### From npm
+
+```bash
+npx langsmith-mcp-server
+```
+
+### MCP Client Integration
+
+#### Cursor / Claude Code
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "langsmith": {
+      "command": "npx",
+      "args": ["langsmith-mcp-server"],
+      "env": {
+        "LANGSMITH_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `LANGSMITH_API_KEY` | Yes | Your LangSmith API key for authentication | `lsv2_pt_1234567890` |
+| `LANGSMITH_WORKSPACE_ID` | No | Workspace ID for API keys scoped to multiple workspaces | `your_workspace_id` |
+| `LANGSMITH_ENDPOINT` | No | Custom API endpoint URL (for self-hosted or EU region) | `https://eu.api.smith.langchain.com` |
+
+**Notes:**
+- Only `LANGSMITH_API_KEY` is required for basic functionality
+- `LANGSMITH_WORKSPACE_ID` is useful when your API key has access to multiple workspaces
+- `LANGSMITH_ENDPOINT` allows you to use custom endpoints for self-hosted LangSmith installations or the EU region
+
+## Development and Contributing
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/langchain-ai/langsmith-mcp-server-js.git
+cd langsmith-mcp-server-js
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+LANGSMITH_API_KEY=your-key npm run dev
+
+# Run production build
+LANGSMITH_API_KEY=your-key npm start
+```
+
+### Testing
+
+```bash
+# Run unit tests
+npm test
+```
+
+### MCP Inspector
+
+For interactive development and debugging, use the MCP Inspector:
+
+```bash
+LANGSMITH_API_KEY=your-key npx @modelcontextprotocol/inspector npx .
+```
+
+This opens a browser UI where you can browse all tools, inspect their schemas, and invoke them interactively.
+
+### Verify the server responds
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | LANGSMITH_API_KEY=test npx . 2>/dev/null
+```
+
+### Architecture
+
+This is a direct port of the [Python LangSmith MCP Server](https://github.com/langchain-ai/langsmith-mcp-server) with the same module structure:
+
+```
+src/
+  index.ts                    # Entry point (stdio transport)
+  server.ts                   # McpServer setup
+  common/
+    helpers.ts                # Client creation, data conversion utilities
+    pagination.ts             # Char-based stateless pagination
+    formatters.ts             # Message extraction and formatting
+  services/
+    register-tools.ts         # MCP tool registration with Zod schemas
+    tools/
+      prompts.ts              # Prompt management tools
+      traces.ts               # Trace/run/project tools
+      datasets.ts             # Dataset and example tools
+      experiments.ts          # Experiment listing tools
+      usage.ts                # Billing/usage REST API tools
+```
+
+## Contributing
+
+This TypeScript implementation is a community port of the official [Python LangSmith MCP Server](https://github.com/langchain-ai/langsmith-mcp-server) by [LangChain](https://langchain.com).
+
+Contributions are welcome! Please open an issue or pull request on GitHub.
+
+## License
+
+This project is distributed under the MIT License. For detailed terms and conditions, please refer to the [LICENSE](LICENSE) file.

package/dist/common/formatters.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Output formatting utilities for messages and run.
+ */
+/**
+ * Format messages as pretty-printed JSON.
+ *
+ * @param messages - List of message objects
+ * @returns JSON string (indent=2) representation of messages
+ */
+export declare function formatMessages(messages: Record<string, unknown>[]): string;
+/**
+ * Extract messages from a run dictionary.
+ *
+ * Messages can be in various locations:
+ * - run.inputs.messages (for LLM runs)
+ * - run.outputs.messages (for some run types)
+ * - run.outputs.output.messages (for nested output structures)
+ * - run.outputs.choices[0].message (for OpenAI-style outputs)
+ *
+ * @param runDict - Run dictionary from LangSmith
+ * @returns List of message dictionaries
+ */
+export declare function extractMessagesFromRun(runDict: Record<string, unknown>): Record<string, unknown>[];
+/**
+ * Extract messages from runs and return pretty-printed JSON in "formatted".
+ */
+export declare function formatRunsWithMessages(runs: Record<string, unknown>[]): Record<string, unknown>;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/common/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/common/formatters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAClC,MAAM,CAER;AA8GD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAqC3B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB"}

package/dist/common/formatters.js

@@ -0,0 +1,150 @@
+/**
+ * Output formatting utilities for messages and run.
+ */
+/**
+ * Format messages as pretty-printed JSON.
+ *
+ * @param messages - List of message objects
+ * @returns JSON string (indent=2) representation of messages
+ */
+export function formatMessages(messages) {
+    return JSON.stringify(messages, null, 2);
+}
+/**
+ * Recursively extract messages from nested dictionary structures.
+ *
+ * @param data - Dictionary, list, or other data structure to search
+ * @param _path - Current path in the structure (for debugging)
+ * @param depth - Current recursion depth
+ * @param maxDepth - Maximum recursion depth to avoid infinite loops
+ * @returns List of message dictionaries found
+ */
+function extractMessagesFromDict(data, _path = "", depth = 0, maxDepth = 5) {
+    if (depth > maxDepth) {
+        return [];
+    }
+    const messages = [];
+    if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+        const obj = data;
+        // Check for messages key directly (highest priority)
+        if ("messages" in obj) {
+            const msgs = obj.messages;
+            if (Array.isArray(msgs)) {
+                for (const msg of msgs) {
+                    if (typeof msg === "object" && msg !== null && !Array.isArray(msg)) {
+                        messages.push(msg);
+                    }
+                }
+                return messages; // Return early since we found messages
+            }
+        }
+        // Check for single message key
+        if ("message" in obj) {
+            const msg = obj.message;
+            if (typeof msg === "object" && msg !== null && !Array.isArray(msg)) {
+                messages.push(msg);
+            }
+        }
+        // Check for OpenAI-style choices
+        if ("choices" in obj) {
+            const choices = obj.choices;
+            if (Array.isArray(choices)) {
+                for (const choice of choices) {
+                    if (typeof choice === "object" &&
+                        choice !== null &&
+                        !Array.isArray(choice)) {
+                        const choiceObj = choice;
+                        if ("message" in choiceObj) {
+                            const msg = choiceObj.message;
+                            if (typeof msg === "object" &&
+                                msg !== null &&
+                                !Array.isArray(msg)) {
+                                messages.push(msg);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // If we found messages at this level, return them (don't recurse)
+        if (messages.length > 0) {
+            return messages;
+        }
+        // Recursively search nested dictionaries
+        for (const [key, value] of Object.entries(obj)) {
+            if (typeof value === "object" &&
+                value !== null) {
+                const nestedMsgs = extractMessagesFromDict(value, `${_path}.${key}`, depth + 1, maxDepth);
+                messages.push(...nestedMsgs);
+            }
+        }
+    }
+    else if (Array.isArray(data)) {
+        for (const item of data) {
+            if (typeof item === "object" && item !== null) {
+                const nestedMsgs = extractMessagesFromDict(item, `${_path}[]`, depth + 1, maxDepth);
+                messages.push(...nestedMsgs);
+            }
+        }
+    }
+    return messages;
+}
+/**
+ * Extract messages from a run dictionary.
+ *
+ * Messages can be in various locations:
+ * - run.inputs.messages (for LLM runs)
+ * - run.outputs.messages (for some run types)
+ * - run.outputs.output.messages (for nested output structures)
+ * - run.outputs.choices[0].message (for OpenAI-style outputs)
+ *
+ * @param runDict - Run dictionary from LangSmith
+ * @returns List of message dictionaries
+ */
+export function extractMessagesFromRun(runDict) {
+    const messages = [];
+    // Check inputs for messages
+    const inputs = runDict.inputs;
+    if (inputs !== undefined && inputs !== null) {
+        const inputMessages = extractMessagesFromDict(inputs, "inputs");
+        messages.push(...inputMessages);
+    }
+    // Check outputs for messages (including nested structures)
+    const outputs = runDict.outputs;
+    if (outputs !== undefined && outputs !== null) {
+        const outputMessages = extractMessagesFromDict(outputs, "outputs");
+        messages.push(...outputMessages);
+    }
+    // Filter to ensure we only return message dictionaries
+    // Deduplicate messages by ID if present
+    const validMessages = [];
+    const seenIds = new Set();
+    for (const msg of messages) {
+        if (typeof msg !== "object" || msg === null || Array.isArray(msg)) {
+            continue;
+        }
+        const msgId = msg.id;
+        if (typeof msgId === "string") {
+            if (seenIds.has(msgId)) {
+                continue;
+            }
+            seenIds.add(msgId);
+        }
+        validMessages.push(msg);
+    }
+    return validMessages;
+}
+/**
+ * Extract messages from runs and return pretty-printed JSON in "formatted".
+ */
+export function formatRunsWithMessages(runs) {
+    const allMessages = [];
+    for (const run of runs) {
+        const runMessages = extractMessagesFromRun(run);
+        if (runMessages.length > 0) {
+            allMessages.push(...runMessages);
+        }
+    }
+    return { formatted: formatMessages(allMessages) };
+}
+//# sourceMappingURL=formatters.js.map

package/dist/common/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../../src/common/formatters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAmC;IAEnC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,uBAAuB,CAC9B,IAAa,EACb,QAAgB,EAAE,EAClB,QAAgB,CAAC,EACjB,WAAmB,CAAC;IAEpB,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAE/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,GAAG,GAAG,IAA+B,CAAC;QAE5C,qDAAqD;QACrD,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;YAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;wBACnE,QAAQ,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC;oBAChD,CAAC;gBACH,CAAC;gBACD,OAAO,QAAQ,CAAC,CAAC,uCAAuC;YAC1D,CAAC;QACH,CAAC;QAED,+BAA+B;QAC/B,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC;YACxB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnE,QAAQ,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,IAAI,SAAS,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,IACE,OAAO,MAAM,KAAK,QAAQ;wBAC1B,MAAM,KAAK,IAAI;wBACf,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACtB,CAAC;wBACD,MAAM,SAAS,GAAG,MAAiC,CAAC;wBACpD,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;4BAC3B,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC;4BAC9B,IACE,OAAO,GAAG,KAAK,QAAQ;gCACvB,GAAG,KAAK,IAAI;gCACZ,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EACnB,CAAC;gCACD,QAAQ,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC;4BAChD,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,kEAAkE;QAClE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,yCAAyC;QACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,IACE,OAAO,KAAK,KAAK,QAAQ;gBACzB,KAAK,KAAK,IAAI,EACd,CAAC;gBACD,MAAM,UAAU,GAAG,uBAAuB,CACxC,KAAK,EACL,GAAG,KAAK,IAAI,GAAG,EAAE,EACjB,KAAK,GAAG,CAAC,EACT,QAAQ,CACT,CAAC;gBACF,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC9C,MAAM,UAAU,GAAG,uBAAuB,CACxC,IAAI,EACJ,GAAG,KAAK,IAAI,EACZ,KAAK,GAAG,CAAC,EACT,QAAQ,CACT,CAAC;gBACF,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAgC;IAEhC,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAE/C,4BAA4B;IAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,aAAa,GAAG,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAChE,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IAClC,CAAC;IAED,2DAA2D;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,cAAc,GAAG,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC;IACnC,CAAC;IAED,uDAAuD;IACvD,wCAAwC;IACxC,MAAM,aAAa,GAA8B,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAClE,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;QACrB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,SAAS;YACX,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA+B;IAE/B,MAAM,WAAW,GAA8B,EAAE,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,WAAW,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,WAAW,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;AACpD,CAAC"}

package/dist/common/helpers.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Helper functions for the LangSmith MCP server.
+ */
+import { Client } from "langsmith";
+/**
+ * Create a LangSmith client from environment variables.
+ *
+ * Reads LANGSMITH_API_KEY (required), LANGSMITH_ENDPOINT (optional),
+ * and LANGSMITH_WORKSPACE_ID (optional) from the environment.
+ *
+ * @returns LangSmith Client instance
+ * @throws Error if LANGSMITH_API_KEY is not set
+ */
+export declare function getLangSmithClient(): Client;
+/**
+ * Get API key and endpoint from environment variables.
+ * Used by tools that call LangSmith REST APIs directly (e.g. billing/usage).
+ *
+ * @returns Tuple of [apiKey, endpoint]. Endpoint is normalized (no trailing slash).
+ * @throws Error if LANGSMITH_API_KEY is not set
+ */
+export declare function getApiKeyAndEndpoint(): [string, string];
+/**
+ * Extract a LangGraph app host name from run stats.
+ *
+ * @param runStats - The run stats object
+ * @returns The LangGraph app host name, or undefined if not found
+ */
+export declare function getLanggraphAppHostName(runStats: Record<string, unknown>): string | undefined;
+/**
+ * Parse the as_of parameter, converting ISO timestamps to Date objects
+ * while leaving version tags as strings.
+ *
+ * @param asOf - Dataset version tag OR ISO timestamp string
+ * @returns Date object if asOf is a valid ISO timestamp, otherwise the original string
+ */
+export declare function parseAsOfParameter(asOf: string): Date | string;
+/**
+ * Recursively search for a key in a nested dictionary or list.
+ * Returns the first occurrence found during depth-first traversal.
+ *
+ * @param data - The data structure to search in
+ * @param key - The key to search for
+ * @returns The value associated with the key if found, otherwise undefined
+ */
+export declare function findInDict(data: unknown, key: string): unknown | undefined;
+/**
+ * Recursively convert Date objects to ISO strings in data structures.
+ * Note: In the JS SDK, UUIDs are already strings, unlike the Python SDK
+ * where they are uuid.UUID objects. This function primarily handles Dates.
+ */
+export declare function convertToSerializable(obj: unknown): unknown;
+/**
+ * Recursively count the total number of characters in a data structure.
+ */
+export declare function countCharacters(obj: unknown): number;
+/**
+ * Recursively count the total number of fields/keys in a data structure.
+ */
+export declare function countFields(obj: unknown): number;
+/**
+ * Filter a run dictionary to only include selected fields.
+ * If select is undefined or empty, returns the full dictionary.
+ */
+export declare function filterFields(runDict: Record<string, unknown>, select?: string[]): Record<string, unknown>;
+/**
+ * Build a simplified trace tree structure showing top-level fields
+ * with metrics for nested content.
+ *
+ * @param runDict - The dictionary to build a tree from
+ * @param depth - How many levels deep to show actual content before summarizing.
+ *               0 = summarize all nested structures (default)
+ */
+export declare function buildTraceTree(runDict: Record<string, unknown>, depth?: number): Record<string, unknown>;
+/**
+ * Parse a JSON array string into an array of strings.
+ * If the value starts with "[", parse as JSON array.
+ * Otherwise, wrap in a single-element array.
+ */
+export declare function parseJsonArray(value: string | undefined): string[] | undefined;
+/**
+ * Parse a JSON object string into a Record.
+ * If the value starts with "{", parse as JSON object.
+ * Otherwise, return undefined.
+ */
+export declare function parseJsonObject(value: string | undefined): Record<string, unknown> | undefined;
+/**
+ * Parse a boolean string ("true"/"false") to a boolean value.
+ */
+export declare function parseBoolString(value: string | undefined): boolean | undefined;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/common/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/common/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAY3C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,GAAG,SAAS,CAoBpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAU9D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,GACV,OAAO,GAAG,SAAS,CAqBrB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAkB3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAoBpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAgBhD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,GAAE,MAAU,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyFzB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAUrC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAG9E"}