USAGE.md

# 📘 使用指南

## 🚀 快速开始

### 1. 连接到 MCP Server

#### Claude Desktop 配置

**Windows**: 编辑 `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS**: 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`

添加配置：
```json
{
  "mcpServers": {
    "sec-financial-data": {
      "url": "https://jc321-easyreportsmcpserver.hf.space/sse"
    }
  }
}
```

重启 Claude Desktop，查看右下角 🔌 图标。

---

## 🛠️ 可用工具 (7个)

### 1. `search_company`
按公司名称搜索 → 获取 CIK、ticker、官方名称

**示例**: "Search for Microsoft"

---

### 2. `get_company_info`
获取详细公司信息 → 行业、SIC 代码、财年等

**参数**: `cik` (公司 CIK 代码)

---

### 3. `get_company_filings`
列出所有 SEC 报告 → 10-K, 10-Q, 20-F 及日期、链接

**参数**: 
- `cik`: 公司 CIK 代码
- `form_types` (可选): 如 `["10-K", "10-Q"]`

---

### 4. `get_financial_data`
获取特定期间财务数据 → Revenue, Net Income, EPS, Cash Flow

**参数**:
- `cik`: 公司 CIK 代码
- `period`: 格式 "YYYY" (年度) 或 "YYYYQX" (季度)

**示例**: "Show me Apple's financial data for 2024Q3"

---

### 5. `extract_financial_metrics` ⭐ 推荐
提取多年综合指标 → 年度 + 季度数据，按时间排序

**参数**:
- `cik`: 公司 CIK 代码
- `years`: 年数 (1-10, 默认 3)

**示例**: "Extract 5 years of financial metrics for Tesla"

---

### 6. `get_latest_financial_data`
获取最新可用财务数据

**参数**: `cik` (公司 CIK 代码)

---

### 7. `advanced_search_company`
智能搜索 → 自动识别公司名称、ticker 或 CIK

**参数**: `company_input` (任意格式的公司标识)

---

## 💬 使用示例

### 场景 1: 快速查询
**输入**: "Search for Tesla and show me their latest financial data"

**AI 工作流程**:
1. 🔍 `search_company("Tesla")` → 找到 CIK
2. 🆕 `get_latest_financial_data(cik)` → 获取最新数据
3. 📊 返回格式化结果

---

### 场景 2: 趋势分析
**输入**: "Extract 3 years of financial metrics for Apple and analyze revenue growth"

**AI 工作流程**:
1. 📈 `extract_financial_metrics(cik, years=3)`
2. 📊 返回 12+ 期数据（年度 + 季度）
3. 🤖 AI 分析并解释趋势

---

### 场景 3: 公司对比
**输入**: "Compare NVIDIA and AMD revenue for the past 2 years"

**AI 工作流程**:
1. 🔍 搜索两家公司
2. 📊 提取各自数据
3. 📈 AI 对比分析

---

## 🎨 格式化输出示例

### 成功查询
```
✅ Company Found:
{
  "cik": "0000789019",
  "name": "MICROSOFT CORP",
  "ticker": "MSFT"
}
```

### 财务数据
```
💰 Financial Data for 2024Q3:
{
  "period": "2024Q3",
  "revenue": "$65.59B",
  "net_income": "$24.67B",
  "eps": "$3.30",
  "operating_cash_flow": "$34.25B",
  "free_cash_flow": "$19.28B"
}
```

### 多年数据
```
📈 Financial Metrics (12 periods):
[
  {
    "period": "2024Q3",
    "type": "quarterly",
    "revenue": "$65.59B",
    ...
  },
  ...
]
```

---

## 🔧 本地开发和测试

### 启动服务器
```bash
python mcp_server_sse.py
```

访问: http://localhost:7860

### 运行测试
```bash
python test_mcp_sse.py
```

### 健康检查
```bash
curl http://localhost:7860/health
```

---

## 📦 部署到 Hugging Face Space

### 方法 1: Git 推送
```bash
git add .
git commit -m "Update MCP Server"
git push
```

### 方法 2: Web 界面
直接在 HF Space 上传文件。

### 验证部署
```bash
# 检查健康状态
curl https://jc321-easyreportsmcpserver.hf.space/health

# 查看工具列表
curl https://jc321-easyreportsmcpserver.hf.space/tools
```

---

## ⚠️ 常见问题

### Q: Claude Desktop 看不到工具？
**A**: 
1. 检查 JSON 配置格式
2. 确认 URL 以 `/sse` 结尾
3. 完全退出并重启 Claude Desktop

### Q: 工具调用返回错误？
**A**:
1. 检查 CIK 格式（10位数字）
2. 验证期间格式（"2024" 或 "2024Q3"）
3. 稍等片刻再试（SEC API 限流）

### Q: Space 冷启动慢？
**A**: 
首次访问需要 30-60 秒唤醒，访问主页即可唤醒。

---

## 📊 端点参考

| 端点 | 说明 |
|------|------|
| `/` | 主页（引导页面） |
| `/sse` | SSE 连接端点（MCP 客户端使用） |
| `/message` | MCP 消息处理 |
| `/tools` | 工具列表（JSON） |
| `/health` | 健康检查 |

---

## 🎯 数据来源

**SEC EDGAR API** - 美国证券交易委员会官方数据

**遵守规则**:
- User-Agent: Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)
- 速率限制: 最多 10 请求/秒

---

## 📞 支持

**访问主页**: https://jc321-easyreportsmcpserver.hf.space/  
**查看文档**: 主页包含完整的配置说明和示例

---

**享受你的 MCP Server！** 🚀