Building and Testing

This page documents the build system, test suite organization, and development workflows for the Perplexity MCP Server. For information about TypeScript configuration and compiler options, see TypeScript Configuration. For CI/CD automation and publishing workflows, see CI/CD and Publishing.

Overview

The project uses a TypeScript-based build system with the following components:

• Build Tool: TypeScript compiler (tsc) for production builds
• Dev Tool: tsx for rapid development without compilation
• Test Framework: Vitest for unit and integration testing
• Coverage Tool: Vitest with V8 provider for code coverage analysis

The build process produces ES modules in the dist/ directory, with executable permissions set on entry point files.

Sources: package.json1-71 vitest.config.ts1-21

---

Build System Architecture

The following diagram illustrates the build pipeline and artifact generation:

Build Pipeline Flow:

1. TypeScript compiler reads source files from src/
2. Compilation produces JavaScript modules in dist/ following ES module format
3. shx chmod +x sets executable permissions on entry points
4. Test files and config are excluded from npm package distribution

Sources: package.json38-39 package.json30-36

---

Build Scripts Reference

The following table documents all build-related npm scripts:

Script	Command	Purpose
build	tsc && shx chmod +x dist/*.js	Full production build with executable permissions
prepare	npm run build	Automatic build hook triggered before npm publish
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
start:http:public	BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* node dist/http.js	Run HTTP server with public access

Sources: package.json37-43

TypeScript Compilation

The build process uses the TypeScript compiler (tsc) with configuration from tsconfig.json. Key compilation characteristics:

• Target: ES2020 for modern JavaScript features
• Module System: ESNext with Node16 resolution
• Output: Preserves directory structure in dist/
• Declaration Files: Not generated (not a library package)

To perform a production build:

This executes:

1. tsc - Compiles all .ts files (excluding .test.ts via tsconfig)
2. shx chmod +x dist/*.js - Makes entry points executable for CLI usage

Sources: package.json38

Executable Entry Points

The build system produces two executable entry points:

1. dist/index.js - STDIO mode server, registered as perplexity-mcp binary
2. dist/http.js - HTTP mode server, not registered as binary

The chmod +x operation enables direct execution:

The package.json bin field registers the STDIO entry point:

Sources: package.json27-29 package.json38

---

Development Mode

Development mode uses tsx to execute TypeScript directly without compilation, enabling rapid iteration.

Development Scripts:

Script	Command	Use Case
dev	tsx src/index.ts	Local STDIO server development
dev:http	tsx src/http.ts	HTTP server development (localhost only)
dev:http:public	BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* tsx src/http.ts	HTTP server with public access for testing

Advantages of tsx in Development:

• No compilation step required
• Faster iteration cycle
• Automatic TypeScript type checking
• Direct source map support for debugging

Sources: package.json44-46 package.json64

---

Test Suite Organization

The test suite uses Vitest with three primary test files covering different system layers:

Test File Responsibilities:

src/index.test.ts

Primary integration tests for core API functionality:

• formatSearchResults: Search result formatting with various data structures
• performChatCompletion: Chat API calls, citation handling, error scenarios
• performSearch: Search API calls, parameter handling
• API Response Validation: Malformed response handling
• Edge Cases: JSON parsing, timeouts, concurrent requests, unicode handling
• strip_thinking: Thinking token removal behavior
• Proxy Support: Proxy configuration and fallback chain

Coverage: 287 lines, 11 test suites, 43 test cases

Sources: src/index.test.ts1-765

src/server.test.ts

Unit tests for utility and helper functions:

• stripThinkingTokens: Regex-based token removal logic
• getProxyUrl: Proxy resolution chain (PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY)
• proxyAwareFetch: Conditional undici vs native fetch
• validateMessages: Message array validation with detailed error reporting

Coverage: 257 lines, 4 test suites, 23 test cases

Sources: src/server.test.ts1-257

src/transport.test.ts

Integration tests for MCP protocol transport layers:

• Server Factory: createPerplexityServer() initialization
• STDIO Transport: StdioServerTransport connection and error handling
• HTTP Transport: StreamableHTTPServerTransport with Express integration
• Protocol Methods: tools/list and tools/call MCP protocol verification
• Health Check: HTTP /health endpoint functionality

Coverage: 367 lines, 5 test suites, 11 test cases

Sources: src/transport.test.ts1-367

---

Running Tests

Basic Test Execution

Sources: package.json47-49

Test Execution Flow

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

Test Environment Setup

Vitest is configured with a dedicated test environment that provides:

1. Environment Variables: Automatically set PERPLEXITY_API_KEY=test-api-key
2. Exclusions: Skip node_modules/ and dist/ directories
3. Coverage Exclusions: Skip test files, config files, and compiled output

Configuration details from vitest.config.ts:

Sources: vitest.config.ts3-20

---

Test Patterns and Mocking

API Mocking Pattern

All tests mock the fetch API to avoid real network calls:

Sources: src/index.test.ts69-72

Environment Variable Testing

Tests manipulate process.env to verify configuration handling:

Cleanup Pattern: All tests restore original environment:

Sources: src/server.test.ts61-69 src/index.test.ts139

Error Testing Strategy

Tests verify error handling for multiple failure scenarios:

Error Type	Test Pattern	Example
API Errors	Mock ok: false response	src/index.test.ts123-136
Timeout Errors	Mock slow response with AbortSignal	src/index.test.ts138-165
Network Errors	Mock rejected Promise	src/index.test.ts167-175
Validation Errors	Call with invalid inputs	src/server.test.ts196-254
Malformed JSON	Mock throw on .json()	src/index.test.ts405-418

Sources: src/index.test.ts123-435

---

Coverage Reporting

Coverage Configuration

The project uses Vitest with V8 coverage provider for code coverage analysis:

Sources: vitest.config.ts9-18

Coverage Outputs

Running npm run test:coverage generates:

1. Text Report: Inline console output with line/branch/function coverage percentages
2. HTML Report: Interactive browser-based report at coverage/index.html
3. LCOV Report: Machine-readable format at coverage/lcov.info (for CI integration)

Coverage Artifact Structure:

coverage/
├── index.html # HTML entry point
├── lcov.info # LCOV format data
├── coverage-final.json # Raw V8 coverage data
└── [source files].html # Per-file HTML reports

Sources: vitest.config.ts10-11

Excluded from Coverage

The following files are intentionally excluded from coverage metrics:

• node_modules/ - Third-party dependencies
• dist/ - Compiled JavaScript (coverage tracks TypeScript source)
• *.test.ts - Test files (should not be counted)
• *.config.ts - Configuration files (minimal logic)

Sources: vitest.config.ts12-17

---

Test-Driven Scenarios

The test suite validates key functional scenarios:

Scenario: Chat Completion with Citations

Test Location: src/index.test.ts94-121

Sources: src/index.test.ts94-121

Scenario: Thinking Token Stripping

Test Location: src/index.test.ts665-702

Sources: src/index.test.ts665-702 src/server.test.ts5-58

Scenario: Proxy Resolution Chain

Test Location: src/server.test.ts60-114

Sources: src/server.test.ts60-114 src/index.test.ts704-763

---

Test Execution in CI

The test suite is automatically executed in GitHub Actions on every pull request and push. See Automated Testing Workflow for CI/CD integration details.

CI Environment Characteristics:

• Node.js 20.x runtime
• Clean npm ci install
• Single test run (no watch mode)
• Coverage not collected in CI (optional enhancement)

Sources: package.json47