Perplexity MCP 服务器

一个 MCP 服务器，提供与 Perplexity AI API 交互的工具，使用 mcp-ts-template 构建。此服务器允许与 模型上下文协议 (MCP) 兼容的 AI 代理利用 Perplexity 的搜索增强查询功能。包含一个 showThinking 参数，使推理模型能够展示其内部推理过程。

核心功能

• 实用工具: 用于日志记录、错误处理、ID 生成、速率限制和请求上下文管理的可重用组件。
• 类型安全: 使用 TypeScript 的强类型。
• 错误处理: 强大的错误处理系统。
• 安全性: 基本安全功能，如输入清理。
• Perplexity 工具: 一个随时可用的工具，用于与 Perplexity Search API 交互。

.clinerules: 此存储库包含一个 .clinerules 文件，该文件充当 LLM 编码代理（如 Cline）的开发者速查表，提供有关此项目的代码库模式、文件位置和代码片段的快速参考。

目录

• 概述
  • 什么是模型上下文协议？
  • 架构 & 组件
• 功能
  • 核心实用工具
  • 类型安全
  • 错误处理
  • 安全性
  • Perplexity 搜索工具
• 安装
• 配置
• 项目结构
• 工具文档
  • perplexity_search
• 开发指南
  • 添加新工具
  • 添加新资源
• 许可证

概述

什么是模型上下文协议？

模型上下文协议 (MCP) 是一个框架，使 AI 系统能够与外部工具和资源交互。它允许语言模型：

• 执行工具，执行操作并返回结果
• 访问提供信息的结构化资源
• 通过标准化接口创建上下文工作流程

此服务器允许 AI 系统通过 MCP 使用 Perplexity API。

架构 & 组件

该服务器基于 mcp-ts-template 并遵循其模块化架构：

<details> <summary>点击展开架构图</summary>

flowchart TB
    subgraph API["API 层"]
        direction LR
        MCP["MCP 协议"]
        Val["验证"]
        San["清理"]

        MCP --> Val --> San
    end

    subgraph Core["核心组件"]
        direction LR
        Config["配置"]
        Logger["日志系统"]
        Error["错误处理"]
        Server["MCP 服务器"]

        Config --> Server
        Logger --> Server
        Error --> Server
    end

    subgraph Implementation["实现层"]
        direction LR
        Tool["工具 (Perplexity)"]
        Util["实用工具"]

        Tool --> Server
        Util --> Tool
    end

    San --> Config
    San --> Server

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class API,Core,Implementation layer
    class MCP,Val,San,Config,Logger,Error,Server,Tool,Util component

</details>

核心组件：

• 配置系统: 具有验证功能的环境感知配置
• 日志系统: 具有敏感数据编辑的结构化日志记录
• 错误处理: 具有一致模式的集中式错误处理
• MCP 服务器: 工具的协议实现
• 验证层: 使用 validator 和 sanitize-html 进行输入验证和清理。
• 实用工具: 用于常见操作的可重用实用函数

功能

核心实用工具

• 日志记录: 可配置的日志记录，具有文件轮换和敏感数据编辑
• 错误处理: 基于模式的错误分类和标准化报告
• ID 生成: 具有前缀支持的安全唯一标识符创建
• 速率限制: 请求限制以防止 API 滥用
• 请求上下文: 请求跟踪和关联
• 清理: 使用 validator 和 sanitize-html 进行输入验证和清理。
• 成本跟踪: 基于模型和令牌使用情况估算 Perplexity API 成本

类型安全

• 全局类型: 用于一致接口的共享类型定义
• 错误类型: 标准化错误代码和结构
• MCP 协议类型: MCP 协议的类型定义
• 工具类型: 用于工具注册和配置的接口

错误处理

• 基于模式的分类: 根据消息模式自动对错误进行分类
• 一致的格式: 具有附加上下文的标准化错误响应
• 错误映射: 用于特定领域错误的自定义错误转换
• 安全 Try/Catch 模式: 集中式错误处理助手

安全性

• 输入验证: 使用 validator 进行各种数据类型检查。
• 输入清理: 使用 sanitize-html 防止注入攻击。
• 参数范围: 在清理逻辑中强制执行限制以防止滥用。
• 敏感数据编辑: 日志中的自动编辑。

Perplexity 搜索工具

• perplexity_search: 此服务器提供的核心工具，支持与 Perplexity Search API 交互。

安装

前提条件

• Node.js (v18+)
• npm 或 yarn
• 一个 Perplexity API 密钥（参见 配置）

设置

1. 克隆此存储库：

   # 如果存储库 URL 不同，请替换为实际的 URL
   git clone https://github.com/casey/perplexity-mcp-server.git
   cd perplexity-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

配置

环境变量

此服务器需要以下环境变量：

变量	描述	默认值
PERPLEXITY_API_KEY	用于 Perplexity 身份验证的 API 密钥	(必需)
PERPLEXITY_DEFAULT_MODEL	用于 Perplexity 请求的默认模型	"sonar-reasoning"
PERPLEXITY_DEFAULT_SEARCH_CONTEXT	搜索上下文大小（'low'、'medium'、'high'）	"high"
LOG_LEVEL	日志记录级别（“debug”、“info”、“warn”、“error”）	"info"
NODE_ENV	运行时环境（“development”、“production”）	"development"

MCP 客户端设置

将此服务器添加到您的 MCP 客户端设置（例如，在 VS Code 或 Claude Desktop 中）：

{
  "mcpServers": {
    "perplexity": {
      "command": "node",
      "args": ["/path/to/perplexity-mcp-server/dist/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

将 /path/to/perplexity-mcp-server/dist/index.js 替换为已构建服务器文件的实际路径，并将 YOUR_PERPLEXITY_API_KEY 替换为您的密钥。

配置系统（内部）

内部配置系统管理设置：

• 环境配置: 从环境变量加载 API 密钥等设置。
• 验证: 验证配置值（例如，搜索上下文大小）。
• 日志记录: 记录缺少或无效配置的警告。

项目结构

代码库遵循 src/ 目录中的模块化结构：

src/
├── config/           # 配置管理
├── index.ts          # 主入口点
├── mcp-server/       # MCP 服务器实现
│   ├── server.ts     # 服务器设置和注册
│   └── tools/        # 工具实现
│       └── perplexitySearch/
│           ├── index.ts
│           ├── logic.ts
│           └── registration.ts
├── services/         # 外部服务集成
│   ├── index.ts
│   └── perplexityApi.ts
├── types-global/     # 全局类型定义
│   ├── errors.ts
│   ├── mcp.ts
│   └── tool.ts
└── utils/            # 实用函数
    ├── costTracker.ts
    ├── errorHandler.ts
    ├── idGenerator.ts
    ├── index.ts
    ├── logger.ts
    ├── rateLimiter.ts
    ├── requestContext.ts
    └── sanitization.ts

有关项目结构的详细最新视图，请运行：

npm run tree

工具文档

perplexity_search

perplexity_search 工具使用 Perplexity API 执行搜索增强查询。它接受自然语言查询，使用 Perplexity 的后端执行 Web 搜索，然后使用 LLM 根据搜索结果合成答案。

输入参数

参数	类型	必需	描述
query	string	是	要由 Perplexity 处理的主要搜索查询或问题
return_related_questions	boolean	否	如果为 true，则指示 Perplexity 模型在主答案旁边建议相关问题（默认值：false）
search_recency_filter	string	否	按时间范围过滤搜索结果（例如，“day”、“week”、“month”、“year”）
search_domain_filter	string[]	否	将搜索限制为特定域（例如，[“wikipedia.org”]）
showThinking	boolean	否	在响应中包含模型的内部推理（默认值：false）

示例

基本用法：

{
  "query": "量子计算的最新进展是什么？"
}

高级用法：

{
  "query": "量子计算的最新进展是什么？",
  "return_related_questions": true,
  "search_recency_filter": "month",
  "search_domain_filter": ["nature.com", "science.org", "arxiv.org"],
  "showThinking": true
}

开发指南

此项目使用 mcp-ts-template 中的结构和指南。

添加新工具

按照模板的指南：

1. 创建目录: src/mcp-server/tools/yourNewTool/
2. 定义逻辑 & 模式: logic.ts（输入/输出类型、验证模式、核心函数）。
3. 实现注册: registration.ts（导入逻辑、模式，使用 ErrorHandler.tryCatch 和 server.tool()）。
4. 导出注册: index.ts（导出注册函数）。
5. 在服务器中注册: src/mcp-server/server.ts（导入并调用注册函数）。

添加新资源

资源不是此服务器的主要重点，但如果需要，请按照模板的指南：

1. 创建目录: src/mcp-server/resources/yourNewResource/
2. 定义逻辑 & 模式: logic.ts（参数类型、查询模式、核心函数）。
3. 实现注册: registration.ts（导入逻辑、模式，定义 ResourceTemplate，使用 ErrorHandler.tryCatch 和 server.resource()）。
4. 导出注册: index.ts（导出注册函数）。
5. 在服务器中注册: src/mcp-server/server.ts（导入并调用注册函数）。

许可证

此项目已获得 Apache License 2.0 许可 - 有关详细信息，请参阅 LICENSE 文件。

---

<div align="center"> 使用 <a href="https://modelcontextprotocol.io/">模型上下文协议</a> 构建 </div>