How honeyhiveai/typescript-sdk works
Project and Its Purpose
• HoneyHive is an SDK (and also an MCP server) designed to allow users and AI applications to interact with a range of resources (configurations, datapoints, datasets, events, experiments, metrics, projects, sessions, and tools) through a programmatically generated API.
• It supports both client-side usage (e.g., through standalone functions and API calls) and a standalone server mode (the MCP server that can be launched via CLI).
Main Components
a. SDK Client Library:
– Encapsulates authentication (bearerAuth), server URL handling, retry strategies, and debugging configuration.
– Provides access to a suite of functions (as seen in the “Available Resources and Operations” lists) with methods like create, update, delete and get for configurations, datapoints, datasets, etc.
– Organizes functions into modules (e.g., src/sdk, src/funcs). The core entry point is in src/index.ts and src/core.ts.
b. HTTP Client:
– A lightweight wrapper around the Fetch API (found in src/lib/http.ts) that supports hooks (beforeRequest, requestError) to alter requests, add headers (e.g., for custom HTTP client handlers) and manage errors.
– Handles retry logic configurable per-operation or globally (as described in the README).
c. MCP Server (Model Context Protocol Server):
– Implemented in its own module (src/mcp-server) with separate CLI commands (cli/start, cli/command.ts) that expose the SDK methods as tools for AI applications.
– Provides an alternative to using the SDK directly in client code by allowing the same operations to be executed via command line.
d. Operation Handlers and Standalone Functions:
– Within src/funcs and src/mcp-server/tools, you have discrete function modules that handle each API operation, such as creating events, retrieving datapoints, managing projects, etc.
– These modules use consistent validations, error handling (with SDKError and HTTP client errors) and follow the generated patterns.
e. Data Models and Schemas:
f. Utility Libraries and Hooks:
– The src/lib folder includes helper modules for encoding, security, retries, and logging.
– Hooks (in src/hooks) allow extra customization over request lifecycles.
g. Documentation and Tests:
– The docs directory holds markdown documentation (e.g., md files for each resource and operations overview).
– The tests directory (with integration tests, environment setups, and Docker/Makefile) validates the functionality of both the SDK and MCP server aspects.
Relationships and Interactions
– The SDK Client uses the HTTP Client to make network requests to the API backend. Its customizable hooks and retry strategies determine how each request is processed.
– Each functional module (for configurations, events, etc.) calls upon the shared libraries (models and lib functions) to validate inputs and interpret responses.
– For those running HoneyHive as an MCP server, the CLI module relays requests to the same underlying function modules that the SDK uses.
– Standalone functions allow for tree-shaken deployments by importing only what is needed.
Architectural Patterns and Design Principles
• Modularity: Each API resource is implemented as a separate module. This simplifies dependency management and testing.
• Separation of Concerns: Distinct layers for HTTP communications, business logic (operation handlers), data validation (models/schemas), and command-line interface (MCP server).
• Extensibility: Hooks (in the HTTP client and the registration under src/hooks) allow flexible customization of request/response handling.
• Error Handling Strategy: Centralized error types (SDKError, HTTP client errors) and detailed logging/debugging options to aid troubleshooting.
Relevant Technologies/Frameworks
– TypeScript as the main language.
– Node.js (v20+ for MCP server).
– Speakeasy for generating SDK components.
– Fetch API wrapped inside the HTTP client.
– Standard testing tools (Jest, integration tests scripts) and Docker/Makefile for test automation.