pplx-npx-search 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to pplx-cli will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-05-26
+
+### Added
+- **Perplexity Model Council handoff.** Added `pplx council` artifact workflows plus MCP tools for creating, reading, checking, and importing Model Council review runs.
+- **Competitive-analysis template.** Added a `competitive-analysis` Perplexity Computer template that produces evidence briefs with a Council review prompt.
+
+## [0.3.2] - 2026-05-26
+
+### Added
+- **MCP server.** Added `pplx-mcp`, a stdio MCP server for Claude Desktop, Claude Code, Codex, and other MCP clients.
+- **MCP tool surface.** Exposes search, labs, auth status, model listing, and Perplexity Computer artifact tools through MCP.
+
 ## [0.3.1] - 2026-05-22
 
 ### Changed
@@ -67,6 +79,8 @@ First public release worth telling people about. (v0.2.0 was unpublished before
 - SSE streaming for real-time answers
 - Optional Playwright and Chrome CDP transports
 
+[0.3.3]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.1...v0.2.2

package/README.md

@@ -102,6 +102,7 @@ pplx reason "explain the Riemann hypothesis"
 pplx research "compare React vs Vue in 2026"
 pplx labs "hello world"          # free, no auth needed
 pplx computer new "compare dinner options nearby"
+pplx council new "critique the competitive threat from Acme in enterprise search"
 pplx models                       # list available models
 ```
 
@@ -152,6 +153,43 @@ pplx search "research this topic" --json --raw --mode pro
 }
 ```
 
+### MCP Server
+
+`pplx-mcp` exposes the same Perplexity workflow through a local stdio MCP server for Claude Desktop, Claude Code, Codex, and other MCP clients.
+
+```bash
+pplx-mcp
+```
+
+Typical global client registrations:
+
+```bash
+claude mcp add --scope user pplx -- /path/to/node /path/to/pplx-mcp
+codex mcp add pplx -- /path/to/node /path/to/pplx-mcp
+```
+
+For Claude Desktop, add the server under `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pplx": {
+      "command": "/path/to/node",
+      "args": ["/path/to/pplx-mcp"]
+    }
+  }
+}
+```
+
+The MCP server exposes:
+
+- `pplx_search`: authenticated `search`, `reasoning`, and `deep-research` queries with sources and artifacts.
+- `pplx_labs`: Labs model queries that do not require cookie auth.
+- `pplx_auth_status`: validates the stored Perplexity browser cookies.
+- `pplx_models`: lists known model aliases.
+- `pplx_computer_create`, `pplx_computer_status`, `pplx_computer_read_task`, and `pplx_computer_import`: Perplexity Computer artifact handoff tools.
+- `pplx_council_create`, `pplx_council_status`, `pplx_council_read_task`, and `pplx_council_import`: Perplexity Model Council artifact handoff tools.
+
 ---
 
 ## Artifacts
@@ -164,6 +202,7 @@ Query-producing commands save artifacts by default:
 - `pplx labs`
 - bare `pplx "query"`
 - `pplx computer new`
+- `pplx council new`
 
 Each run gets a folder containing `meta.json`, `query.txt`, `answer.md`, `result.json`, and `sources.json`. Use `--out <dir>` to choose the destination for one run, or set `"artifactDir"` in `~/.config/pplx/config.json` to make it persistent. Use `--artifact-id <id>` when an agent needs a deterministic run folder, and `--no-artifact` to disable saving for one search-style run.
 
@@ -184,6 +223,18 @@ pplx computer import <run-id> --out ~/Dropbox/pplx-runs --json
 
 Computer runs include `task.md`, `result.schema.json`, and `computer-result.json`. Paste `task.md` into Perplexity Computer; when the task is done, place the structured result in `computer-result.json` so local agents can read it.
 
+`pplx council` is an artifact handoff for Perplexity Model Council. It requires Model Council access in the Perplexity web UI and creates a task prompt plus result contract without claiming a private Council API:
+
+```bash
+pplx council new "critique the competitive threat from Acme in enterprise search" --out ~/Dropbox/pplx-runs
+pplx council new "review this evidence" --evidence ~/Dropbox/pplx-runs/acme/computer-result.json
+pplx council open <run-id> --copy
+pplx council status <run-id> --out ~/Dropbox/pplx-runs
+pplx council import <run-id> --out ~/Dropbox/pplx-runs --json
+```
+
+Council runs include `task.md`, `result.schema.json`, and `council-result.json`. Paste `task.md` into Perplexity Model Council; when the review is done, place the structured result in `council-result.json` so local agents can read it.
+
 ---
 
 ## Options

package/bin/pplx-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runMcpServer } from '../src/mcp-server.js';
+
+runMcpServer().catch((error) => {
+  console.error('pplx MCP server error:', error?.message || error);
+  process.exit(1);
+});

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "pplx-npx-search",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "CLI for Perplexity AI with cookie-based auth. Headless, agent-friendly, no API key required.",
   "type": "module",
   "bin": {
-    "pplx": "bin/pplx.js"
+    "pplx": "bin/pplx.js",
+    "pplx-mcp": "bin/pplx-mcp.js"
   },
   "scripts": {
     "start": "node bin/pplx.js",
@@ -37,12 +38,14 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "eventsource-parser": "^3.0.0",
     "ora": "^8.0.0",
     "playwright": "^1.58.1",
-    "ws": "^8.16.0"
+    "ws": "^8.21.0",
+    "zod": "^4.4.3"
   }
 }

package/src/cli.js

@@ -15,6 +15,7 @@ import { loadConfig } from './config.js';
 import { resolveTimeoutMs } from './timeout.js';
 import { makeArtifactContext, resolveArtifactDir, writeStandardArtifact } from './artifacts.js';
 import {
+  COMPUTER_TEMPLATES,
   createComputerRun,
   copyTextToClipboard,
   importComputerResult,
@@ -22,6 +23,14 @@ import {
   openComputerUrl,
   readTaskFile,
 } from './computer.js';
+import {
+  COUNCIL_TEMPLATES,
+  copyCouncilTaskToClipboard,
+  createCouncilRun,
+  importCouncilResult,
+  inspectCouncilRun,
+  openCouncilUrl,
+} from './council.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -562,7 +571,7 @@ const computer = program
 addArtifactOptions(computer
   .command('new [task]')
   .description('Create a Perplexity Computer task artifact')
-  .option('--template <name>', 'Computer task template', 'compare')
+  .option('--template <name>', `Computer task template: ${COMPUTER_TEMPLATES.join(', ')}`, 'compare')
   .option('--json', 'Output run metadata as JSON'), { allowDisable: false })
   .action(async (taskArg, opts) => {
     opts = getOpts(opts);
@@ -649,6 +658,100 @@ addArtifactOptions(computer
     }
   });
 
+// Council artifact handoff workflow
+const council = program
+  .command('council')
+  .description('Create and manage Perplexity Model Council artifact handoffs');
+
+addArtifactOptions(council
+  .command('new [task]')
+  .description('Create a Perplexity Model Council task artifact')
+  .option('--template <name>', `Council task template: ${COUNCIL_TEMPLATES.join(', ')}`, 'competitive-analysis')
+  .option('--evidence <path>', 'Optional local evidence artifact path to reference in the Council task')
+  .option('--json', 'Output run metadata as JSON'), { allowDisable: false })
+  .action(async (taskArg, opts) => {
+    opts = getOpts(opts);
+    const task = await resolveQuery(taskArg);
+    try {
+      const run = createCouncilRun({
+        task,
+        template: opts.template,
+        evidencePath: opts.evidence,
+        opts,
+        config: loadConfig(),
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(run));
+        return;
+      }
+      console.log(chalk.green(`✓ Council task artifact created: ${run.artifactDir}`));
+      console.log(chalk.dim(`  Task: ${run.taskPath}`));
+      console.log(chalk.dim(`  Result: ${run.resultPath}`));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(council
+  .command('open <run>')
+  .description('Open Perplexity and optionally copy task.md for Model Council')
+  .option('--copy', 'Copy task.md to the clipboard'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const runDir = resolveRunDir(runId, opts);
+    try {
+      if (opts.copy && !copyCouncilTaskToClipboard(runDir)) {
+        console.log(chalk.yellow('Clipboard copy is only supported on macOS.'));
+      }
+      if (!openCouncilUrl()) {
+        console.log(chalk.yellow('Opening Perplexity is only supported on macOS.'));
+        console.log('https://www.perplexity.ai/');
+        return;
+      }
+      console.log(chalk.green(`✓ Opened Perplexity for ${runDir}`));
+      if (opts.copy) console.log(chalk.dim('  Copied task.md to clipboard.'));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(council
+  .command('status <run>')
+  .description('Inspect a Perplexity Model Council artifact run')
+  .option('--json', 'Output status as JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const status = inspectCouncilRun(resolveRunDir(runId, opts));
+    if (opts.json) {
+      console.log(JSON.stringify(status));
+      return;
+    }
+    const label = status.status === 'complete'
+      ? chalk.green('[✓] Complete')
+      : status.status === 'pending'
+        ? chalk.yellow('[○] Pending')
+        : chalk.red(status.status === 'invalid' ? '[!] Invalid' : '[✗] Missing');
+    console.log(`${label} ${status.artifactDir}`);
+    if (status.reason) console.log(chalk.dim(`  ${status.reason}`));
+  });
+
+addArtifactOptions(council
+  .command('import <run>')
+  .description('Print a completed Perplexity Model Council result')
+  .option('--json', 'Output compact JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    try {
+      const result = importCouncilResult(resolveRunDir(runId, opts));
+      console.log(opts.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
 // Models command
 program
   .command('models')

package/src/computer.js

@@ -10,6 +10,7 @@ import {
 
 export const COMPUTER_URL = 'https://www.perplexity.ai/computer';
 export const COMPUTER_RESULT_FILE = 'computer-result.json';
+export const COMPUTER_TEMPLATES = ['compare', 'competitive-analysis'];
 export const PENDING_COMPUTER_RESULT = {
   summary: '',
   winner: '',
@@ -18,6 +19,7 @@ export const PENDING_COMPUTER_RESULT = {
   sources: [],
   checked_at: '',
   notes: [],
+  council_review_prompt: '',
   _status: 'pending',
 };
 
@@ -34,14 +36,11 @@ const RESULT_SCHEMA = {
     sources: { type: 'array' },
     checked_at: { type: 'string' },
     notes: { type: 'array' },
+    council_review_prompt: { type: 'string' },
   },
 };
 
-export function buildComputerTask({ task, template = 'compare', resultPath }) {
-  if (template !== 'compare') {
-    throw new Error(`unsupported computer template: ${template}`);
-  }
-
+function buildCompareTask({ task, resultPath }) {
   return `# Perplexity Computer Task
 
 You are running a live comparison task for a local agent workflow.
@@ -72,6 +71,60 @@ If you cannot access the filesystem, return the JSON in the chat so the local ag
 `;
 }
 
+function buildCompetitiveAnalysisTask({ task, resultPath }) {
+  return `# Perplexity Computer Task
+
+You are running a live competitive-analysis task for a local agent workflow.
+
+## User request
+
+${task}
+
+## Instructions
+
+- Treat this as "one competitor or competitor set" plus "one topic, market, product surface, capability, pricing motion, GTM motion, or customer segment."
+- Use live web pages and direct source pages where possible, not only search snippets.
+- Check competitor-owned pages first: home page, product docs, pricing, changelog, blog, help center, release notes, status pages, public roadmaps, job postings, and app marketplace listings.
+- Add independent evidence where useful: customer reviews, forum threads, analyst commentary, news, benchmark posts, partner pages, search ads, and social posts.
+- Preserve source URLs for every material claim.
+- Separate facts from interpretation.
+- Identify:
+  - current positioning
+  - recent changes or launches
+  - pricing and packaging implications
+  - GTM and distribution signals
+  - customer pain or praise signals
+  - likely strategic intent
+  - threat level to the user request's context
+  - evidence gaps that need follow-up
+- Include the time the information was checked.
+- Mark uncertainty explicitly. Do not invent missing values.
+- Prefer structured evidence over prose.
+- Include \`council_review_prompt\`: a concise prompt that can be pasted into Perplexity Model Council to critique the evidence and strategy read.
+
+## Output target
+
+Write the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+export function buildComputerTask({ task, template = 'compare', resultPath }) {
+  if (!COMPUTER_TEMPLATES.includes(template)) {
+    throw new Error(`unsupported computer template: ${template}`);
+  }
+
+  if (template === 'competitive-analysis') {
+    return buildCompetitiveAnalysisTask({ task, resultPath });
+  }
+  return buildCompareTask({ task, resultPath });
+}
+
 export function createComputerRun({ task, template = 'compare', opts = {}, config = {} }) {
   const ctx = makeArtifactContext({ command: 'computer', query: task, opts, config });
   if (!ctx) {

package/src/council.js

@@ -0,0 +1,282 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  ARTIFACT_SCHEMA_VERSION,
+  makeArtifactContext,
+  readJsonFile,
+  writeJson,
+} from './artifacts.js';
+import { copyTextToClipboard } from './computer.js';
+
+export const COUNCIL_URL = 'https://www.perplexity.ai/';
+export const COUNCIL_RESULT_FILE = 'council-result.json';
+export const COUNCIL_TEMPLATES = ['competitive-analysis', 'strategy-review'];
+export const PENDING_COUNCIL_RESULT = {
+  summary: '',
+  consensus: [],
+  disagreements: [],
+  risks: [],
+  recommendations: [],
+  followups: [],
+  sources: [],
+  confidence: 'low',
+  checked_at: '',
+  notes: [],
+  _status: 'pending',
+};
+
+const RESULT_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'pplx council review result',
+  type: 'object',
+  required: [
+    'summary',
+    'consensus',
+    'disagreements',
+    'risks',
+    'recommendations',
+    'followups',
+    'sources',
+    'confidence',
+    'checked_at',
+    'notes',
+  ],
+  properties: {
+    summary: { type: 'string' },
+    consensus: { type: 'array' },
+    disagreements: { type: 'array' },
+    risks: { type: 'array' },
+    recommendations: { type: 'array' },
+    followups: { type: 'array' },
+    sources: { type: 'array' },
+    confidence: { enum: ['low', 'medium', 'high'] },
+    checked_at: { type: 'string' },
+    notes: { type: 'array' },
+  },
+};
+
+function buildCompetitiveAnalysisCouncilTask({ task, evidencePath, resultPath }) {
+  const evidenceBlock = evidencePath
+    ? `\n## Evidence brief\n\nUse this local evidence artifact if available:\n\n\`${evidencePath}\`\n`
+    : '';
+
+  return `# Perplexity Model Council Task
+
+Use Perplexity Model Council for a multi-model review. This is a judgment and synthesis pass, not the primary web-browsing pass.
+
+## User request
+
+${task}
+${evidenceBlock}
+## Instructions
+
+- Ask the Council to evaluate the same evidence from multiple model perspectives before synthesizing.
+- Focus on the competitor, topic, market, product capability, pricing motion, GTM motion, or customer segment named in the request.
+- Separate source-backed facts from strategic interpretation.
+- Identify where the models agree and where they disagree.
+- Challenge the strongest assumption in the analysis.
+- Surface missing evidence that would change the conclusion.
+- Produce concrete recommendations and monitoring follow-ups.
+- Preserve source URLs from the evidence brief and add any new source URLs used by Council.
+- Mark uncertainty explicitly. Do not invent missing values.
+
+## Output target
+
+Return the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+function buildStrategyReviewCouncilTask({ task, evidencePath, resultPath }) {
+  const evidenceBlock = evidencePath
+    ? `\n## Evidence brief\n\nUse this local evidence artifact if available:\n\n\`${evidencePath}\`\n`
+    : '';
+
+  return `# Perplexity Model Council Task
+
+Use Perplexity Model Council for a multi-model strategy review.
+
+## User request
+
+${task}
+${evidenceBlock}
+## Instructions
+
+- Ask the Council to evaluate the request from multiple reasoning perspectives before synthesizing.
+- Identify consensus, disagreements, risks, blind spots, and decision criteria.
+- Separate source-backed facts from interpretation.
+- Challenge the strongest assumption.
+- Surface missing evidence that would change the conclusion.
+- Produce concrete recommendations and follow-up questions.
+- Preserve source URLs from the evidence brief and add any new source URLs used by Council.
+- Mark uncertainty explicitly. Do not invent missing values.
+
+## Output target
+
+Return the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+export function buildCouncilTask({
+  task,
+  template = 'competitive-analysis',
+  evidencePath,
+  resultPath,
+}) {
+  if (!COUNCIL_TEMPLATES.includes(template)) {
+    throw new Error(`unsupported council template: ${template}`);
+  }
+
+  if (template === 'strategy-review') {
+    return buildStrategyReviewCouncilTask({ task, evidencePath, resultPath });
+  }
+  return buildCompetitiveAnalysisCouncilTask({ task, evidencePath, resultPath });
+}
+
+export function createCouncilRun({
+  task,
+  template = 'competitive-analysis',
+  evidencePath,
+  opts = {},
+  config = {},
+}) {
+  const ctx = makeArtifactContext({ command: 'council', query: task, opts, config });
+  if (!ctx) {
+    throw new Error('council runs require artifacts; omit --no-artifact for this command');
+  }
+
+  mkdirSync(ctx.artifactDir, { recursive: true });
+  const createdAt = new Date().toISOString();
+  const resultPath = join(ctx.artifactDir, COUNCIL_RESULT_FILE);
+  const taskText = buildCouncilTask({ task, template, evidencePath, resultPath });
+  const meta = {
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    command: 'council',
+    query: task,
+    template,
+    evidencePath: evidencePath || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+  };
+  const result = {
+    query: task,
+    answer: '',
+    sources: [],
+    command: 'council',
+    mode: 'council',
+    model: 'model-council',
+    template,
+    evidencePath: evidencePath || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+    councilResultFile: COUNCIL_RESULT_FILE,
+  };
+
+  writeJson(join(ctx.artifactDir, 'meta.json'), meta);
+  writeFileSync(join(ctx.artifactDir, 'query.txt'), `${task}\n`, 'utf8');
+  writeFileSync(join(ctx.artifactDir, 'answer.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.json'), result);
+  writeJson(join(ctx.artifactDir, 'sources.json'), []);
+  writeFileSync(join(ctx.artifactDir, 'task.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.schema.json'), RESULT_SCHEMA);
+  writeJson(join(ctx.artifactDir, COUNCIL_RESULT_FILE), PENDING_COUNCIL_RESULT);
+
+  return {
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    taskPath: join(ctx.artifactDir, 'task.md'),
+    resultPath,
+  };
+}
+
+function assertCouncilResult(value) {
+  const missing = [
+    'summary',
+    'consensus',
+    'disagreements',
+    'risks',
+    'recommendations',
+    'followups',
+    'sources',
+    'confidence',
+    'checked_at',
+    'notes',
+  ].filter((key) => !(key in value));
+  if (missing.length) return { ok: false, reason: `missing fields: ${missing.join(', ')}` };
+  if (!['low', 'medium', 'high'].includes(value.confidence)) {
+    return { ok: false, reason: 'confidence must be low, medium, or high' };
+  }
+  for (const key of ['consensus', 'disagreements', 'risks', 'recommendations', 'followups', 'sources', 'notes']) {
+    if (!Array.isArray(value[key])) return { ok: false, reason: `${key} must be an array` };
+  }
+  return { ok: true, reason: null };
+}
+
+export function inspectCouncilRun(runDir) {
+  const artifactDir = resolve(runDir);
+  const resultPath = join(artifactDir, COUNCIL_RESULT_FILE);
+  const metaPath = join(artifactDir, 'meta.json');
+  if (!existsSync(metaPath)) {
+    return { status: 'missing', artifactDir, resultPath, reason: 'meta.json not found' };
+  }
+  if (!existsSync(resultPath)) {
+    return { status: 'pending', artifactDir, resultPath, reason: `${COUNCIL_RESULT_FILE} not found` };
+  }
+  try {
+    const result = readJsonFile(resultPath);
+    if (result._status === 'pending') {
+      return { status: 'pending', artifactDir, resultPath, reason: `${COUNCIL_RESULT_FILE} is still pending` };
+    }
+    const validation = assertCouncilResult(result);
+    return {
+      status: validation.ok ? 'complete' : 'invalid',
+      artifactDir,
+      resultPath,
+      reason: validation.reason,
+      result,
+    };
+  } catch (e) {
+    return { status: 'invalid', artifactDir, resultPath, reason: e.message };
+  }
+}
+
+export function importCouncilResult(runDir) {
+  const status = inspectCouncilRun(runDir);
+  if (status.status !== 'complete') {
+    throw new Error(`council result is ${status.status}: ${status.reason}`);
+  }
+  return status.result;
+}
+
+export function openCouncilUrl() {
+  if (process.platform === 'darwin') {
+    execFileSync('open', [COUNCIL_URL]);
+    return true;
+  }
+  return false;
+}
+
+export function copyCouncilTaskToClipboard(runDir) {
+  const taskText = readCouncilTaskFile(runDir);
+  return copyTextToClipboard(taskText);
+}
+
+export function readCouncilTaskFile(runDir) {
+  return readFileSync(join(resolve(runDir), 'task.md'), 'utf8');
+}

package/src/mcp-server.js

@@ -0,0 +1,437 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { loadConfig } from './config.js';
+import { loadCookies } from './cookies.js';
+import { testAuth } from './session.js';
+import { search } from './search.js';
+import { LabsClient } from './labs.js';
+import { resolveTimeoutMs } from './timeout.js';
+import { makeArtifactContext, resolveArtifactDir, writeStandardArtifact } from './artifacts.js';
+import {
+  COMPUTER_TEMPLATES,
+  createComputerRun,
+  importComputerResult,
+  inspectComputerRun,
+  readTaskFile,
+} from './computer.js';
+import {
+  COUNCIL_TEMPLATES,
+  createCouncilRun,
+  importCouncilResult,
+  inspectCouncilRun,
+  readCouncilTaskFile,
+} from './council.js';
+import { MODEL_MAP, LABS_MODELS } from './constants.js';
+
+const SERVER_NAME = 'pplx';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const SERVER_VERSION = pkg.version;
+const SEARCH_MODES = ['auto', 'pro', 'reasoning', 'deep-research'];
+const TRANSPORTS = ['auto', 'http', 'playwright', 'curl', 'chrome'];
+
+const optionalArtifactArgs = {
+  out: z.string().optional().describe('Artifact root for this run. Defaults to ~/.config/pplx/config.json artifactDir.'),
+  artifactId: z.string().optional().describe('Deterministic artifact id for this run.'),
+  saveArtifact: z.boolean().optional().default(true).describe('Save the standard pplx artifact files.'),
+};
+
+function toTextResult(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    structuredContent: value,
+  };
+}
+
+function normalizeSources(sources) {
+  if (!sources) return ['web'];
+  if (Array.isArray(sources)) return sources;
+  return String(sources).split(',').map((source) => source.trim()).filter(Boolean);
+}
+
+function normalizeSourceResult(result) {
+  return {
+    title: result.name || result.title || '',
+    url: result.url || '',
+  };
+}
+
+function mcpArtifactOpts(args = {}) {
+  if (args.saveArtifact === false) return { artifact: false };
+  return {
+    out: args.out,
+    artifactId: args.artifactId,
+  };
+}
+
+function transportOpts(transport, config) {
+  if (transport === 'chrome') return { chrome: true };
+  if (transport === 'playwright') return { playwright: true };
+  if (transport === 'curl') return { curl: true };
+  if (transport === 'http') return { playwright: false, chrome: false, curl: false };
+  return {
+    chrome: config.chrome,
+    playwright: config.playwright,
+    curl: config.curl,
+  };
+}
+
+async function assertAuthReady({ cookies, opts }) {
+  if (opts.chrome || opts.allowAnonymous) return;
+  if (Object.keys(cookies).length === 0) {
+    throw new Error('No Perplexity cookies stored. Run: pplx auth --browser auto');
+  }
+  const ok = await testAuth(cookies);
+  if (!ok) {
+    throw new Error('Stored Perplexity cookies are invalid or expired. Run: pplx auth --browser auto');
+  }
+}
+
+export async function runSearchTool(args) {
+  const config = loadConfig();
+  const mode = args.mode || 'pro';
+  const transport = args.transport || 'auto';
+  const opts = {
+    ...config,
+    ...transportOpts(transport, config),
+    mode,
+    model: args.model,
+    sources: normalizeSources(args.sources),
+    language: args.language || args.lang || 'en-US',
+    incognito: args.incognito ?? false,
+    allowAnonymous: args.allowAnonymous ?? false,
+    timeoutMs: undefined,
+  };
+  opts.timeoutMs = resolveTimeoutMs({ ...opts, timeoutMs: args.timeoutMs, mode });
+
+  const cookies = loadCookies() || {};
+  await assertAuthReady({ cookies, opts });
+
+  const artifactCtx = makeArtifactContext({
+    command: mode === 'deep-research' ? 'research' : mode === 'reasoning' ? 'reason' : 'search',
+    query: args.query,
+    opts: mcpArtifactOpts(args),
+    config,
+  });
+
+  let lastAnswer = '';
+  let lastData = null;
+  for await (const data of search(args.query, cookies, opts)) {
+    lastData = data;
+    if ((data.answer || '').length >= lastAnswer.length) {
+      lastAnswer = data.answer || lastAnswer;
+    }
+  }
+
+  const answer = lastData?.answer || lastAnswer || '';
+  if (!answer) throw new Error('No answer received from Perplexity.');
+
+  const sources = (lastData?.web_results || []).map(normalizeSourceResult);
+  const artifactInfo = writeStandardArtifact(artifactCtx, {
+    answer,
+    sources,
+    mode,
+    model: args.model || 'default',
+  });
+
+  return {
+    query: args.query,
+    answer,
+    sources,
+    mode,
+    model: args.model || 'default',
+    artifactDir: artifactInfo?.artifactDir || null,
+    artifactId: artifactInfo?.artifactId || null,
+  };
+}
+
+export async function runLabsTool(args) {
+  const config = loadConfig();
+  const model = args.model || 'sonar';
+  const artifactCtx = makeArtifactContext({
+    command: 'labs',
+    query: args.query,
+    opts: mcpArtifactOpts(args),
+    config,
+  });
+  const client = new LabsClient();
+  let answer = '';
+  const events = [];
+  try {
+    await client.connect();
+    for await (const data of client.ask(args.query, model)) {
+      events.push(data);
+      answer = data.output || answer;
+    }
+  } finally {
+    client.close();
+  }
+
+  const artifactInfo = writeStandardArtifact(artifactCtx, {
+    answer,
+    sources: [],
+    mode: 'labs',
+    model,
+  });
+
+  return {
+    query: args.query,
+    answer,
+    events,
+    mode: 'labs',
+    model,
+    artifactDir: artifactInfo?.artifactDir || null,
+    artifactId: artifactInfo?.artifactId || null,
+  };
+}
+
+export async function getAuthStatus() {
+  const cookies = loadCookies() || {};
+  const cookieCount = Object.keys(cookies).length;
+  if (cookieCount === 0) {
+    return {
+      authenticated: false,
+      cookieCount,
+      message: 'No cookies stored. Run: pplx auth --browser auto',
+    };
+  }
+  const authenticated = await testAuth(cookies);
+  return {
+    authenticated,
+    cookieCount,
+    message: authenticated
+      ? 'Stored Perplexity cookies are valid.'
+      : 'Stored Perplexity cookies are invalid or expired. Run: pplx auth --browser auto',
+  };
+}
+
+function resolveRunDir(run, out, config) {
+  if (isAbsolute(run) || run.includes('/')) return resolve(run);
+  return join(resolveArtifactDir({ out, config }), run);
+}
+
+export function createPplxMcpServer() {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+
+  server.registerTool('pplx_search', {
+    title: 'Perplexity Search',
+    description: 'Run an authenticated Perplexity search/reasoning/deep-research query and return answer, sources, and artifact paths.',
+    inputSchema: {
+      query: z.string().min(1).describe('Question or research prompt.'),
+      mode: z.enum(SEARCH_MODES).optional().default('pro').describe('Perplexity mode.'),
+      model: z.string().optional().describe('Optional model alias or raw Perplexity model id.'),
+      sources: z.array(z.string()).optional().default(['web']).describe('Source types such as web, scholar, or social.'),
+      language: z.string().optional().default('en-US').describe('Language code.'),
+      incognito: z.boolean().optional().default(false).describe('Do not save the query to Perplexity history.'),
+      transport: z.enum(TRANSPORTS).optional().default('auto').describe('Transport override for Perplexity calls.'),
+      timeoutMs: z.union([z.string(), z.number()]).optional().describe('Overall stream timeout, e.g. 120s, 10m, or milliseconds.'),
+      allowAnonymous: z.boolean().optional().default(false).describe('Allow anonymous Perplexity responses when cookies are missing or expired.'),
+      ...optionalArtifactArgs,
+    },
+    annotations: {
+      title: 'Perplexity Search',
+      readOnlyHint: false,
+      openWorldHint: true,
+    },
+  }, async (args) => toTextResult(await runSearchTool(args)));
+
+  server.registerTool('pplx_labs', {
+    title: 'Perplexity Labs',
+    description: 'Query Perplexity Labs models without browser-cookie auth.',
+    inputSchema: {
+      query: z.string().min(1).describe('Question or prompt.'),
+      model: z.enum(LABS_MODELS).optional().default('sonar').describe('Labs model.'),
+      ...optionalArtifactArgs,
+    },
+    annotations: {
+      title: 'Perplexity Labs',
+      readOnlyHint: false,
+      openWorldHint: true,
+    },
+  }, async (args) => toTextResult(await runLabsTool(args)));
+
+  server.registerTool('pplx_auth_status', {
+    title: 'Perplexity Auth Status',
+    description: 'Check whether stored Perplexity cookies are present and authenticated.',
+    inputSchema: {},
+    annotations: {
+      title: 'Perplexity Auth Status',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async () => toTextResult(await getAuthStatus()));
+
+  server.registerTool('pplx_models', {
+    title: 'Perplexity Models',
+    description: 'List known Perplexity model aliases exposed by pplx-cli.',
+    inputSchema: {},
+    annotations: {
+      title: 'Perplexity Models',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async () => toTextResult({ modes: MODEL_MAP, labs: LABS_MODELS }));
+
+  server.registerTool('pplx_computer_create', {
+    title: 'Create Perplexity Computer Handoff',
+    description: 'Create a Perplexity Computer artifact handoff folder containing task.md, result.schema.json, and computer-result.json.',
+    inputSchema: {
+      task: z.string().min(1).describe('Live web task for Perplexity Computer.'),
+      template: z.enum(COMPUTER_TEMPLATES).optional().default('compare').describe('Computer task template.'),
+      out: z.string().optional().describe('Artifact root for this run.'),
+      artifactId: z.string().optional().describe('Deterministic artifact id for this run.'),
+    },
+    annotations: {
+      title: 'Create Perplexity Computer Handoff',
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const run = createComputerRun({
+      task: args.task,
+      template: args.template || 'compare',
+      opts: { out: args.out, artifactId: args.artifactId },
+      config: loadConfig(),
+    });
+    return toTextResult(run);
+  });
+
+  server.registerTool('pplx_council_create', {
+    title: 'Create Perplexity Model Council Handoff',
+    description: 'Create a Perplexity Model Council artifact handoff folder containing task.md, result.schema.json, and council-result.json.',
+    inputSchema: {
+      task: z.string().min(1).describe('Judgment, strategy, or competitive-analysis task for Model Council.'),
+      template: z.enum(COUNCIL_TEMPLATES).optional().default('competitive-analysis').describe('Council task template.'),
+      evidencePath: z.string().optional().describe('Optional local evidence artifact path to reference in the Council task.'),
+      out: z.string().optional().describe('Artifact root for this run.'),
+      artifactId: z.string().optional().describe('Deterministic artifact id for this run.'),
+    },
+    annotations: {
+      title: 'Create Perplexity Model Council Handoff',
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const run = createCouncilRun({
+      task: args.task,
+      template: args.template || 'competitive-analysis',
+      evidencePath: args.evidencePath,
+      opts: { out: args.out, artifactId: args.artifactId },
+      config: loadConfig(),
+    });
+    return toTextResult(run);
+  });
+
+  server.registerTool('pplx_council_status', {
+    title: 'Perplexity Model Council Status',
+    description: 'Inspect a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Perplexity Model Council Status',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(inspectCouncilRun(runDir));
+  });
+
+  server.registerTool('pplx_council_import', {
+    title: 'Import Perplexity Model Council Result',
+    description: 'Read and validate a completed council-result.json from a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Import Perplexity Model Council Result',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(importCouncilResult(runDir));
+  });
+
+  server.registerTool('pplx_council_read_task', {
+    title: 'Read Perplexity Model Council Task',
+    description: 'Read the task.md prompt from a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Read Perplexity Model Council Task',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult({ runDir, task: readCouncilTaskFile(runDir) });
+  });
+
+  server.registerTool('pplx_computer_status', {
+    title: 'Perplexity Computer Status',
+    description: 'Inspect a Perplexity Computer artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Perplexity Computer Status',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(inspectComputerRun(runDir));
+  });
+
+  server.registerTool('pplx_computer_import', {
+    title: 'Import Perplexity Computer Result',
+    description: 'Read and validate a completed computer-result.json from a Perplexity Computer artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Import Perplexity Computer Result',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(importComputerResult(runDir));
+  });
+
+  server.registerTool('pplx_computer_read_task', {
+    title: 'Read Perplexity Computer Task',
+    description: 'Read the task.md prompt from a Perplexity Computer artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Read Perplexity Computer Task',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult({ runDir, task: readTaskFile(runDir) });
+  });
+
+  return server;
+}
+
+export async function runMcpServer() {
+  const server = createPplxMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('pplx MCP server running on stdio');
+}