USAGE.md

📘 使用指南

🚀 快速开始

1. 连接到 MCP Server

Claude Desktop 配置

Windows: 编辑 %APPDATA%\Claude\claude_desktop_config.json
macOS: 编辑 ~/Library/Application Support/Claude/claude_desktop_config.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",
    ...
  },
  ...
]

---

🔧 本地开发和测试

启动服务器

python mcp_server_sse.py

访问: http://localhost:7860

运行测试

python test_mcp_sse.py

健康检查

curl http://localhost:7860/health

---

📦 部署到 Hugging Face Space

方法 1: Git 推送

git add .
git commit -m "Update MCP Server"
git push

方法 2: Web 界面

直接在 HF Space 上传文件。

验证部署

# 检查健康状态
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！ 🚀