Data Types and Validation

This page documents the static TypeScript type system (src/types.ts) and the runtime Zod validation schemas (src/validation.ts). Together these two modules define the shape of every data structure that flows between the MCP tool handlers and the Perplexity API.

• For how these types are used during request construction and response parsing, see Request Processing Pipeline.
• For the tool input schemas (Zod schemas defined inline as part of tool registration), see Server Implementation.
• For logging and utility functions that operate on these types, see Logging and Utilities.

---

Module Overview

src/types.ts — TypeScript interface declarations. Provide compile-time type safety across the entire codebase. All interfaces are exported and imported wherever API requests or responses are constructed or consumed.

src/validation.ts — Zod schema objects mirroring the same structures. Provide runtime validation of API responses that cannot be verified at compile time. The schemas are parsed after each API call to catch malformed or unexpected payloads before they reach tool output formatting.

Both modules are consumed by src/server.ts (src/server.ts). src/validation.ts additionally pulls in the zod library as its sole external dependency.

Sources: src/types.ts1-70 src/validation.ts1-46

---

Type and Schema Correspondence

Every interface in src/types.ts has a corresponding Zod schema in src/validation.ts. The diagram below shows the parallel structure.

Diagram: TypeScript interfaces and their Zod schema counterparts

Sources: src/types.ts1-70 src/validation.ts1-46

---

TypeScript Interfaces (src/types.ts)

Conversation and Message Types

Interface	Fields	Purpose
Message	role: string, content: string	Represents a single message in a conversation thread as passed in by MCP tool callers
ChatMessage	content: string, role?: string	Represents a message object returned from the Perplexity API inside a choice

Message is the input-side type used in tool handler arguments. ChatMessage is the output-side type nested inside ChatChoice from an API response. The role field is required on input but optional on output.

Sources: src/types.ts3-11

Chat Completion Response Types

These interfaces model the JSON body returned by the /chat/completions endpoint.

Interface	Fields	Notes
ChatChoice	message: ChatMessage, finish_reason?: string, index?: number	One completion candidate from the response
TokenUsage	prompt_tokens?: number, completion_tokens?: number, total_tokens?: number	Token accounting from the API
ChatCompletionResponse	choices: ChatChoice[], citations?: string[], usage?: TokenUsage, id?: string, model?: string, created?: number	Top-level response envelope

The citations field on ChatCompletionResponse is the array of source URLs that performChatCompletion appends to the response text as a numbered list. All fields other than choices are optional, reflecting that different Perplexity models may omit them.

Sources: src/types.ts8-32

Search Types

These interfaces model the /search endpoint used by perplexity_search.

Interface	Fields	Notes
SearchResult	title: string, url: string, snippet?: string, date?: string, score?: number	A single search result item
SearchUsage	tokens?: number	Token count for a search call
SearchResponse	results: SearchResult[], query?: string, usage?: SearchUsage	Top-level search response envelope
SearchRequestBody	query: string, max_results: number, max_tokens_per_page: number, country?: string	Body sent to /search

SearchRequestBody is a pure outbound type — it is constructed in performSearch and never validated at runtime because the server controls its construction.

Sources: src/types.ts34-57

Option and Internal Types

Interface	Fields	Purpose
ChatCompletionOptions	search_recency_filter?, search_domain_filter?, search_context_size?, reasoning_effort?	Typed union of optional API parameters forwarded to /chat/completions
UndiciRequestOptions	dispatcher?: ProxyAgent, index signature [key: string]: unknown	Wraps undici fetch options; carries the optional ProxyAgent for proxy-aware requests

ChatCompletionOptions.search_recency_filter is constrained to "hour" | "day" | "week" | "month" | "year". search_context_size is constrained to "low" | "medium" | "high". reasoning_effort is constrained to "minimal" | "low" | "medium" | "high". These literal union types enforce that only valid API values can be passed.

UndiciRequestOptions uses an index signature ([key: string]: unknown) alongside the typed dispatcher field, allowing undici-specific options to be forwarded without enumerating every possible key.

Sources: src/types.ts59-69

---

Zod Schemas (src/validation.ts)

Zod schemas are used to parse API responses at runtime. A failed parse means the API returned something unexpected — this produces a descriptive Zod error rather than a silent type cast gone wrong.

Schema Composition

Diagram: Zod schema composition tree

Sources: src/validation.ts1-46

Schema Definitions

ChatMessageSchema

src/validation.ts3-6

Validates content as a required string and role as an optional string. Matches ChatMessage in src/types.ts.

ChatChoiceSchema

src/validation.ts8-12

Validates a single choice object. Nests ChatMessageSchema for the message field. finish_reason and index are optional.

TokenUsageSchema

src/validation.ts14-18

All three token count fields are optional numbers, because the API does not guarantee their presence on every response.

ChatCompletionResponseSchema

src/validation.ts20-27

The critical constraint here is .min(1) on the choices array — an empty choices array would cause downstream code to fail when accessing choices[0].message.content, so Zod rejects it before it reaches that path. All other top-level fields beyond choices are optional.

SearchResultSchema

src/validation.ts29-35

title and url are required strings. snippet, date, and score are optional. This matches the SearchResult interface exactly.

SearchUsageSchema

src/validation.ts37-39

A single optional tokens field.

SearchResponseSchema

src/validation.ts41-45

results is a required array (may be empty). query and usage are optional.

---

Validation Flow in Context

Diagram: Where validation sits in the request/response lifecycle

Sources: src/validation.ts20-27 src/types.ts25-32

The same pattern applies to performSearch, which uses SearchResponseSchema.parse() on the raw JSON from /search.

---

Summary Table

Symbol	File	Kind	Runtime validation?	Used by
Message	src/types.ts	TS interface	No	Tool handlers in server.ts
ChatMessage	src/types.ts	TS interface	Via ChatMessageSchema	ChatChoice, response parsing
ChatChoice	src/types.ts	TS interface	Via ChatChoiceSchema	ChatCompletionResponse
TokenUsage	src/types.ts	TS interface	Via TokenUsageSchema	ChatCompletionResponse
ChatCompletionResponse	src/types.ts	TS interface	Via ChatCompletionResponseSchema	performChatCompletion
SearchResult	src/types.ts	TS interface	Via SearchResultSchema	SearchResponse, result formatting
SearchUsage	src/types.ts	TS interface	Via SearchUsageSchema	SearchResponse
SearchResponse	src/types.ts	TS interface	Via SearchResponseSchema	performSearch
SearchRequestBody	src/types.ts	TS interface	No (outbound only)	performSearch
ChatCompletionOptions	src/types.ts	TS interface	No (internal)	performChatCompletion
UndiciRequestOptions	src/types.ts	TS interface	No (fetch layer)	proxyAwareFetch
ChatMessageSchema	src/validation.ts	Zod schema	Yes	ChatChoiceSchema
ChatChoiceSchema	src/validation.ts	Zod schema	Yes	ChatCompletionResponseSchema
TokenUsageSchema	src/validation.ts	Zod schema	Yes	ChatCompletionResponseSchema
ChatCompletionResponseSchema	src/validation.ts	Zod schema	Yes	performChatCompletion
SearchResultSchema	src/validation.ts	Zod schema	Yes	SearchResponseSchema
SearchUsageSchema	src/validation.ts	Zod schema	Yes	SearchResponseSchema
SearchResponseSchema	src/validation.ts	Zod schema	Yes	performSearch

Sources: src/types.ts1-70 src/validation.ts1-46