TypeScript Configuration

This document explains the TypeScript compiler configuration for the @perplexity-ai/mcp-server. It covers the tsconfig.json settings, module system configuration, type safety features, and how TypeScript compilation integrates with the build process. For project structure and directory organization, see page 8.1. For building and testing procedures, see page 8.2.

Compiler Configuration Overview

The TypeScript configuration is defined in tsconfig.json at the repository root (tsconfig.json1-16) and controls how source files in src/ are compiled to JavaScript in dist/.

Core Compiler Options

The following table summarizes the key compiler options (tsconfig.json2-11):

Option	Value	Purpose
target	ES2020	Emit JavaScript compatible with ES2020 runtime
module	ESNext	Use latest ECMAScript module syntax
outDir	./dist	Output compiled JavaScript to dist/ directory
rootDir	./src	Treat src/ as the root input directory
moduleResolution	node	Resolve modules using Node.js algorithm
strict	true	Enable all strict type-checking options
esModuleInterop	true	Enable CommonJS/ESM interoperability helpers
forceConsistentCasingInFileNames	true	Enforce consistent file name casing
skipLibCheck	true	Skip type checking of declaration files

Sources: tsconfig.json1-16

Module System Configuration

The project uses ECMAScript Modules (ESM) as its module system, configured through both TypeScript and package.json settings.

TypeScript Module Settings

ESM Module System: Configuration and Compilation Flow

The configuration establishes a pure ESM environment:

1. TypeScript Module Generation: module: "ESNext" (tsconfig.json4) instructs tsc to emit modern ECMAScript module syntax (import/export statements).
2. Package Type Declaration: "type": "module" (package.json25) tells Node.js to treat all .js files as ESM modules.
3. Module Resolution: moduleResolution: "node" (tsconfig.json11) uses the Node.js resolution algorithm to locate imported packages.
4. Runtime Requirements: "engines": {"node": ">=18"} (package.json68-70) ensures the runtime supports native ESM.

This configuration eliminates the need for .mjs extensions or CommonJS translation layers.

Sources: tsconfig.json4-11 package.json25-70

Import Resolution Strategy

Import Resolution and Type Checking for External Packages

The moduleResolution: "node" setting enables standard Node.js package resolution:

• Looks for packages in node_modules/
• Resolves based on package.json main or exports fields
• Automatically locates TypeScript declaration files

The esModuleInterop: true setting (tsconfig.json8) provides compatibility shims when importing CommonJS modules into ESM code, which is necessary for dependencies like express and cors that may use CommonJS internally.

The skipLibCheck: true setting (tsconfig.json10) skips type checking of external .d.ts declaration files to improve compilation performance.

Sources: tsconfig.json8-11

Type Safety and Strictness

The project enables TypeScript's strict mode and enforces type safety throughout the codebase.

Strict Mode Configuration

Strict Mode Flags Enabled by strict: true

The strict: true setting (tsconfig.json7) is an umbrella flag enabling all strict type-checking options:

Flag	Effect
noImplicitAny	Prevents implicit any types; requires explicit annotations
strictNullChecks	Distinguishes null/undefined from other types
strictFunctionTypes	Enforces contravariance for function parameters
strictBindCallApply	Type-checks .bind(), .call(), .apply() usage
strictPropertyInitialization	Ensures class properties are initialized in constructors
noImplicitThis	Requires explicit typing for this in functions
alwaysStrict	Emits "use strict" in output; parses in strict mode

The forceConsistentCasingInFileNames: true setting (tsconfig.json9) prevents cross-platform issues from inconsistent import casing (e.g., import './Server' vs import './server').

Sources: tsconfig.json7-9

Type System Integration

Type System: Internal Definitions and External @types Packages

The project combines internal type definitions with external type packages:

Source	Contents
src/types.ts	Message, ChatCompletionOptions, SearchResponse, model type maps
@modelcontextprotocol/sdk	McpServer, StdioServerTransport, MCP protocol types
@types/express (package.json59)	Request, Response for HTTP server
@types/cors (package.json58)	Types for cors middleware
@types/node (package.json60)	Node.js built-in types
zod	Runtime schema validation with static type inference

strict: true ensures all of src/server.ts, src/index.ts, and src/http.ts are fully annotated with no implicit any escapes.

Sources: tsconfig.json7 package.json58-61

Build Integration

The TypeScript compiler integrates with the npm build system through package.json scripts.

Compilation Pipeline

TypeScript Build Pipeline: tsc → dist/

The build process (package.json38) executes two steps:

1. TypeScript Compilation: tsc compiles all .ts files from src/ to .js files in dist/ per tsconfig.json5-6
2. Executable Permissions: shx chmod +x dist/*.js makes compiled files executable on Unix-like systems.

The outDir: "./dist" setting (tsconfig.json5) preserves directory structure: src/server.ts → dist/server.js, src/index.ts → dist/index.js, etc.

Sources: package.json38 tsconfig.json5-6

Build Script Configuration

The following build-related scripts are defined in package.json37-49:

Script	Command	Purpose
build	tsc && shx chmod +x dist/*.js	Full production build
prepare	npm run build	Automatic pre-publish build
watch	tsc --watch	Continuous compilation during development
start	node dist/index.js	Run compiled STDIO server
start:http	node dist/http.js	Run compiled HTTP server
dev	tsx src/index.ts	Run TypeScript directly in STDIO mode
dev:http	tsx src/http.ts	Run TypeScript directly in HTTP mode

The prepare script runs build automatically before npm publish. The watch script uses tsc --watch for incremental compilation, recompiling only files that have changed.

Sources: package.json37-46

Development Workflow

The project supports both production compilation and rapid development iteration.

Development vs Production Modes

Development vs. Production Compilation Workflows

Development Execution with tsx

The project uses tsx (package.json63) for development, which executes TypeScript files directly without a separate compilation step:

• npm run dev executes src/index.ts directly via tsx (STDIO mode)
• npm run dev:http executes src/http.ts directly via tsx (HTTP mode)

tsx handles TypeScript compilation in-memory using esbuild, providing fast iteration without touching dist/.

Watch Mode Compilation

The npm run watch command (package.json40) runs tsc --watch, which:

• Compiles TypeScript on initial invocation
• Monitors src/**/*.ts for changes
• Incrementally recompiles only modified files and their dependents
• Maintains compilation state for faster subsequent builds

This mode is useful when verifying the compiled output or debugging issues specific to the production build rather than the tsx development path.

Sources: package.json40-63

Target Environment

The TypeScript configuration targets modern JavaScript runtimes with specific feature requirements.

Target and Runtime Compatibility

ES2020 Target: Features Used and Runtime Compatibility

The target: "ES2020" setting (tsconfig.json3) means:

1. Feature Set: The compiler assumes the runtime supports all ES2020 features including optional chaining (?.), nullish coalescing (??), Promise.allSettled, BigInt, and dynamic import().
2. No Transpilation: Modern syntax is preserved as-is in the output rather than being downleveled.
3. Runtime Match: The "engines": {"node": ">=18"} constraint (package.json68-70) ensures the runtime natively supports all emitted ES2020 constructs.

This produces clean JavaScript without legacy polyfills or compatibility shims.

Sources: tsconfig.json3 package.json68-70

Type Checking Scope

The TypeScript compiler processes a specific set of source files based on the include configuration.

Compilation Scope

The include array (tsconfig.json13-15) is set to src/**/*.ts. This means:

• All .ts files under src/ are included in the build.
• node_modules/ is excluded by TypeScript's default behavior.
• The dist/ output directory is not re-processed.
• Test files such as src/server.test.ts are included in the TypeScript project graph but not emitted as distribution artifacts (they are excluded from the published files array in package.json).

The five source files compiled by tsc:

File	Role
src/server.ts	Core createPerplexityServer() implementation
src/index.ts	STDIO (StdioServerTransport) entry point
src/http.ts	HTTP (StreamableHTTPServerTransport) + Express entry point
src/types.ts	Shared TypeScript interfaces
src/logger.ts	Logger, stripThinkingTokens, proxy utilities

Sources: tsconfig.json13-15 package.json30-36

Configuration Best Practices

The TypeScript configuration follows several best practices for MCP server development:

Design Decisions

Setting	Choice	Rationale
strict: true	Enable all strict checks	Prevents common errors and improves code reliability in server environment
target: ES2020	Modern JavaScript target	Matches Node.js 18+ capabilities, no unnecessary transpilation
module: ESNext	Latest module syntax	Aligns with package.json type:module and modern Node.js ESM support
skipLibCheck: true	Skip .d.ts validation	Improves build performance, trusts external type definitions
esModuleInterop: true	CJS/ESM compatibility	Required for importing CommonJS dependencies like express
rootDir/outDir	src/ → dist/	Clear separation between source and compiled artifacts

These settings create a type-safe, modern JavaScript codebase optimized for Node.js server environments while maintaining compatibility with the MCP ecosystem.

Sources: tsconfig.json1-16 package.json25-70