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！** 🚀