搜索集成服务器

困惑MCP服务器

MCP服务器向Claude展示了Perplexity AI的搜索功能，实现了对话过程中无缝的研究集成。

🚧 开发状态

当前版本： v0.1.0-alpha（主动开发中）

✅ 完成

• 项目基础和安全设置
• API密钥验证配置管理
• 具有重试逻辑和错误处理的困惑API客户端
• 使用FastMCP实现MCP服务器
• 全面的测试套件
• 安全验证和消毒

🔮 计划（未来阶段）

• 困惑空间整合
• 内存和上下文管理
• 跨空间的主题总结
• 跨平台数据综合
• 从多源数据生成文档

注： 该项目尚处于早期开发阶段。API和功能可能会发生变化。

安装

先决条件

• Python 3.10或更高版本
• 困惑API键(在这里买一个)
• 支持MCP的Claude Desktop或Claude Code

逐步设置

1. 克隆存储库

   复制

   git clone https://github.com/yourusername/claude-perplexity-mcp-server.git
   cd claude-perplexity-mcp-server
   

2. 创建虚拟环境 （推荐）

   复制

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate
   

3. 安装依赖项

   复制

   pip install -r requirements.txt
   

4. 配置环境变量

   复制

   # Copy the example file
   cp .env.example .env
   
   # Edit .env and add your Perplexity API key
   # PERPLEXITY_API_KEY=pplx-your-actual-api-key-here
   

5. 验证配置

   复制

   python -c "from config import get_config; print('Configuration loaded successfully')"
   

6. 测试服务器 （可选）

   复制

   python server.py
   

配置

所有配置均通过环境变量进行管理 .env 文件。看 .env.example 对于模板。

环境变量

模型选项

• sonar -标准型号
• sonar-pro -具有更好推理能力的增强模型（推荐）

搜索焦点选项

• web -常规网络搜索（默认）
• academic -学术和研究来源
• sec -以安全为重点的来源

最近度过滤器

• hour -最后一小时
• day -最后一天
• week -上周
• month -上个月
• year -去年

用法

设置Claude桌面

1. 查找Claude桌面配置

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • 窗户： %APPDATA%\Claude\claude_desktop_config.json

2. 添加MCP服务器配置

   复制

   {
     "mcpServers": {
       "perplexity-search": {
         "command": "python",
         "args": ["C:/path/to/claude-perplexity-mcp-server/server.py"],
         "env": {
           "PERPLEXITY_API_KEY": "pplx-your-key-here"
         }
       }
     }
   }
   

   注： 对于Windows，请在路径中使用正斜杠或转义反斜杠：

   复制

   "args": ["C:\\Users\\YourName\\path\\to\\server.py"]
   

3. 重新启动克劳德桌面

4. 验证工具是否可用

   • 这 perplexity_search 工具应该出现在Claude的可用工具中
   • 你可以问克劳德：“你有什么工具？”

使用工具

只需让克劳德搜索信息：

"Search Perplexity for the latest developments in quantum computing"

或者更具体地说：

"Use perplexity_search to find recent news about Python 3.12 features"

工具参数

Claude在调用工具时可以使用这些参数：

• 怎么翻译 （必填）：您的搜索问题
• 模型 （可选）：替代默认模型(sonar 或 sonar-pro)
• 搜索焦点 （可选）： web, academic，或 sec
• 新近性 （可选）： hour, day, week, month，或 year

查询示例

• “人工智能的最新发展是什么？”
• “搜索气候变化解决方案的最新研究”
• “查找有关Python编程语言的最新信息”

已知限制

引文显示问题

当前状态： 引用包含在工具响应中，但可能无法在Claude Desktop的UI中正确显示。

• 原始JSON： 引用在原始工具响应JSON中正确显示
• 文本显示： 引文标记和链接可能无法在Claude Desktop的文本输出中呈现
• 解决方法： 在Claude Desktop的开发人员工具或JSON视图中检查原始工具响应

我们正在积极努力解决这一限制。 这是Claude Desktop如何处理MCP工具响应和引文格式的一个已知问题。

其他限制

• 费率限制适用于您的困惑API等级
• 连接速度慢时可能会出现网络超时（自动重试并回退）
• 出于安全考虑，非常长的查询（>10000个字符）被拒绝

故障排除

服务器无法启动

问题： ModuleNotFoundError: No module named 'mcp'

解决方案：

pip install -r requirements.txt

问题： ValueError: PERPLEXITY_API_KEY not found

解决方案：

• 确保 .env 文件存在于项目根目录中
• 验证 PERPLEXITY_API_KEY 设定在 .env
• 检查API密钥是否以 pplx-

工具未出现在Claude桌面中

问题： 工具未显示在Claude Desktop中

解决：

1. 验证中的路径 claude_desktop_config.json 是正确的
2. 确保Python在您的系统PATH中
3. 检查一下 server.py 可执行
4. 完全重新启动克劳德桌面
5. 检查Claude Desktop日志是否有错误

API错误

问题： API authentication failed

解决方案：

• 在中验证您的API密钥是否正确 .env
• 确保API密钥未过期
• 查看您的困惑账户了解API使用限制

问题： Rate limit exceeded

解决方案：

• 请稍等片刻，然后重试
• 检查您的困惑API等级和费率限制
• 如果需要，考虑升级您的困惑计划

网络问题

问题： Request timed out

解决方案：

• 检查您的互联网连接
• 验证困惑API是否可以从您的网络访问
• 重试（指数回退自动重试）

配置问题

问题： 模型或参数错误无效

解决方案：

• 检查 .env.example 对于有效选项
• 验证 DEFAULT_MODEL 设置为 sonar 或 sonar-pro
• 确保 search_focus 值为： web, academic，或 sec
• 确保 recency 值为： hour, day, week, month，或 year

安全

最佳实践

• 永不承诺 .env 文件 -它们包含敏感的API密钥
• 使用环境变量 -所有秘密都从加载 .env
• 消毒伐木 -API密钥从未完全登录
• URL验证 -引用经过验证，以防止恶意网址

提交前的安全检查表

在每次提交之前运行以下命令：

• [ ] .env 在...里 .gitignore 而不是上演
• []代码、注释或文档中没有API键
• [ ] .env.example 仅包含占位符值
• []错误消息不会泄露机密
• []日志已消毒
• []所有机密都使用环境变量

快速检查： git diff --cached 并搜索 pplx-

看 安全.md 详细的安全政策和负责任的披露指南。

发展

运行测试

python test_phase5.py

项目结构

claude-perplexity-mcp-server/
├── .env.example          # Configuration template
├── .gitignore           # Git ignore rules
├── README.md            # This file
├── SECURITY.md          # Security policy
├── requirements.txt     # Python dependencies
├── config.py           # Configuration management
├── perplexity_client.py # Perplexity API client
├── server.py           # MCP server implementation
└── test_phase5.py      # Test suite

代码质量

• 全程键入提示
• 全面的错误处理
• 安全第一设计
• 符合PEP 8标准
• 所有公共函数的文档字符串

贡献

欢迎投稿！请确保：

1. 代码遵循现有的样式和模式
2. 所有测试均通过
3. 遵循安全检查表
4. 文档已更新
5. 包括类型提示

许可证

Apache 2.0许可证-有关详细信息，请参阅许可证文件。

支持

对于问题、疑问或贡献：

• 安全问题： 看 安全.md
• Bug报告： 在GitHub上打开一个问题
• 功能请求： 打开一个问题 enhancement 标签

致谢

• 内置于 FastMCP -高级MCP SDK
• 由...驱动 困惑AI -人工智能驱动的搜索
• 专为 克劳德桌面 -Anthropic的人工智能助手