Development Guide

This section covers everything needed to work on the @perplexity-ai/mcp-server codebase itself: the repository layout, how to run the server without a build step during development, how to build and test, and the TypeScript compiler configuration. It is intended for contributors and anyone modifying or extending the server.

For deployment of the built server, see Deployment. For configuration of the running server (environment variables, proxy, etc.), see Configuration.

---

Quick Start for Contributors

The minimum requirements to start developing are:

Requirement	Minimum Version
Node.js	18
npm	bundled with Node 18+

Set PERPLEXITY_API_KEY in your environment, then:

npm ci
npm run dev # stdio mode, no build needed
npm run dev:http # HTTP mode, no build needed
npm test # run the test suite

Sources: package.json68-70 package.json44-46

---

Repository Layout

Development workflow diagram: source to output

Sources: package.json26-36 package.json37-49

---

npm Scripts Reference

All developer-facing tasks are exposed as npm scripts in package.json37-49

Script	Command	Purpose
build	tsc && shx chmod +x dist/*.js	Compile TypeScript and mark output files executable
prepare	npm run build	Auto-runs build on npm install
watch	tsc --watch	Incremental compile on file change
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	HTTP server open to all origins
dev	tsx src/index.ts	Run stdio server directly from TypeScript (no build)
dev:http	tsx src/http.ts	Run HTTP server directly from TypeScript (no build)
dev:http:public	BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* tsx src/http.ts	HTTP server, open to all origins, no build
test	vitest run	Single-pass test run
test:watch	vitest	Continuous test watch mode
test:coverage	vitest run --coverage	Test run with v8 coverage report

Sources: package.json37-49

---

Development vs Production Mode

Mode selection diagram

tsx executes TypeScript source files directly using an ESBuild-based transformer, enabling fast iteration without a compile step. The build script uses tsc for full type checking and produces the dist/ artifacts that are shipped in the npm package.

Sources: package.json37-49

---

Child Pages

The remaining sections in this Development Guide cover each topic in detail:

• Project Structure and Architecture — Source file layout, dist/ output, config files, and how src/index.ts and src/http.ts relate to the shared src/server.ts core.
• Building and Testing — Full details on the tsc build pipeline, shx cross-platform chmod, tsx dev mode, vitest configuration, the PERPLEXITY_API_KEY test stub, and coverage exclusions.
• TypeScript Configuration — tsconfig.json settings: ES2020 target, ESNext module system, strict mode, esModuleInterop, node module resolution, src/ as rootDir, and dist/ as outDir.

---

Key Dependencies at a Glance

Development toolchain dependency diagram

Sources: package.json58-67 package.json37-49