困惑者-MCP

Name: 困惑者-MCP
Author: thetom42

作者：thetom4225 星标更新：2025-10-06

安装使用来源：spider==github.com

项目介绍

Perplexica MCP Server

一个使用Perplexica的AI驱动搜索引擎提供搜索功能的Model Context Protocol (MCP)服务器。

功能

搜索工具：支持多种聚焦模式的AI驱动网络搜索
多传输支持：支持stdio、SSE和可流式传输的HTTP传输
FastMCP集成：使用FastMCP构建，确保强大的MCP协议合规性
统一架构：单个服务器实现支持所有传输模式
生产就绪：支持Docker并采用最佳安全实践

开发环境

对于Claude Code用户

重要：如果你正在使用Claude Code进行开发，该项目要求在所有开发操作中使用container-use MCP服务器。所有文件操作、代码更改和shell命令必须在container-use环境中执行。

使用Container-Use（仅限Claude Code）

当使用Claude Code贡献此项目时，你必须：

仅使用Container-Use：所有文件操作、代码编辑和shell命令必须通过container-use环境执行
查看你的工作：在做出更改后，告知他人如何访问你的工作：
- 使用container-use log <env_id>查看开发日志
- 使用container-use checkout <env_id>检查出你的环境
不进行本地操作：不要直接在本地文件系统上执行文件操作

示例开发流程（Claude Code）

# 创建一个新的环境用于你的工作
container-use create --title "你的功能描述"

# 使用container-use工具进行更改
# （所有文件操作由container-use处理）

# 与他人分享你的工作
container-use log <你的-env-id>
container-use checkout <你的-env-id>

这确保了使用Claude Code时所有开发活动的一致性、可重复性和适当的版本控制。

对于其他开发环境

如果你不使用Claude Code，你可以使用你喜欢的工具和IDE正常开发。常规开发流程不需要container-use的要求。

安装

从PyPI安装（推荐）

# 直接从PyPI安装
pip install perplexica-mcp

# 或者使用uvx进行隔离执行
uvx perplexica-mcp --help

从源码安装

# 克隆仓库
git clone https://github.com/thetom42/perplexica-mcp.git
cd perplexica-mcp

# 安装依赖
uv sync

MCP客户端配置

要使用此服务器与MCP客户端，你需要配置客户端以连接到Perplexica MCP服务器。以下是流行MCP客户端的配置示例。

重要：所有传输模式都需要正确配置环境变量，特别是：

PERPLEXICA_BACKEND_URL：指向你的Perplexica后端API的URL

PERPLEXICA_CHAT_MODEL_PROVIDER 和 PERPLEXICA_CHAT_MODEL_NAME：聊天模型配置

PERPLEXICA_EMBEDDING_MODEL_PROVIDER 和 PERPLEXICA_EMBEDDING_MODEL_NAME：嵌入模型配置

这些变量必须在你的环境中设置或在MCP客户端配置中提供。

Claude Desktop

Stdio传输（推荐）

在你的Claude Desktop配置文件中添加以下内容：

位置：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "perplexica": {
      "command": "uvx",
      "args": ["perplexica-mcp", "stdio"],
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

替代方案（从源码）：

{
  "mcpServers": {
    "perplexica": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

注意：从源码运行时，请确保设置了所有必需的环境变量。stdio传输需要正确的模型提供商和模型名称配置以与Perplexica后端通信。

SSE传输

首先启动服务器：

uv run src/perplexica_mcp/server.py sse

然后配置Claude Desktop：

{
  "mcpServers": {
    "perplexica": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Cursor IDE

在你的Cursor MCP配置中添加：

{
  "servers": {
    "perplexica": {
      "command": "uvx",
      "args": ["perplexica-mcp", "stdio"],
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

替代方案（从源码）：

{
  "servers": {
    "perplexica": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

VS Code（带有MCP扩展）

在你的VS Code MCP配置文件（.vscode/mcp.json）中添加：

{
  "servers": {
    "perplexica": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

通用MCP客户端配置

对于任何支持stdio传输的MCP客户端：

# 命令以运行服务器（PyPI安装）
uvx perplexica-mcp stdio

# 命令以运行服务器（带.env文件的PyPI安装）
uvx --env-file .env perplexica-mcp stdio

# 命令以运行服务器（从源码）
uv run python -m perplexica_mcp stdio

# 环境变量（可以导出或内联设置）
export PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search
export PERPLEXICA_CHAT_MODEL_PROVIDER=openai
export PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini
export PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai
export PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small

# 或者内联设置以供单次执行（所有必需的变量）
PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search \
PERPLEXICA_CHAT_MODEL_PROVIDER=openai \
PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini \
PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai \
PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small \
uvx perplexica-mcp stdio

对于HTTP/SSE传输客户端：

# 启动服务器（PyPI安装）
uvx perplexica-mcp sse  # 或 'http'

# 启动服务器（从源码）
uv run /path/to/perplexica-mcp/src/perplexica_mcp/server.py sse  # 或 'http'

# 连接到端点
SSE: http://localhost:3001/sse
HTTP: http://localhost:3002/mcp/

配置说明

路径配置：用实际的安装路径替换/path/to/perplexica-mcp/
Perplexica URL：确保PERPLEXICA_BACKEND_URL指向你的运行中的Perplexica实例
传输选择：
- 使用stdio用于大多数MCP客户端（Claude Desktop、Cursor）
- 使用SSE用于基于Web的客户端或实时应用
- 使用HTTP用于REST API集成
依赖项：确保uvx已安装并在PATH中可用（或uv用于源码安装）

故障排除

服务器无法启动：检查uvx（或uv用于源码）是否已安装且路径正确
连接被拒绝：验证Perplexica是否在配置的URL上运行并可访问
权限错误：确保MCP客户端有权执行服务器命令
环境变量：检查PERPLEXICA_BACKEND_URL是否正确设置

服务器配置

在项目根目录创建一个.env文件，包含你的Perplexica配置：

# Perplexica后端配置
PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search

# 默认模型配置（可选）
# 如果设置，这些模型将在未指定搜索请求中的模型时作为默认值使用

# 聊天模型配置
PERPLEXICA_CHAT_MODEL_PROVIDER=openai
PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini

# 嵌入模型配置
PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai
PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small

环境变量

变量	描述	默认值	示例
`PERPLEXICA_BACKEND_URL`	指向Perplexica搜索API的URL	`http://localhost:3000/api/search`	`http://localhost:3000/api/search`
`PERPLEXICA_CHAT_MODEL_PROVIDER`	默认聊天模型提供商	无	`openai`，`ollama`，`anthropic`
`PERPLEXICA_CHAT_MODEL_NAME`	默认聊天模型名称	无	`gpt-4o-mini`，`claude-3-sonnet`
`PERPLEXICA_EMBEDDING_MODEL_PROVIDER`	默认嵌入模型提供商	无	`openai`，`ollama`
`PERPLEXICA_EMBEDDING_MODEL_NAME`	默认嵌入模型名称	无	`text-embedding-3-small`

注意：模型环境变量是可选的。如果未设置，你需要在每个搜索请求中指定模型。设置后，它们提供了方便的默认值，但仍可以在每次请求中覆盖。

使用方法

服务器支持三种传输模式：

1. Stdio传输

# PyPI安装
uvx perplexica-mcp stdio

# 从源码
uv run src/perplexica_mcp/server.py stdio

2. SSE传输

# PyPI安装
uvx perplexica-mcp sse [host] [port]

# 从源码
uv run src/perplexica_mcp/server.py sse [host] [port]
# 默认：localhost:3001，端点：/sse

3. 可流式传输的HTTP传输

# PyPI安装
uvx perplexica-mcp http [host] [port]

# 从源码
uv run src/perplexica_mcp/server.py http [host] [port]
# 默认：localhost:3002，端点：/mcp

Docker部署

服务器包括Docker支持，具有多个传输配置，适用于容器化部署。

前提条件

已安装Docker和Docker Compose
外部Docker网络名为backend（用于与Perplexica集成）

创建外部网络

docker network create backend

构建和运行

选项1：HTTP传输（可流式传输的HTTP）

# 使用HTTP传输构建和运行
docker-compose up -d

# 或先构建，再运行
docker-compose build
docker-compose up -d

选项2：SSE传输（服务器发送事件）

# 使用SSE传输构建和运行
docker-compose -f docker-compose-sse.yml up -d

# 或先构建，再运行
docker-compose -f docker-compose-sse.yml build
docker-compose -f docker-compose-sse.yml up -d

环境配置

两个Docker配置都支持环境变量：

# 为Docker创建.env文件
cat > .env << EOF
PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search
EOF

# 在docker-compose.yml中取消注释env_file以使用.env文件

或者直接在compose文件中设置环境变量：

environment:
  - PERPLEXICA_BACKEND_URL=http://your-perplexica-host:3000/api/search

容器详情

传输	容器名称	端口	端点	健康检查
HTTP	`perplexica-mcp-http`	3001	`/mcp/`	MCP初始化请求
SSE	`perplexica-mcp-sse`	3001	`/sse`	SSE端点检查

健康监控

两个容器都包括健康检查：

# 检查容器健康
docker ps
docker-compose ps

# 查看健康检查日志
docker logs perplexica-mcp-http
docker logs perplexica-mcp-sse

与Perplexica集成

Docker设置假设Perplexica在同一Docker网络中运行：

# 同一compose文件中的Perplexica服务示例
services:
  perplexica-app:
    # ... 你的Perplexica配置
    networks:
      - backend
  
  perplexica-mcp:
    # ... MCP服务器配置
    environment:
      - PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search
    networks:
      - backend

生产考虑

两个容器都使用restart: unless-stopped以提高可靠性
健康检查确保服务可用性
外部网络允许与现有的Perplexica部署集成
Dockerfile中实现了最佳安全实践

可用工具

搜索

使用Perplexica执行AI驱动的网络搜索。

参数：

query（字符串，必填）：搜索查询
focus_mode（字符串，必填）：其中之一：'webSearch'，'academicSearch'，'writingAssistant'，'wolframAlphaSearch'，'youtubeSearch'，'redditSearch'
chat_model（字符串，可选）：聊天模型配置
embedding_model（字符串，可选）：嵌入模型配置
optimization_mode（字符串，可选）：'speed' 或 'balanced'
history（数组，可选）：对话历史
system_instructions（字符串，可选）：自定义指令
stream（布尔值，可选）：是否流式传输响应

测试

运行全面测试套件以验证所有传输：

uv run src/test_transports.py

这将测试：

✓ Stdio传输与MCP协议握手
✓ HTTP传输与可流式传输的HTTP兼容性
✓ SSE传输端点可达性

传输细节

Stdio传输

使用FastMCP内置的stdio服务器
支持完整的MCP协议，包括初始化和工具列表
适合MCP客户端集成

SSE传输

用于实时通信的服务器发送事件
端点：http://host:port/sse
包括周期性的ping消息以检查连接健康状况

可流式传输的HTTP传输

符合MCP可流式传输的HTTP规范
端点：http://host:port/mcp
根据协议返回307重定向到/mcp/
使用StreamableHTTPSessionManager进行适当的会话管理

开发

服务器使用以下构建：

FastMCP：现代MCP服务器框架，内置传输支持
Uvicorn：用于SSE和HTTP传输的ASGI服务器
httpx：用于Perplexica API通信的HTTP客户端
python-dotenv：环境变量管理

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP客户端    │◄──►│ Perplexica MCP   │◄──►│   Perplexica    │
│                 │    │     服务器       │    │   搜索API    │
│  (stdio/SSE