ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter4/perception-tools/TOOL_REFERENCE.md

@@ -0,0 +1,640 @@
+# Tool Reference Guide
+
+Complete reference for all 22 perception tools available in this MCP server.
+
+## Table of Contents
+
+- [Search Tools (3)](#search-tools)
+- [Multimodal Understanding Tools (4)](#multimodal-understanding-tools)
+- [File System Tools (3)](#file-system-tools)
+- [Public Data Source Tools (6)](#public-data-source-tools)
+- [Private Data Source Tools (2)](#private-data-source-tools)
+
+---
+
+## Search Tools
+
+### 1. web_search
+
+Search the web using Google Custom Search API.
+
+**Parameters:**
+- `query` (string, required): Search query string
+- `num_results` (int, default: 5): Number of results to return (1-10)
+- `language` (string, default: "en"): Language code (en, zh, es, etc.)
+- `country` (string, default: "us"): Country code (us, cn, uk, etc.)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "query": "Python programming",
+    "results": [
+      {
+        "id": "google-0",
+        "title": "Python.org",
+        "url": "https://www.python.org",
+        "snippet": "Official Python website...",
+        "source": "google"
+      }
+    ],
+    "count": 5
+  },
+  "metadata": {
+    "query": "Python programming",
+    "search_engine": "google",
+    "total_results": 5,
+    "search_time": 0.45
+  }
+}
+```
+
+**Requirements:** Google API Key, Google CSE ID
+
+---
+
+### 2. download
+
+Download a file from a URL to local storage.
+
+**Parameters:**
+- `url` (string, required): HTTP/HTTPS URL to download from
+- `output_path` (string, required): Local path to save the file
+- `overwrite` (bool, default: false): Whether to overwrite existing files
+- `timeout` (int, default: 180): Download timeout in seconds
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": "Successfully downloaded file to /path/to/file.pdf",
+  "metadata": {
+    "url": "https://example.com/file.pdf",
+    "output_path": "/path/to/file.pdf",
+    "file_size_bytes": 1048576,
+    "duration_seconds": 2.3
+  }
+}
+```
+
+**Limits:** Maximum 100MB file size by default
+
+---
+
+### 3. knowledge_base_search
+
+Search a local knowledge base directory for relevant documents.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `knowledge_base_path` (string, required): Path to knowledge base directory
+- `top_k` (int, default: 5): Number of top results to return
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "query": "machine learning",
+    "results": [
+      {
+        "file": "docs/ml_basics.md",
+        "snippet": "...machine learning algorithms...",
+        "relevance": 12
+      }
+    ],
+    "total_found": 3
+  },
+  "metadata": {
+    "knowledge_base": "/path/to/kb",
+    "top_k": 5
+  }
+}
+```
+
+**Supported file types:** .txt, .md, .json
+
+---
+
+## Multimodal Understanding Tools
+
+### 4. webpage_reader
+
+Extract content from web pages including text and links.
+
+**Parameters:**
+- `url` (string, required): URL of the webpage
+- `extract_text` (bool, default: true): Whether to extract main text content
+- `extract_links` (bool, default: false): Whether to extract all links
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "url": "https://example.com",
+    "title": "Example Page",
+    "text": "Page content...",
+    "text_length": 5000,
+    "links": []
+  },
+  "metadata": {
+    "url": "https://example.com"
+  }
+}
+```
+
+---
+
+### 5. document_reader
+
+Extract content from documents (PDF, DOCX, PPTX).
+
+**Parameters:**
+- `file_path` (string, required): Path to document file or URL
+- `extract_images` (bool, default: false): Whether to extract images
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "file_name": "document.pdf",
+    "file_type": "pdf",
+    "page_count": 10,
+    "text": "Document content...",
+    "text_length": 15000
+  },
+  "metadata": {
+    "file_path": "/path/to/document.pdf",
+    "file_type": ".pdf"
+  }
+}
+```
+
+**Supported formats:** PDF, DOCX, PPTX
+
+---
+
+### 6. image_parser
+
+Parse and analyze image files.
+
+**Parameters:**
+- `image_path` (string, required): Path to image file or URL
+- `use_llm` (bool, default: true): Use LLM for image understanding
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "file_name": "image.jpg",
+    "format": "JPEG",
+    "mode": "RGB",
+    "size": [1920, 1080],
+    "width": 1920,
+    "height": 1080,
+    "note": "Full base64 data available for vision API analysis"
+  },
+  "metadata": {
+    "file_path": "/path/to/image.jpg"
+  }
+}
+```
+
+**Supported formats:** JPG, PNG, GIF, BMP, TIFF, WEBP
+
+---
+
+### 7. video_parser
+
+Extract metadata and information from video files.
+
+**Parameters:**
+- `video_path` (string, required): Path to video file or URL
+- `extract_frames` (bool, default: false): Extract sample frames
+- `frame_interval` (int, default: 30): Extract one frame every N seconds
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "file_name": "video.mp4",
+    "duration_seconds": 120.5,
+    "fps": 30.0,
+    "frame_count": 3615,
+    "resolution": "1920x1080",
+    "width": 1920,
+    "height": 1080
+  },
+  "metadata": {
+    "file_path": "/path/to/video.mp4"
+  }
+}
+```
+
+**Supported formats:** MP4, AVI, MOV, MKV, WEBM
+
+---
+
+## File System Tools
+
+### 8. file_reader
+
+Read a file and return its contents.
+
+**Parameters:**
+- `file_path` (string, required): Path to the file
+- `encoding` (string, default: "utf-8"): File encoding
+- `max_length` (int, default: 50000): Maximum characters to read
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "file_path": "/path/to/file.txt",
+    "content": "File contents...",
+    "size_bytes": 1024,
+    "truncated": false,
+    "encoding": "utf-8"
+  },
+  "metadata": {
+    "file_path": "/path/to/file.txt"
+  }
+}
+```
+
+---
+
+### 9. grep
+
+Search for patterns in files using regular expressions.
+
+**Parameters:**
+- `pattern` (string, required): Regular expression pattern to search for
+- `directory` (string, required): Directory to search in
+- `file_pattern` (string, default: "*"): File pattern to match (e.g., "*.py")
+- `recursive` (bool, default: true): Search recursively
+- `case_sensitive` (bool, default: false): Case-sensitive search
+- `max_results` (int, default: 100): Maximum number of results
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "pattern": "def.*:",
+    "results": [
+      {
+        "file": "src/main.py",
+        "line_number": 42,
+        "line": "def my_function():",
+        "absolute_path": "/full/path/to/src/main.py"
+      }
+    ],
+    "total_found": 15,
+    "truncated": false
+  },
+  "metadata": {
+    "directory": "/path/to/search",
+    "file_pattern": "*.py",
+    "recursive": true
+  }
+}
+```
+
+---
+
+### 10. text_summarizer
+
+Summarize long text content.
+
+**Parameters:**
+- `text` (string, required): Text to summarize
+- `max_length` (int, default: 500): Target summary length in characters
+- `use_llm` (bool, default: true): Use LLM for better summarization
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "original_length": 5000,
+    "summary_length": 500,
+    "summary": "Summary text...",
+    "method": "extractive",
+    "compression_ratio": 0.1
+  },
+  "metadata": {
+    "method": "extractive"
+  }
+}
+```
+
+---
+
+## Public Data Source Tools
+
+### 11. weather
+
+Get current weather information for a location.
+
+**Parameters:**
+- `location` (string, required): City name, coordinates, or zip code
+- `units` (string, default: "metric"): Temperature units (metric/imperial/standard)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "location": "London",
+    "country": "GB",
+    "temperature": 15.5,
+    "feels_like": 14.2,
+    "humidity": 72,
+    "pressure": 1013,
+    "weather": "Clouds",
+    "description": "overcast clouds",
+    "wind_speed": 5.2,
+    "units": "metric"
+  },
+  "metadata": {
+    "location": "London",
+    "units": "metric"
+  }
+}
+```
+
+**Requirements:** OpenWeather API key
+
+---
+
+### 12. stock_price
+
+Get current stock price and market information.
+
+**Parameters:**
+- `symbol` (string, required): Stock ticker symbol (e.g., "AAPL", "TSLA")
+- `interval` (string, default: "1d"): Data interval
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "symbol": "AAPL",
+    "currency": "USD",
+    "current_price": 175.43,
+    "previous_close": 174.20,
+    "open": 174.50,
+    "day_high": 176.00,
+    "day_low": 173.80,
+    "volume": 52341000,
+    "exchange": "NASDAQ"
+  },
+  "metadata": {
+    "symbol": "AAPL"
+  }
+}
+```
+
+**Source:** Yahoo Finance (no API key required)
+
+---
+
+### 13. currency_converter
+
+Convert between different currencies.
+
+**Parameters:**
+- `amount` (float, required): Amount to convert
+- `from_currency` (string, required): Source currency code (e.g., "USD")
+- `to_currency` (string, required): Target currency code (e.g., "EUR")
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "amount": 100.0,
+    "from_currency": "USD",
+    "to_currency": "EUR",
+    "exchange_rate": 0.92,
+    "converted_amount": 92.0,
+    "timestamp": "2024-01-15"
+  },
+  "metadata": {
+    "rate": 0.92
+  }
+}
+```
+
+**Source:** Exchange Rate API (no API key required)
+
+---
+
+### 14. wikipedia_search
+
+Search Wikipedia and retrieve article summaries.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `language` (string, default: "en"): Wikipedia language (en, zh, es, etc.)
+- `sentences` (int, default: 5): Number of sentences in summary
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "title": "Artificial Intelligence",
+    "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
+    "summary": "Artificial intelligence (AI) is...",
+    "language": "en",
+    "search_results": ["Artificial Intelligence", "AI", "Machine Learning"]
+  },
+  "metadata": {
+    "query": "artificial intelligence",
+    "language": "en"
+  }
+}
+```
+
+---
+
+### 15. arxiv_search
+
+Search ArXiv for academic papers.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `max_results` (int, default: 5): Maximum number of papers
+- `sort_by` (string, default: "relevance"): Sort method (relevance/lastUpdatedDate/submittedDate)
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "query": "machine learning",
+    "papers": [
+      {
+        "title": "Deep Learning Paper",
+        "authors": ["John Doe", "Jane Smith"],
+        "summary": "Paper summary...",
+        "published": "2024-01-15T00:00:00",
+        "url": "https://arxiv.org/abs/2401.12345",
+        "pdf_url": "https://arxiv.org/pdf/2401.12345",
+        "categories": ["cs.LG", "cs.AI"]
+      }
+    ],
+    "count": 5
+  },
+  "metadata": {
+    "query": "machine learning",
+    "max_results": 5
+  }
+}
+```
+
+---
+
+### 16. wayback_search
+
+Search Wayback Machine for archived versions of web pages.
+
+**Parameters:**
+- `url` (string, required): URL to search for
+- `year` (int, optional): Filter results by specific year
+- `limit` (int, default: 10): Maximum number of snapshots
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "url": "https://example.com",
+    "snapshots": [
+      {
+        "timestamp": "2024-01-15T10:30:00",
+        "url": "https://web.archive.org/web/20240115103000/https://example.com",
+        "status_code": "200",
+        "mime_type": "text/html"
+      }
+    ],
+    "count": 10
+  },
+  "metadata": {
+    "url": "https://example.com",
+    "year": null
+  }
+}
+```
+
+---
+
+## Private Data Source Tools
+
+### 17. calendar_events
+
+Get events from Google Calendar.
+
+**Parameters:**
+- `start_date` (string, optional): Start date in ISO format (defaults to today)
+- `end_date` (string, optional): End date in ISO format (defaults to 7 days from now)
+- `calendar_id` (string, default: "primary"): Calendar ID
+- `max_results` (int, default: 10): Maximum number of events
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "events": [
+      {
+        "id": "event_id_123",
+        "summary": "Team Meeting",
+        "start": "2024-01-15T10:00:00Z",
+        "end": "2024-01-15T11:00:00Z",
+        "location": "Conference Room A",
+        "description": "Weekly team sync",
+        "attendees": ["john@example.com", "jane@example.com"]
+      }
+    ],
+    "count": 5,
+    "calendar_id": "primary"
+  },
+  "metadata": {
+    "start_date": "2024-01-15T00:00:00Z",
+    "end_date": "2024-01-22T00:00:00Z"
+  }
+}
+```
+
+**Requirements:** Google Calendar API OAuth2 authentication
+
+---
+
+### 18. notion_search
+
+Search Notion workspace or specific database.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `database_id` (string, optional): Specific database ID to search
+- `page_size` (int, default: 10): Results per page
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": {
+    "query": "project notes",
+    "results": [
+      {
+        "id": "page_id_123",
+        "type": "page",
+        "url": "https://notion.so/page_id_123",
+        "title": "Project Planning",
+        "created_time": "2024-01-15T10:00:00Z",
+        "last_edited_time": "2024-01-16T14:30:00Z"
+      }
+    ],
+    "count": 3
+  },
+  "metadata": {
+    "database_id": null
+  }
+}
+```
+
+**Requirements:** Notion API key
+
+---
+
+## Error Response Format
+
+All tools return errors in a standardized format:
+
+```json
+{
+  "success": false,
+  "message": "Error description here",
+  "metadata": {
+    "error_type": "specific_error_type"
+  }
+}
+```
+
+Common error types:
+- `missing_credentials`: API keys not configured
+- `api_request_failed`: External API request failed
+- `file_not_found`: Specified file doesn't exist
+- `invalid_parameters`: Invalid input parameters
+- `timeout`: Operation timed out
+- `permission_denied`: Insufficient permissions