Development Tooling

This page explains the development tooling used for building, testing, and developing the Perplexity MCP Server. The development toolchain consists of TypeScript compilation tools, test frameworks, and build utilities. For information about runtime dependencies required by the application, see page 10.2. For overall package configuration, see page 10.1.

Overview

The development tooling provides the complete development environment for TypeScript compilation, testing, and local development workflows. These tools are declared in the devDependencies field of package.json58-67 and are not included in the production bundle.

Sources: package.json58-67

TypeScript Compilation Toolchain

Core Compiler

The project uses TypeScript 5.9.3 (typescript@^5.9.3) as its primary compilation tool. The TypeScript compiler (tsc) transforms TypeScript source files in src/ to JavaScript output in dist/.

Tool	Version	Command	Purpose
typescript	^5.9.3	tsc	TypeScript-to-JavaScript compiler

The compiler is invoked through npm scripts defined in package.json37-40:

Script	Command	Purpose
build	tsc && shx chmod +x dist/*.js	Production compilation with executable permissions
prepare	npm run build	Automatic build on npm install
watch	tsc --watch	Watch mode for incremental compilation

Sources: package.json37-40 package.json65

TypeScript Type Definitions

Type definition packages (@types/*) provide TypeScript type information for JavaScript libraries that lack native TypeScript support. These enable full type checking and IDE autocomplete for third-party dependencies.

Type Definition Packages to Source File Mapping

Type Package	Version	Provides Types For	Used In
@types/node	^20	Node.js runtime APIs	All source files
@types/express	^5.0.0	Express framework	src/http.ts
@types/cors	^2.8.17	CORS middleware	src/http.ts

The @types/node version constraint ^20 aligns with the minimum Node.js version requirement specified in package.json68-70

Sources: package.json59-61 package.json68-70 src/http.ts src/server.ts src/index.ts

Development Execution with tsx

The tsx package (tsx@^4.19.4) enables direct execution of TypeScript files without pre-compilation. This tool is used exclusively in development mode for rapid iteration.

Development Scripts Using tsx

Script	Command	Entry Point	Purpose
dev	tsx src/index.ts	src/index.ts	Run STDIO server in dev mode
dev:http	tsx src/http.ts	src/http.ts	Run HTTP server in dev mode
dev:http:public	BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* tsx src/http.ts	src/http.ts	Run HTTP server with public access

The tsx execution flow bypasses the TypeScript compilation step, directly interpreting TypeScript source files. This eliminates the build step required for production execution (which uses node dist/index.js), significantly improving development iteration speed.

Sources: package.json44-46 package.json64

Testing Infrastructure

Vitest Test Framework

The project uses Vitest 4.0.5 (vitest@^4.0.5) as its testing framework. Vitest provides fast unit test execution with native TypeScript support and integrated coverage reporting.

Test Execution Flow

Test Commands

Script	Command	Behavior	Output
test	vitest run	Single test run, exit on completion	Test results to console
test:watch	vitest	Watch mode, re-run on file changes	Continuous test feedback
test:coverage	vitest run --coverage	Single run with coverage analysis	Test results + coverage report

The test configuration is defined in vitest.config.ts1-21 which specifies:

• Test file exclusions (node_modules, dist)
• Environment variables (sets PERPLEXITY_API_KEY for tests)
• Coverage provider (V8) and reporters (text, HTML, LCOV)

The coverage plugin (@vitest/coverage-v8@^4.0.5) uses the V8 JavaScript engine's built-in coverage instrumentation, providing accurate code coverage metrics without requiring code transformation.

Sources: package.json47-49 package.json62 package.json66 vitest.config.ts1-21

Build Utilities

Cross-Platform Shell Commands (shx)

The shx package (shx@^0.4.0) provides cross-platform shell commands that work consistently across Windows, Linux, and macOS. This ensures the build process produces identical results regardless of the development environment.

Usage in Build Script

The build script in package.json38 uses shx for setting file permissions:

This two-step build process:

1. tsc - Compiles TypeScript to JavaScript in dist/
2. shx chmod +x dist/*.js - Makes all compiled .js files executable

The executable permission is required for the binary entry point defined in package.json27-29:

This binary configuration enables the npx @perplexity-ai/mcp-server invocation pattern used by MCP clients like Claude Desktop, Cursor, and VS Code. Without the executable permission, the binary would fail to launch on Unix-like systems.

Sources: package.json27-29 package.json38 package.json63

Complete Development Workflow

Development Tooling Execution Flow

This diagram shows the complete development workflow from source code to execution:

1. Development Mode - Direct TypeScript execution via tsx for rapid iteration
2. Build Process - TypeScript compilation and permission setting via tsc and shx
3. Testing - Unit testing and coverage via Vitest
4. Production Execution - Running compiled JavaScript via Node.js

Sources: package.json37-49 vitest.config.ts1-21

Version Management

All development dependencies use caret (^) version constraints, which allow automatic minor and patch version updates while locking the major version.

Development Dependency Versions

Package	Constraint	Resolved	Version Strategy
typescript	^5.9.3	5.9.3	Major version 5 lock
vitest	^4.0.5	4.0.5	Major version 4 lock
@vitest/coverage-v8	^4.0.5	4.0.5	Matches vitest version
tsx	^4.19.4	4.19.4	Major version 4 lock
@types/node	^20	20.x	Aligns with Node.js 20 LTS
@types/express	^5.0.0	5.x	Matches express@^4 (v5 types)
@types/cors	^2.8.17	2.x	Matches cors@^2.8.5
shx	^0.4.0	0.4.0	Stable shell utility

Version Constraint Strategy:

1. Type Safety - Type definition versions (@types/*) match their corresponding runtime library major versions
2. Stability - Major version locks prevent breaking changes from entering the project
3. Security - Caret ranges allow automatic security patches via npm update
4. Test Consistency - @vitest/coverage-v8 version matches vitest to ensure plugin compatibility

Sources: package.json58-67

Node.js Engine Requirements

The project specifies Node.js >=18 as the minimum runtime version in package.json68-70:

Development Tool Node.js Requirements

Tool	Node.js Requirement	Effective Constraint
typescript	>=14.17	✓ Compatible with Node 18+
vitest	^18.0.0 || ^20.0.0 || ^22.0.0	✓ Compatible with Node 18+
tsx	>=18.0.0	✓ Matches project minimum
@vitest/coverage-v8	>=18	✓ Matches project minimum
Project Standard	>=18	Effective minimum

All development tools support Node.js 18+, which is the current Long-Term Support (LTS) release. This ensures:

• Consistency - Same Node.js version for development and production
• Modern Features - Access to Node.js 18+ features (native fetch, test runner, etc.)
• Long-term Support - LTS version receives security updates until April 2025

Sources: package.json68-70

Build Preparation Hook

The prepare script in package.json39 automatically runs the build during npm install:

This ensures that:

1. TypeScript compilation occurs before publishing to npm
2. Executable permissions are set on the binary entry point
3. The dist/ directory is populated before package distribution

This lifecycle hook is critical for the package's distribution via npm, as the files field in package.json30-36 includes dist/*.js but excludes source files.

Sources: package.json39 package.json30-36