使用说明

MCP搜索服务器-综合文档🚀

智能MCP（模型上下文协议）服务器，可帮助您使用强大的Exa AI搜索引擎发现和研究MCP服务器。使用FastMCP构建，可与Claude、Cursor等AI助手无缝集成。

🎥 演示

观看演示视频，了解MCP搜索服务器的运行情况：

🎬 在YouTube上观看演示

🌟 特性

智能MCP发现：根据您的具体要求搜索MCP服务器
智能分析：自动分析搜索结果并对其进行MCP相关性排名
详细信息：获取有关特定MCP服务器的全面详细信息
类似的MCP：查找与您已知的类似的MCP服务器
类别式组织：按职能类别组织的MCP
直接问答：询问有关MCP服务器的具体问题并获得直接答案
多种搜索模式：支持广泛搜索和以GitHub为中心的搜索

🏗️ 建筑

服务器由几个关键组件组成：

核心组件

ExaSearchClient：处理与Exa的搜索、回答和查找类似API的交互
MCP分析仪：智能分析引擎：
- 从搜索结果中识别MCP相关内容
- 基于多个因素计算置信度得分
- 提取结构化信息（特征、类别等）
- 筛选和排名建议
MCP建议：表示发现的MCP的数据结构，其中：
- 名称、描述和URL
- 存储库信息
- 置信度得分
- 主要特征和类别
- 安装说明

可用工具

工具	描述	用例
`search_mcps`	根据需求搜索MCP	“我需要一个MCP来访问数据库”
`get_mcp_details`	获取特定MCP的详细信息	分析特定GitHub仓库
`find_similar_mcps`	查找与参考类似的MCP	查找已知MCP的替代品
`ask_mcp_question`	询问有关MCP的具体问题	“用于网络抓取的最佳MCP是什么？”
`categorize_mcps`	按类别组织MCP	按职能领域探索MCP

🚀 快速开始

先决条件

Python 3.10+
Exa API密钥 -从以下位置获取一个 Exa仪表板

安装

克隆和设置：

git clone <this-repo>
cd mcp-search-server
pip install -r requirements.txt

设置Exa API密钥：
```
export EXA_API_KEY=your_api_key_here
```
运行服务器：
```
python mcp_search_server.py
```

使用FastMCP CLI进行测试

# Test the server interactively
fastmcp dev mcp_search_server.py

# Or inspect with web UI
fastmcp inspect mcp_search_server.py

📦 安装指南

本指南涵盖了在不同操作系统上安装和设置MCP Search Server。

📋 先决条件

必修的：

Python 3.10或更高版本
Exa API密钥 （从 Exa仪表板)
Internet连接 搜索功能

可选：

Git 用于克隆存储库
FastMCP命令行界面 用于测试和开发

🐍 Python安装

视窗

选项1:微软商店（推荐）

打开Microsoft应用商店
搜索“Python 3.11”或“Python 3.12”
点击“获取”进行安装
验证安装： python --version

选项2:Python.org

访问 python.org/下载
下载适用于Windows的最新Python 3.10+
在选中“添加到PATH”的情况下运行安装程序
验证： python --version

选项3：巧克力

# Install Chocolatey first (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Python
choco install python

macOS

选项1：自制（推荐）

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.11

选项2:Python.org

访问 python.org/下载
下载适用于macOS的最新Python 3.10+
运行安装程序
验证： python3 --version

Linux（Ubuntu/Debian）

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-pip python3.11-venv

# Verify installation
python3.11 --version

Linux（CentOS/RHEL/Fedora）

# Fedora
sudo dnf install python311 python311-pip

# CentOS/RHEL (with EPEL)
sudo yum install python311 python311-pip

🚀 MCP搜索服务器安装

方法1：直接下载和设置

下载文件：

# Create project directory
mkdir mcp-search-server
cd mcp-search-server

# Download files (or copy from this project)
# - mcp_search_server.py
# - requirements.txt
# - README.md
# - test_mcp_search.py

安装依赖项：

# Using pip
pip install -r requirements.txt

# Or install manually
pip install fastmcp>=2.0.0 httpx>=0.25.0

设置环境：

# Linux/Mac
export EXA_API_KEY=your_exa_api_key_here

# Windows Command Prompt
set EXA_API_KEY=your_exa_api_key_here

# Windows PowerShell
$env:EXA_API_KEY="your_exa_api_key_here"

方法2：使用虚拟环境（推荐）

创建虚拟环境：

# Create virtual environment
python -m venv mcp-search-env

# Activate it
# Linux/Mac:
source mcp-search-env/bin/activate

# Windows:
mcp-search-env\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```
运行服务器：
```
python mcp_search_server.py
```

🔑 Exa API密钥设置

1.获取API密钥

访问 Exa仪表板
注册或登录
导航到API密钥部分
创建新的API密钥
复制密钥（以开头 exa_)

2.设置环境变量

临时（当前会议）

# Linux/Mac
export EXA_API_KEY=exa_your_key_here

# Windows Command Prompt
set EXA_API_KEY=exa_your_key_here

# Windows PowerShell
$env:EXA_API_KEY="exa_your_key_here"

永久设置

Linux/Mac（~/.bashrc或~/.zshrc）：

echo 'export EXA_API_KEY=exa_your_key_here' >> ~/.bashrc
source ~/.bashrc

Windows（系统环境变量）：

打开控制面板中的“环境变量”
添加新的用户变量：
- 姓名： EXA_API_KEY
- 价值： exa_your_key_here
重新启动终端/应用程序

✅ 验证与测试

1.基本安装测试

# Test Python installation
python --version

# Test package imports
python -c "import fastmcp, httpx; print('Dependencies OK')"

2.API关键测试

# Test environment variable
python -c "import os; print('API Key:', 'Set' if os.getenv('EXA_API_KEY') else 'Not Set')"

3.服务器测试

# Run test script
python test_mcp_search.py

# Or run server directly
python mcp_search_server.py

📚 使用指南

本指南将引导您设置和使用MCP搜索服务器，为您的项目发现和研究MCP服务器。

🛠️ 集成方法

方法1：克劳德桌面集成

找到Claude Desktop配置文件：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json

添加服务器配置：

{
  "mcpServers": {
    "mcp-search": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_search_server.py"],
      "env": {
        "EXA_API_KEY": "your_exa_api_key_here"
      }
    }
  }
}

重新启动克劳德桌面
克劳德测试：
- 类型：“搜索数据库MCP服务器”
- Claude现在应该能够使用MCP搜索工具了

方法2：光标集成

打开光标设置
导航到MCP配置

添加MCP搜索服务器：

{
  "command": "python",
  "args": ["/path/to/mcp_search_server.py"],
  "env": {
    "EXA_API_KEY": "your_api_key"
  }
}

方法3：命令行测试

# Interactive testing with FastMCP CLI
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

方法4：程序化使用

import asyncio
import json
from fastmcp import Client

async def search_for_mcps():
    async with Client("mcp_search_server.py") as client:
        # Search for MCPs
        result = await client.call_tool("search_mcps", {
            "requirement": "database access",
            "max_results": 5
        })
        
        data = json.loads(result.text)
        print(f"Found {data['total_found']} MCPs")
        
        for rec in data['recommendations']:
            print(f"- {rec['name']}: {rec['description']}")

# Run the search
asyncio.run(search_for_mcps())

🎯 常见用例

用例1：为特定任务查找MCP

目标： 查找数据库操作的MCP

步骤：

使用 search_mcps 工具
提供要求：“数据库访问和SQL操作”
审查信心评分和类别
获取详细信息 get_mcp_details

交互示例：

User: "I need an MCP for SQLite database access"
Tool: search_mcps(requirement="SQLite database access", max_results=5)
Result: List of SQLite-related MCPs with confidence scores

用例2：探索MCP类别

目标： 了解不同地区可用的MCP

步骤：

使用 categorize_mcps 工具
提供“文件管理”等广泛要求
探索返回的不同类别
深入到特定类别

交互示例：

User: "What file management MCPs are available?"
Tool: categorize_mcps(requirement="file management")
Result: MCPs grouped by categories (File System, Cloud Storage, etc.)

用例3：研究与比较

目标： 比较类似的MCP

步骤：

找到初始MCP search_mcps
使用 find_similar_mcps 寻找替代方案
使用 get_mcp_details 进行详细比较
向以下人员提出具体问题 ask_mcp_question

交互示例：

User: "Find alternatives to the FastMCP file server"
Tool: find_similar_mcps(reference_mcp_url="https://github.com/example/fastmcp-file")
Result: List of similar MCPs with comparison data

用例4：一般问题

目标： 获取有关MCP的专家答案

步骤：

使用 ask_mcp_question 工具
询问有关MCP生态系统的具体问题
通过引用获得答案
跟进更具体的搜索

交互示例：

User: "What are the most popular MCPs for web scraping?"
Tool: ask_mcp_question(question="most popular MCPs for web scraping")
Result: Direct answer with citations and source links

📋 可用工具参考

1. `search_mcps`

目的： 根据需求搜索MCP

参数：

requirement （string）：您需要什么（例如，“数据库访问”）
max_results （int，默认值=10）：结果数
include_github_only （bool，默认值=false）：仅限于GitHub存储库

退货： 带有MCP建议、置信度评分和类别的JSON

2. `get_mcp_details`

目的： 获取特定MCP的详细信息

参数：

mcp_url （string）:MCP存储库或文档的URL

退货： 详细的MCP信息，包括类似的MCP

3. `find_similar_mcps`

目的： 查找与参考MCP类似的MCP

参数：

reference_mcp_url （string）：引用MCP的URL
max_results （int，默认值=5）：相似MCP的数量

退货： 具有比较数据的类似MCP列表

4. `ask_mcp_question`

目的： 询问有关MCP的具体问题

参数：

question （string）：您关于MCP服务器的问题

退货： 直接回答引用和来源

5. `categorize_mcps`

目的： 按类别组织MCP

参数：

requirement （string）：对MCP进行分类的要求

退货： 按功能类别分组的MCP

🔍 了解结果

置信度得分

0.8-1.0: 高度相关，绝对是MCP
0.6-0.8: 可能相关，可能是MCP
0.4-0.6: 可能相关，可能相关
0.2-0.4: 相关性低，值得检查
0.0-0.2: 相关性最低

主要特点

自动提取的功能：

数据库操作
API集成
文件管理
网络抓取
交流工具
开发公用事业

🔧 配置

环境变量

EXA_API_KEY （必需）：您的Exa AI API密钥

服务器配置

服务器可以使用不同的传输方式运行：

# STDIO (default) - for local use
mcp.run()

# HTTP Streaming - for web deployment
mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

# SSE - for compatibility
mcp.run(transport="sse", host="127.0.0.1", port=8000)

📊 api参考

刀具参数

`search_mcps`

requirement （str）：描述你需要什么
max_results （int，默认值=10）：要返回的结果数
include_github_only （bool，默认值=False）：仅限于GitHub存储库

`get_mcp_details`

mcp_url （str）:MCP服务器或存储库的URL

`find_similar_mcps`

reference_mcp_url （str）：引用MCP的URL
max_results （int，默认值=5）：要查找的相似MCP的数量

`ask_mcp_question`

question （str）：您关于MCP服务器的问题

`categorize_mcps`

requirement （str）：对MCP进行分类的要求

响应格式

所有工具都返回结构化JSON，其中包含：

清晰的数据组织
置信度评分（如适用）
丰富的元数据（类别、特征等）
处理描述性消息时出错

🛠️ 整合

使用克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-search": {
      "command": "python",
      "args": ["/path/to/mcp_search_server.py"],
      "env": {
        "EXA_API_KEY": "your_api_key_here"
      }
    }
  }
}

带光标

在MCP设置中进行配置，以在Cursor中启用MCP发现。

编程访问

from fastmcp import Client

async def main():
    async with Client("mcp_search_server.py") as client:
        result = await client.call_tool("search_mcps", {
            "requirement": "file management",
            "max_results": 5
        })
        print(result.text)

🚨 故障排除

常见问题

问题：“python：找不到命令”

解决：

安装Python（请参阅Python安装部分）
使用 python3 而不是 python
检查Python是否在PATH中

问题：“没有名为'fastmcp'的模块”

解决：

# Install missing dependencies
pip install fastmcp httpx

# Or reinstall from requirements
pip install -r requirements.txt

问题：“需要EXA_API_KEY环境变量”

解决：

设置环境变量（请参阅Exa API密钥设置）
检查变量是否已设置： echo $EXA_API_KEY （Linux/Mac）或 echo %EXA_API_KEY% （Windows）
设置环境变量后重新启动终端

问题：安装过程中出现权限错误

解决：

# Use --user flag
pip install --user -r requirements.txt

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate    # Windows
pip install -r requirements.txt

问题：“SSL证书验证失败”

解决：

# Upgrade certificates
pip install --upgrade certifi

# Or use --trusted-host (temporary fix)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org fastmcp

问题：“搜索MCP时出错：HTTP 401”

解决方案： 检查您的Exa API密钥是否有效且处于活动状态

问题：“未找到符合要求的MCP”

解决：

尝试更广泛的搜索词
使用不同的关键字
检查要求是否过于具体

问题：工具返回空结果

解决：

验证互联网连接
尝试不同的搜索词
检查Exa API状态

平台特定问题

Windows PowerShell执行策略

如果出现执行策略错误：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS权限问题

如果您遇到权限错误：

# Use Homebrew Python instead of system Python
brew install python@3.11
export PATH="/opt/homebrew/bin:$PATH"

Linux缺少开发标头

如果编译失败：

# Ubuntu/Debian
sudo apt install python3-dev build-essential

# CentOS/RHEL
sudo yum install python3-devel gcc

性能提示

使用特定要求 为了获得更好的结果
从更广泛的搜索开始 然后缩小范围
检查置信度得分 衡量相关性
仅使用GitHub搜索 获得更高质量的结果
尝试类别搜索 用于勘探

API限值

Exa API有基于您的计划的费率限制
服务器会自动遵守这些限制
考虑缓存频繁搜索词的结果
使用较小的 max_results 更快响应的值

🎓 最佳实践

1.搜索策略

从宽开始，然后缩小范围
使用特定领域的术语
尝试多种需求措辞
潜水前检查信心得分

2.结果评估

审查信心评分（建议>0.6）
检查存储库活动和星级
仔细阅读说明
验证安装要求

3.集成提示

在集成之前独立测试服务器
在配置中使用绝对路径
正确设置环境变量
监控错误日志以发现问题

4.工作流程优化

保存有用的MCP URL以供将来参考
使用分类进行发现
询问后续问题以澄清
选择前比较类似的MCP

🔍 运作原理

搜索智能

该系统使用多个信号来识别和排名MCP服务器：

内容分析：扫描MCP特定的关键字和指标
来源可信度：优先考虑GitHub存储库和官方文档
考试评分：利用Exa的语义理解
特征提取：自动识别关键功能
类别分类：按功能区对MCP进行分组

质量评分

每个MCP建议都包括一个基于以下因素的置信度评分：

MCP特定术语的存在
存储库质量指标
文件完整性
Exa的语义相关性得分

🧪 测试

在开发模式下运行服务器：

# Interactive testing
fastmcp dev mcp_search_server.py

# Web-based inspector
fastmcp inspect mcp_search_server.py

# Run test script
python test_mcp_search.py

🔒 安全与隐私

API密钥安全：需要Exa API密钥，但从未记录或公开
只读操作：服务器仅执行搜索操作，不进行任何修改
错误处理：优雅的降级，并显示信息丰富的错误消息
速率限制：遵守Exa API费率限制

🚦 局限性

需要Exa API密钥（付费服务）
搜索质量取决于Exa的索引覆盖率
考试成绩受考试费率限制
基于内容分析的MCP检测（可能有假阳性/阴性）

🎯 用例

对于开发者

发现工具：找到解决特定开发挑战的MCP
评估选项：比较同一用例的不同MCP
学习：了解生态系统中可用的MCP

AI助理

推荐引擎：向用户提供智能MCP建议
研究工具：帮助用户为他们的项目找到合适的工具
知识库：回答有关MCP生态系统的问题

对于团队

标准化：查找批准的MCP供团队使用
文档：保持对可用工具的了解
发现：随时了解新的MCP版本

🤝 贡献

欢迎投稿！需要改进的地方：

增强分析：更好的MCP检测算法
缓存：添加结果缓存以提高性能
过滤：其他过滤选项
出口：已找到的MCP的导出功能
监控：使用情况分析和性能监控

📞 获取帮助

内置帮助

访问帮助资源： mcp-search://help

错误消息

服务器提供详细的错误消息和故障排除提示

测试

使用测试脚本验证功能：

python test_mcp_search.py

支持资源

FastMCP文档：https://gofastmcp.com
Exa AI文档：https://docs.exa.ai
模型上下文协议：https://modelcontextprotocol.io

📄 许可证

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

🔗 链接

🆘 支持

查看内置帮助：使用 mcp-search://help 资源
查看错误消息以获取故障排除指导
确保 EXA_API_KEY 设置正确
验证Exa API的网络连接

内置于❤️ 使用FastMCP和Exa AI

MCP发现快乐！ 🚀

使用说明

MCP搜索服务器-综合文档🚀

🎥 演示

目录

🌟 特性

🏗️ 建筑

核心组件

可用工具

🚀 快速开始

先决条件

安装

使用FastMCP CLI进行测试

📦 安装指南

📋 先决条件

必修的：

可选：

🐍 Python安装

视窗

macOS

Linux（Ubuntu/Debian）

Linux（CentOS/RHEL/Fedora）

🚀 MCP搜索服务器安装

方法1：直接下载和设置

方法2：使用虚拟环境（推荐）

🔑 Exa API密钥设置

1.获取API密钥

2.设置环境变量

✅ 验证与测试

1.基本安装测试

2.API关键测试

3.服务器测试

📚 使用指南

🛠️ 集成方法

方法1：克劳德桌面集成

方法2：光标集成

方法3：命令行测试

方法4：程序化使用

🎯 常见用例

用例1：为特定任务查找MCP

用例2：探索MCP类别

用例3：研究与比较

用例4：一般问题

📋 可用工具参考

1. search_mcps

2. get_mcp_details

3. find_similar_mcps

4. ask_mcp_question

5. categorize_mcps

🔍 了解结果

置信度得分

分类

主要特点

🔧 配置

环境变量

服务器配置

📊 api参考

刀具参数

search_mcps

get_mcp_details

find_similar_mcps

ask_mcp_question

categorize_mcps

响应格式

🛠️ 整合

使用克劳德桌面

带光标

编程访问

🚨 故障排除

常见问题

问题：“python：找不到命令”

问题：“没有名为'fastmcp'的模块”

问题：“需要EXA_API_KEY环境变量”

问题：安装过程中出现权限错误

问题：“SSL证书验证失败”

问题：“搜索MCP时出错：HTTP 401”

问题：“未找到符合要求的MCP”

问题：工具返回空结果

平台特定问题

Windows PowerShell执行策略

macOS权限问题

1. `search_mcps`

2. `get_mcp_details`

3. `find_similar_mcps`

4. `ask_mcp_question`

5. `categorize_mcps`

`search_mcps`

`get_mcp_details`

`find_similar_mcps`

`ask_mcp_question`

`categorize_mcps`