@tinkcarlos/skillora 0.2.0

package/.claude/skills/skill-expert-skills/references/mcp-tools-guide.md

@@ -0,0 +1,439 @@
+# MCP 工具详细指南 (MCP Tools Guide)
+
+> 最后更新: 2025-01-17
+> 用途: 提供 MCP 工具的详细使用指南和最佳实践
+> 适用场景: 使用 MCP 工具获取最新知识、代码上下文等
+
+---
+
+## 目录
+
+1. [MCP 工具概述](#1-mcp-工具概述)
+2. [常用 MCP 工具](#2-常用-mcp-工具)
+3. [使用模式](#3-使用模式)
+4. [错误处理](#4-错误处理)
+5. [性能优化](#5-性能优化)
+6. [回退策略](#6-回退策略)
+7. [最佳实践](#7-最佳实践)
+
+---
+
+## 1. MCP 工具概述
+
+### 1.1 什么是 MCP
+
+**MCP (Model Context Protocol)** = Claude 与外部工具之间的标准协议。
+
+### 1.2 MCP 的价值
+
+| 优势 | 说明 |
+|------|------|
+| **最新知识** | 实时获取最新文档和代码示例 |
+| **代码上下文** | 直接访问开源项目的完整代码库 |
+| **深度搜索** | Exa 搜索引擎，比通用搜索更精准 |
+| **结构化输出** | 标准化的输出格式，便于解析 |
+
+---
+
+## 2. 常用 MCP 工具
+
+### 2.1 Context7 (文档查询工具)
+
+**功能**：查询库和框架的最新文档
+
+```bash
+# 查询库文档
+mcp__context7__query-docs \
+  --query "React useEffect dependency array best practices" \
+  --library "react"
+
+# 获取库信息
+mcp__context7__get-library-info \
+  --library "python-fastapi"
+```
+
+**使用场景**：
+- 查询框架的最新 API 用法
+- 获取官方文档中的最佳实践
+- 了解库的版本更新和 Breaking Changes
+
+**最佳实践**：
+- 使用具体的技术关键词
+- 指定库名而不是通用搜索
+- 结合 "best practices" 或 "examples" 获取实际代码
+
+### 2.2 Exa (深度搜索工具)
+
+**功能**：深度搜索技术博客、文档、教程
+
+```bash
+# 深度搜索
+mcp__exa__web_search_exa \
+  --query "Microservices saga pattern Python implementation" \
+  --numResults 10
+
+# 获取代码上下文
+mcp__exa__get_code_context_exa \
+  --query "Python async context manager pattern" \
+  --language "python"
+```
+
+**使用场景**：
+- 搜索特定技术模式的实现
+- 查找权威博客和技术文章
+- 获取代码片段和示例
+
+**最佳实践**：
+- 指定编程语言或框架
+- 使用 "production" 或 "best practices" 获取生产级代码
+- 结合 "examples" 或 "tutorial" 查找教学资源
+
+### 2.3 Deepwiki (GitHub 文档工具)
+
+**功能**：访问 GitHub 仓库的文档
+
+```bash
+# 获取仓库文档
+mcp__mcp-deepwiki__deepwiki_fetch \
+  --owner "anthropics" \
+  --repo "skills"
+
+# 查询文档
+mcp__mcp-deepwiki__query \
+  --query "deployment" \
+  --repo "anthropics/skills"
+```
+
+**使用场景**：
+- 查询开源项目的文档
+- 获取 README 和其他文档文件
+- 快速了解项目结构和功能
+
+**最佳实践**：
+- 使用官方仓库作为信息源
+- 结合版本号查询特定版本的文档
+- 对比多个仓库的实现方式
+
+### 2.4 WebSearch (通用搜索)
+
+**功能**：网络搜索最新信息
+
+```bash
+# 网络搜索
+WebSearch \
+  --query "Python 3.12 new features 2024" \
+  --numResults 8
+```
+
+**使用场景**：
+- 搜索最新版本更新
+- 查找技术新闻和趋势
+- 获取博客文章和讨论
+
+**最佳实践**：
+- 包含年份获取最新信息
+- 使用 "latest"、"new features"、"changelog" 等关键词
+- 结合官方文档验证信息准确性
+
+---
+
+## 3. 使用模式
+
+### 3.1 知识获取工作流
+
+```
+Step 1: 多源搜索
+    ├─ Context7: 查询官方文档
+    ├─ Exa: 搜索最佳实践博客
+    └─ Deepwiki: 查询开源项目
+         ↓
+Step 2: 交叉验证
+    ├─ 对比不同来源的信息
+    ├─ 识别一致点和矛盾点
+    └─ 确定权威来源
+         ↓
+Step 3: 知识整合
+    ├─ 合并来自多个来源的信息
+    ├─ 标注来源和日期
+    └─ 沉淀到领域知识库
+         ↓
+Step 4: 专家化自检
+    └─ 验证关键问题，确认无遗漏
+```
+
+### 3.2 按场景的搜索策略
+
+| 场景 | 推荐工具 | 查询技巧 |
+|------|----------|----------|
+| **查询官方 API** | Context7 | 使用库名 + "API reference" |
+| **查找最佳实践** | Exa + WebSearch | "best practices" + 生产环境 |
+| **获取代码示例** | Exa + Deepwiki | "examples" + 语言名 |
+| **了解版本更新** | WebSearch | 版本号 + "changelog" + "breaking changes" |
+| **对比多个实现** | Deepwiki | 多个仓库的文档对比 |
+
+---
+
+## 4. 错误处理
+
+### 4.1 常见错误类型
+
+| 错误类型 | 表现 | 解决方案 |
+|----------|------|----------|
+| **工具不可用** | 工具调用失败或返回错误 | 使用回退策略 (见第 6 节) |
+| **无结果** | 搜索返回空结果 | 调整查询关键词，扩大搜索范围 |
+| **结果不相关** | 返回结果与查询不匹配 | 优化查询，添加具体技术术语 |
+| **结果过时** | 返回的内容已过时 | 添加年份过滤，搜索最新版本 |
+
+### 4.2 错误处理模式
+
+```python
+# 错误处理示例
+from typing import Optional
+
+def search_with_fallback(query: str) -> Optional[str]:
+    """使用 MCP 工具搜索，失败时回退"""
+    try:
+        # 优先使用 MCP 工具
+        result = mcp_exa_web_search_exa(query)
+        if result:
+            return result
+    except Exception as e:
+        print(f"⚠️ MCP 工具失败: {e}，使用回退方案")
+    
+    # 回退方案 1: 使用 WebSearch
+    try:
+        result = WebSearch(query)
+        if result:
+            return result
+    except Exception as e:
+        print(f"⚠️ WebSearch 失败: {e}")
+    
+    # 回退方案 2: 使用现有知识库
+    return check_knowledge_base(query)
+
+def check_knowledge_base(query: str) -> Optional[str]:
+    """在现有知识库中查找"""
+    knowledge_file = "domain-knowledge/_index.md"
+    # 实现知识库查询逻辑
+    return None
+```
+
+---
+
+## 5. 性能优化
+
+### 5.1 批量查询
+
+```python
+# 使用示例
+def batch_search_queries(queries: List[str]) -> Dict[str, str]:
+    """批量执行多个查询"""
+    results = {}
+    for query in queries:
+        try:
+            result = mcp_exa_web_search_exa(query)
+            results[query] = result
+        except Exception as e:
+            results[query] = f"Error: {e}"
+    return results
+```
+
+### 5.2 结果缓存
+
+```python
+# 缓存示例
+from functools import lru_cache
+from datetime import datetime, timedelta
+
+@lru_cache(maxsize=100)
+def cached_search(query: str) -> str:
+    """带缓存的搜索，24 小时过期"""
+    return mcp_exa_web_search_exa(query)
+
+# 清除过期的缓存
+def clear_old_cache():
+    """清除超过 24 小时的缓存"""
+    # 实现缓存清理逻辑
+    pass
+```
+
+### 5.3 并行查询
+
+```python
+# 并行查询示例
+from concurrent.futures import ThreadPoolExecutor
+
+def parallel_search(queries: List[str]) -> Dict[str, str]:
+    """并行执行多个搜索"""
+    with ThreadPoolExecutor(max_workers=5) as executor:
+        futures = {
+            executor.submit(mcp_exa_web_search_exa, query): query
+            for query in queries
+        }
+        
+        results = {}
+        for future in futures:
+            query = futures[future]
+            try:
+                results[query] = future.result(timeout=30)
+            except Exception as e:
+                results[query] = f"Error: {e}"
+        
+        return results
+```
+
+---
+
+## 6. 回退策略
+
+### 6.1 回退优先级
+
+```
+┌─────────────────────────────────────────┐
+│  MCP 工具不可用时的回退策略          │
+├─────────────────────────────────────────┤
+│                                        │
+│  Priority 1: 原生工具 (推荐)    │
+│  ├─ WebSearch → WebFetch         │
+│  ├─ CodeSearch → 代码上下文搜索   │
+│  └─ 基础功能 → 使用 LLM 知识  │
+│                                        │
+│  Priority 2: 手动验证 (可接受)    │
+│  ├─ 访问官方文档页面              │
+│  ├─ 查看源代码库                 │
+│  └─ 搜索技术社区                   │
+│                                        │
+│  Priority 3: 知识库 + 警告         │
+│  ├─ 使用现有领域知识库             │
+│  ├─ 标注"知识来源：LLM + 验证"    │
+│  └─ 在 SKILL.md 中添加 metadata       │
+│                                        │
+└─────────────────────────────────────────┘
+```
+
+### 6.2 回退触发条件
+
+| 触发条件 | 优先级 | 说明 |
+|----------|--------|------|
+| MCP 工具未安装 | Priority 1 | 无法执行工具调用 |
+| MCP 工具调用超时 | Priority 1 | 工具响应过慢 |
+| API 配额耗尽 | Priority 2 | 达到使用限制 |
+| 网络不可用 | Priority 2 | 无法访问外部 API |
+| 特定语言/框架不支持 | Priority 3 | MCP 工具不支持该技术栈 |
+
+### 6.3 回退实现示例
+
+```python
+def get_latest_knowledge(topic: str) -> str:
+    """获取最新知识，带回退机制"""
+    
+    # 优先级 1: 尝试 MCP 工具
+    try:
+        result = mcp_context7_query_docs(topic)
+        if result and validate_freshness(result):
+            return result
+    except Exception as e:
+        print(f"⚠️ MCP 工具失败: {e}")
+    
+    # 优先级 2: 尝试原生工具
+    try:
+        result = WebSearch(f"{topic} latest best practices")
+        if result and validate_freshness(result):
+            return result
+    except Exception as e:
+        print(f"⚠️ 原生工具失败: {e}")
+    
+    # 优先级 3: 使用知识库
+    knowledge = check_knowledge_base(topic)
+    if knowledge:
+        print(f"⚠️ 使用现有知识库（可能已过时）")
+        return knowledge
+    
+    # 最终回退：LLM 知识
+    print(f"⚠️ 回退到 LLM 知识，建议手动验证")
+    return generate_llm_knowledge(topic)
+
+def validate_freshness(content: str) -> bool:
+    """验证内容是否足够新（发布日期 < 1 年）"""
+    # 实现时效性检查逻辑
+    return True
+```
+
+---
+
+## 7. 最佳实践
+
+### 7.1 知识获取最佳实践
+
+| 最佳实践 | 说明 | 反模式 |
+|----------|------|--------|
+| **多源交叉验证** | 从多个来源验证信息 | 只信一个来源 |
+| **优先官方文档** | 官方文档作为主要来源 | 只信博客文章 |
+| **标注来源和日期** | 记录每条知识的来源和日期 | 不记录来源 |
+| **定期更新知识库** | 定期检查和更新领域知识库 | 知识库从不更新 |
+| **使用最新版本** | 优先查询最新版本 | 使用过时的文档 |
+
+### 7.2 查询优化最佳实践
+
+| 最佳实践 | 示例 |
+|----------|------|
+| **使用具体关键词** | "React useEffect dependency array" 而非 "React useEffect" |
+| **包含语言/框架** | "Python asyncio" 而非 "async" |
+| **使用最佳实践术语** | "production best practices", "examples", "tutorial" |
+| **组合多个查询** | 同时查询官方文档和社区最佳实践 |
+| **限制结果数量** | 设置 numResults=5-10，避免信息过载 |
+
+### 7.3 错误处理最佳实践
+
+| 最佳实践 | 示例 |
+|----------|------|
+| **优雅降级** | 失败时提供合理的回退方案 | 失败时报错退出 |
+| **记录错误** | 记录错误类型和频次 | 忽略错误 |
+| **重试机制** | 对于临时性错误，重试 2-3 次 | 失败一次就放弃 |
+| **超时控制** | 设置合理的超时时间（30-60 秒） | 无限等待 |
+
+---
+
+## 8. 参考资源
+
+- [MCP Documentation](https://github.com/modelcontextprotocol/specification) - MCP 规范
+- [Context7 Documentation](https://github.com/ModelContextProtocol/context7) - Context7 文档
+- [Exa Documentation](https://docs.exa.ai/) - Exa 文档
+- [MCP Server Registry](https://modelcontextprotocol.io/servers) - MCP 服务器注册表
+
+---
+
+## 9. 快速参考卡
+
+```bash
+# 常用 MCP 命令
+
+# 查询文档
+mcp__context7__query-docs --query "<query>" --library "<library>"
+
+# 深度搜索
+mcp__exa__web_search_exa --query "<query>" --numResults 10
+mcp__exa__get_code_context_exa --query "<query>" --language "<language>"
+
+# GitHub 文档
+mcp__mcp-deepwiki__deepwiki_fetch --owner "<owner>" --repo "<repo>"
+mcp__mcp-deepwiki__query --query "<query>" --repo "<owner/repo>"
+
+# 网络搜索（原生工具）
+WebSearch --query "<query>" --numResults 8
+
+# WebFetch 获取页面
+WebFetch --url "<url>" --format markdown
+```
+
+---
+
+**知识获取流程**：
+```
+多源搜索 → 交叉验证 → 知识整合 → 专家化自检 → 沉淀知识库
+```
+
+**回退策略**：
+```
+MCP 失败 → 原生工具 → 手动验证 → 知识库 + 警告
+```