Implementation:Helicone Helicone MCP Flatten Types

Knowledge Sources	Helicone
Domains	MCP, Code Generation, Type System
Last Updated	2026-02-14 06:32 GMT

Overview

A build-time TypeScript utility that flattens nested OpenAPI schema types into standalone type aliases for Zod schema generation in the Helicone MCP server.

Description

The flatten-types.ts script reads the auto-generated public.ts file (produced from Helicone's OpenAPI specification) and extracts root types such as RequestFilterNode, SessionFilterNode, and SortLeafRequest. It recursively resolves all components["schemas"]["X"] references into direct type references, tracks visited types to avoid infinite loops, performs a topological sort to ensure dependency ordering, and writes the resulting flat type definitions to flat.ts. This flat file is then consumed by ts-to-zod to generate runtime Zod validators.

The script uses a custom parser rather than a full TypeScript AST, scanning the source text character-by-character to handle nested braces, strings, and type boundaries. It supports a maximum recursion depth of 50 to guard against pathological circular references.

Usage

Use this script as part of the MCP server build pipeline when the OpenAPI types have changed and the Zod schemas need to be regenerated. It is invoked via npm run flatten-types or as part of the full npm run generate-zod pipeline.

Code Reference

Source Location

• Repository: Helicone
• File: helicone-mcp/flatten-types.ts

Signature

// Root types targeted for flattening
const ROOT_TYPES = [
  "RequestFilterNode",
  "SessionFilterNode",
  "SortLeafRequest",
];

const ADDITIONAL_TYPES_TO_FLATTEN = [
  "SortDirection",
  "RequestFilterBranch",
  "SessionFilterBranch",
];

// Key functions
function readPublicTs(): string
function extractTypeDefinition(content: string, typeName: string): string | null
function extractNestedTypeNames(definition: string): string[]
function flattenType(content: string, typeName: string, depth?: number): void
function generateOutput(): string
function topologicalSort(defs: Map<string, string>): string[]
function main(): void

Import

// This is a standalone script, not imported as a module.
// Run via: npm run flatten-types
// Or via: tsx flatten-types.ts

I/O Contract

Input	Type	Description
public.ts	File (TypeScript)	Auto-generated OpenAPI types at src/types/public.ts

Output	Type	Description
flat.ts	File (TypeScript)	Flattened type aliases at src/types/flat.ts with all components["schemas"]["X"] references resolved

Function	Parameters	Returns	Description
extractTypeDefinition	content: string, typeName: string	null	Extracts a single type definition from the schemas section of public.ts
extractNestedTypeNames	definition: string	string[]	Finds all referenced type names within a type definition
flattenType	content: string, typeName: string, depth?: number	void	Recursively resolves and stores a type and all its dependencies
topologicalSort	defs: Map<string, string>	string[]	Returns type names sorted in dependency order (leaves first)

Usage Examples

# Run the type flattening step alone
cd helicone-mcp
npm run flatten-types

# Run the full Zod generation pipeline (flatten + ts-to-zod + build)
npm run generate-zod

// Example of what the script transforms:
// Input (public.ts):
//   RequestFilterNode: components["schemas"]["RequestFilterBranch"] | components["schemas"]["RequestFilterLeaf"];
//
// Output (flat.ts):
//   type RequestFilterNode = RequestFilterBranch | RequestFilterLeaf;
//   type RequestFilterBranch = { ... };
//   type RequestFilterLeaf = { ... };

Related Pages

• Principle:Helicone_Helicone_MCP_Type_Generation