Perplexitysearchmcp

困惑度搜索MCP（或：基于困惑度的搜索MCP）

仅暴露一个工具的最小化MCP服务器 perplexity_search 使用Perplexity Python SDK返回结构化的网页搜索结果client.search.create）。 通过……进行配置 PERPLEXITY_API_KEY使用 structlog 进行结构化日志记录。不涉及 LLM/Sonar 端点，也不使用分页。

状态：最有价值球员（MVP）

快速入门

MCP配置编辑器示例（mcp-settings.json）

此配置通过uvx启动服务器，直接从Git远程仓库拉取代码。请在环境变量中设置PERPLEXITY_API_KEY。

{
  "mcpServers": {
    "perplexity-search-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/IngLP/PerplexitySearchMCP.git@main",
        "perplexity-search-mcp"
      ],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-...",
        "LOG_FORMAT": "console"
      }
    }
  }
}

特点/特性

• 一个MCP工具： perplexity_search
• 输入：

- query字符串（必填，去除空格后非空，最大长度4096） - num_results整数（默认值10，限制在\[1, 30\]范围内）

• 输出： { "results": [ { "title": str, "url": str, "date": str?, "last_update": str, "snippet": str }, ... ] }
• 可观测性：使用structlog记录包含每个请求上下文的JSON/控制台日志
• 超时与重试：总超时时间为5秒；仅对临时连接错误进行一次重试
• 配置： PERPLEXITY_API_KEY 在环境中

行为细节

• 无分页；单次调用可返回多达 num_results
• 瞬时错误处理：仅在连接级别错误时重试一次
• 超时时间：每个提供者调用总计5秒
• 出现了作为工具错误的异常（没有HTTP风格的映射）

记录日志

• 使用 structlog 进行结构化日志记录
• 启动配置默认选择JSON；当（需要时）选择控制台 LOG_FORMAT=console 或者 stdout 是一个 TTY 并且 LOG_FORMAT 取消设置（或解除设置）
• 按请求字段：

- request_id， query （完整字符串）， query_length， num_results， result_count， duration_ms， provider_status， timeout_ms

• 切勿记录敏感信息。验证/授权错误应作为警告/错误记录，并附带简洁的信息。

环境变量

• PERPLEXITY_API_KEY困惑度API密钥（必需）
• LOG_FORMAT: json 或者 console （可选）
• LOG_LEVEL例如。， INFO， DEBUG，或数字（可选）

项目布局

• 服务器和工具：search_mcp/server.py
• 提供程序适配器：search_mcp/perplexity_adapter.py
• 测试：tests/

开发工作流程

• 运行测试

uv run pytest

• 预提交（运行代码检查工具、mypy、mdformat 和 pytest）

uv run pre-commit run -a || uv run pre-commit run -a || uv run pre-commit run -a

• 集成测试（真实API）

- 除非……否则跳过 PERPLEXITY_API_KEY 已被设定 - 执行一个实际的单一查询 num_results=1

注意事项和限制条件

• 此服务器不提供LLM/Sonar聊天完成功能（不在服务范围内）
• 不缓存、不持久化、不抓取
• 输出稳定： title， url，可选 date，更多 last_update 并且 snippet 对于所有结果

安全

• 仅读取 PERPLEXITY_API_KEY 在调用时从环境中（获取/获取到）
• 如果键缺失/为空，则失败并显示明确错误
• 错误信息简洁明了，不会泄露敏感数据