感知工具 MCP 服务器

文档摘要

源文件：chapter4/perception-tools/README.md 感知工具 MCP 服务器一个功能完整的 MCP（Model Context Protocol）服务器，为 AI Agent 提供多种感知与数据获取能力。功能特性 ✨ 无需任何 API Key！大多数功能开箱即用，依赖的是免费的开放 API。 🔍 搜索工具网页搜索：DuckDuckGo 搜索（免费，无需 API key）知识库搜索：在本地文档集合中检索文件下载：从 URL 下载文件，并做安全检查 📄 多模态理解工具网页阅读器：从网页中提取文本与链接文档阅读器：从 PDF、DOCX、PPTX 文件中提取内容图片解析器：解析并分析图片文件视频解析器：从视频文件中提取元数据 📁 文件系统工具

源文件：chapter4/perception-tools/README.md

感知工具 MCP 服务器

一个功能完整的 MCP（Model Context Protocol）服务器，为 AI Agent 提供多种感知与数据获取能力。

功能特性

✨ 无需任何 API Key！ 大多数功能开箱即用，依赖的是免费的开放 API。

🔍 搜索工具

网页搜索：DuckDuckGo 搜索（免费，无需 API key）
知识库搜索：在本地文档集合中检索
文件下载：从 URL 下载文件，并做安全检查

📄 多模态理解工具

网页阅读器：从网页中提取文本与链接
文档阅读器：从 PDF、DOCX、PPTX 文件中提取内容
图片解析器：解析并分析图片文件
视频解析器：从视频文件中提取元数据

📁 文件系统工具

文件阅读器：读取文件，支持指定编码
Grep 搜索：在文件中按模式检索（支持正则）
文本摘要：对长文本内容进行摘要

🌐 公开数据源

天气：通过 Open-Meteo 获取当前天气（免费，无需 API key）
股价：来自 Yahoo Finance 的实时股票数据（免费，无需 API key）
加密货币价格：通过 CoinGecko 获取（免费，无需 API key）
货币换算：在不同货币间换算（免费，无需 API key）
地点搜索：通过 Nominatim (OpenStreetMap) 进行地理编码（免费，无需 API key）
POI 搜索：通过 Overpass API (OpenStreetMap) 查询兴趣点（免费，无需 API key）
维基百科：检索并获取维基百科条目（免费，无需 API key）
ArXiv：在 ArXiv 上检索学术论文（免费，无需 API key）
Wayback Machine：访问已归档的网页（免费，无需 API key）

🔐 私有数据源

Google 日历：查询日历事件
Notion：在 Notion 工作区中检索

安装


cd projects/week3/perception-tools

安装依赖：


pip install -r requirements.txt

无需额外配置！ 服务器开箱即用，全部基于免费 API。

配置

✅ 默认免费 API（无需任何设置）

以下功能无需任何 API key 即可立即使用：

网页搜索：DuckDuckGo
天气：Open-Meteo
股价：Yahoo Finance
加密货币价格：CoinGecko
货币换算：ExchangeRate-API
地点搜索：Nominatim (OpenStreetMap)
POI 搜索：Overpass API (OpenStreetMap)
维基百科：Wikipedia API
ArXiv：ArXiv API
Wayback Machine：Internet Archive

可选的私有数据集成

Google 日历

如需集成 Google 日历，需要配置 OAuth2：


pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

按 Google Calendar API quickstart 设置 OAuth2 凭据。

Notion

在 notion.so/my-integrations 创建一个 Notion 集成
获取你的集成 token
把你的数据库/页面共享给该集成
在 .env 中添加 NOTION_API_KEY


pip install notion-client

用法

运行 MCP 服务器


cd src
python main.py

服务器以 stdio 传输运行，适合与 MCP 客户端集成。

命令行界面（`cli.py`）

除了以 MCP stdio 协议对外服务，仓库根目录提供了一个统一的命令行入口
cli.py，无需 MCP 客户端即可直接列出、查看、调用和演示各类感知工具。
工具按第四章「感知工具」的五类场景组织：搜索 / 多模态理解 / 文件系统 /
公开数据源 / 私有数据源（当前共 53 个工具）。


# 查看帮助（中文）
python cli.py --help

# 按五类列出全部感知工具（可用 --category 只看某一类）
python cli.py list
python cli.py list --category filesystem

# 查看某个工具的参数签名与调用示例
python cli.py info weather

# 直接调用某个工具，参数以 key=value 形式传入，结果为标准 ActionResponse JSON
python cli.py run grep 'pattern=async def' directory=src 'file_pattern=*.py'
python cli.py run currency_converter amount=100 from_currency=USD to_currency=CNY

# 运行端到端演示：串联「本地资料 + 外部信息」的研究助手 Agent 感知流程
python cli.py demo            # 完整演示（含联网步骤）
python cli.py demo --offline  # 离线演示（只跑文件系统 / 本地知识库等不联网步骤）

说明：

每个工具都是异步函数，返回统一的 ActionResponse（JSON）；CLI 负责运行事件
循环、解析 JSON 并友好打印。
工具按需惰性导入：list / info / 离线 demo 在缺少可选依赖（如 whisper、
waybackpy）时仍可正常工作，只有真正调用相关工具时才导入对应模块。
需要联网的工具在 list 中标注「联网」，需要授权/API Key 的工具标注了对应说明。

配合 MCP 客户端使用

配置你的 MCP 客户端（例如 Claude Desktop）连接本服务器：


{
  "mcpServers": {
    "perception-tools": {
      "command": "python",
      "args": ["/path/to/perception-tools/src/main.py"]
    }
  }
}

可用工具

搜索工具

`web_search`

使用 DuckDuckGo 进行网页搜索（免费，无需 API key）。

参数：

query (str)：搜索查询字符串
num_results (int, 默认=5)：返回结果数（1-10）
region (str, 默认="wt-wt")：地区代码（例如 "us-en"、"uk-en"，"wt-wt" 表示全球）

`download`

从 URL 下载文件。

参数：

url (str)：要下载的 URL
output_path (str)：本地保存路径
overwrite (bool, 默认=False)：是否覆盖已有文件
timeout (int, 默认=180)：下载超时（秒）

`knowledge_base_search`

在本地知识库目录中检索。

参数：

query (str)：检索查询
knowledge_base_path (str)：知识库目录路径
top_k (int, 默认=5)：返回前 k 个结果

多模态理解工具

`webpage_reader`

读取并提取网页内容。

参数：

url (str)：网页 URL
extract_text (bool, 默认=True)：是否提取文本
extract_links (bool, 默认=False)：是否提取链接

`document_reader`

读取并从文档（PDF、DOCX、PPTX）中提取内容。

参数：

file_path (str)：文档文件路径或 URL
extract_images (bool, 默认=False)：是否提取图片

`image_parser`

解析并分析图片文件。

参数：

image_path (str)：图片文件路径或 URL
use_llm (bool, 默认=True)：是否用 LLM 进行分析

视觉 LLM key / OpenRouter 回退：AI 图片/视频分析
（analyze_image_ai / analyze_video_ai）在设置了 OPENAI_API_KEY 时使用它。
若未设置但设置了 OPENROUTER_API_KEY，会透明地走 OpenRouter
（base_url=https://openrouter.ai/api/v1，模型映射为 provider/model 形式）。
可通过 PERCEPTION_VISION_MODEL 覆盖模型。
（本地 Whisper 转写仍需 OPENAI_API_KEY —— OpenRouter 没有音频转写 API。）

`video_parser`

解析并从视频文件中提取元数据。

参数：

video_path (str)：视频文件路径或 URL
extract_frames (bool, 默认=False)：是否抽取采样帧
frame_interval (int, 默认=30)：抽帧间隔

文件系统工具

`file_reader`

读取文件并返回其内容。

参数：

file_path (str)：文件路径
encoding (str, 默认="utf-8")：文件编码
max_length (int, 默认=50000)：最多读取的字符数

`grep`

在文件中按模式检索（类似 grep 的功能）。

参数：

pattern (str)：正则表达式模式
directory (str)：要检索的目录
file_pattern (str, 默认="*")：文件模式（例如 *.py）
recursive (bool, 默认=True)：是否递归检索
case_sensitive (bool, 默认=False)：是否区分大小写
max_results (int, 默认=100)：最大结果数

`text_summarizer`

对长文本内容进行摘要。

参数：

text (str)：要摘要的文本
max_length (int, 默认=500)：目标摘要长度
use_llm (bool, 默认=True)：是否用 LLM 进行摘要

公开数据源工具

`weather`

通过 Open-Meteo API 获取当前天气信息（免费，无需 API key）。

参数：

location (str)：城市名（会自动进行地理编码）
latitude (float, 可选)：纬度坐标
longitude (float, 可选)：经度坐标

`stock_price`

通过 Yahoo Finance 获取股价与市场信息（免费，无需 API key）。

参数：

symbol (str)：股票代码（例如 AAPL、TSLA、GOOGL）
interval (str, 默认="1d")：数据时间间隔

`crypto_price`

通过 CoinGecko API 获取加密货币价格信息（免费，无需 API key）。

参数：

symbol (str)：加密货币代码或 id（例如 bitcoin、ethereum、btc、eth）
vs_currency (str, 默认="usd")：目标货币（usd、eur、gbp 等）

`currency_converter`

在不同货币间换算。

参数：

amount (float)：要换算的金额
from_currency (str)：源货币代码（例如 USD）
to_currency (str)：目标货币代码（例如 EUR）

`wikipedia_search`

检索维基百科并获取条目摘要。

参数：

query (str)：检索查询
language (str, 默认="en")：维基百科语言
sentences (int, 默认=5)：摘要句子数

`arxiv_search`

在 ArXiv 上检索学术论文。

参数：

query (str)：检索查询
max_results (int, 默认=5)：最大结果数
sort_by (str, 默认="relevance")：排序方式

`wayback_search`

在 Wayback Machine 中检索已归档的网页。

参数：

url (str)：要检索的 URL
year (int, 可选)：按年份过滤
limit (int, 默认=10)：最大快照数

`location_search`

通过 Nominatim (OpenStreetMap) API 搜索地点（免费，无需 API key）。

参数：

query (str)：地点查询（例如 "Eiffel Tower"、"New York"、"Tokyo"）
limit (int, 默认=5)：最大结果数（1-50）
country_code (str, 可选)：国家代码过滤（例如 "us"、"gb"、"fr"）

`poi_search`

通过 Overpass API 搜索某地点附近的兴趣点（免费，无需 API key）。

参数：

query (str)：兴趣点类型（例如 "restaurant"、"cafe"、"hospital"、"atm"、"hotel"）
latitude (float)：中心纬度坐标
longitude (float)：中心经度坐标
radius (int, 默认=1000)：检索半径（米）
limit (int, 默认=10)：最大结果数

私有数据源工具

`calendar_events`

从 Google 日历获取事件。

参数：

start_date (str, 可选)：起始日期（ISO 格式）
end_date (str, 可选)：结束日期（ISO 格式）
calendar_id (str, 默认="primary")：日历 ID
max_results (int, 默认=10)：最大事件数

`notion_search`

在 Notion 工作区中检索。

参数：

query (str)：检索查询
database_id (str, 可选)：指定数据库 ID
page_size (int, 默认=10)：每页结果数

架构

本项目遵循 SOLID 原则，采用模块化架构：


perception-tools/
├── src/
│   ├── main.py                  # MCP server entry point
│   ├── base.py                  # Base models and utilities
│   ├── search_tools.py          # Search functionality
│   ├── multimodal_tools.py      # Document/media processing
│   ├── filesystem_tools.py      # File operations
│   ├── public_data_tools.py     # Public APIs
│   └── private_data_tools.py    # Private data sources
├── requirements.txt             # Python dependencies
├── env.example                  # Environment variables template
└── README.md                    # This file

错误处理

所有工具都返回标准化的 ActionResponse 格式：


{
  "success": true/false,
  "message": "Result data or error message",
  "metadata": {
    "additional": "context information"
  }
}

参与贡献

欢迎贡献！请确保：

代码遵循 KISS、DRY、SOLID 原则
所有工具都返回标准化的 ActionResponse 格式
做好错误处理与日志记录
为新增工具补充文档

许可证

本项目是 AI Agent 训练营教学资料的一部分。

支持

如有问题，请参阅主项目的文档。

作者与出处

原作者： bojieli

来源：bojieli

原文： https://github.com/bojieli/ai-agent-book

许可证：Apache-2.0

整理：灏天文库整理

由灏天文库结构化整理，提供目录导航、全文检索与在线阅读，便于系统化学习

感知工具 MCP 服务器

文档摘要