Upload 4 files

PROJECT_STRUCTURE.md

@@ -0,0 +1,184 @@
+# 📁 项目结构
+
+```
+EasyReportDateMCP/
+│
+├── 📄 README.md                    # 项目主文档
+├── 📘 USAGE.md                     # 使用指南
+├── 📋 PROJECT_STRUCTURE.md         # 本文件
+│
+├── 🐳 Dockerfile                   # HF Space 部署配置
+├── 📦 requirements.txt             # Python 依赖
+├── 🙈 .gitignore                   # Git 忽略规则
+│
+├── 🚀 mcp_server_sse.py            # MCP Server 主程序（SSE 传输）
+├── 📊 edgar_client.py              # SEC EDGAR 数据客户端
+├── 📈 financial_analyzer.py        # 财务数据分析器
+│
+└── 🧪 test_mcp_sse.py              # 测试脚本
+```
+
+---
+
+## 核心文件说明
+
+### 📄 README.md
+项目主文档，包含：
+- 快速开始指南
+- 可用工具列表
+- 使用示例
+- 技术栈说明
+
+### 📘 USAGE.md
+详细使用指南，包含：
+- 客户端配置步骤
+- 7 个工具的详细说明
+- 实际使用场景
+- 故障排除
+
+### 🚀 mcp_server_sse.py
+MCP Server 主程序（583 行）：
+- FastAPI 应用
+- SSE 传输实现
+- 7 个 MCP 工具定义
+- 格式化输出逻辑
+- 健康检查和监控
+
+### 📊 edgar_client.py
+SEC EDGAR 客户端（600+ 行）：
+- 公司搜索
+- 公司信息获取
+- 财报文件检索
+- XBRL 数据解析
+- 财务数据提取
+
+### 📈 financial_analyzer.py
+财务分析器（340+ 行）：
+- 多年数据提取
+- 数据格式化
+- 智能搜索
+- 最新数据获取
+
+### 🐳 Dockerfile
+Docker 部署配置：
+- Python 3.10 基础镜像
+- 依赖安装
+- 应用文件复制
+- Uvicorn 启动命令
+
+### 📦 requirements.txt
+Python 依赖：
+```
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+pydantic==2.5.3
+sec-edgar-api==1.1.0
+requests==2.31.0
+```
+
+### 🧪 test_mcp_sse.py
+测试脚本（232 行）：
+- 健康检查测试
+- MCP 协议测试
+- 工具调用测试
+- SSE 连接测试
+
+---
+
+## 部署文件
+
+### HF Space 必需
+- ✅ `README.md` (HF Space 主页显示)
+- ✅ `Dockerfile` (构建镜像)
+- ✅ `requirements.txt` (依赖)
+- ✅ `mcp_server_sse.py` (主程序)
+- ✅ `edgar_client.py` (核心库)
+- ✅ `financial_analyzer.py` (核心库)
+
+### 可选文件
+- 📘 `USAGE.md` (用户文档)
+- 🧪 `test_mcp_sse.py` (测试)
+- 📋 `PROJECT_STRUCTURE.md` (本文件)
+
+---
+
+## 代码统计
+
+| 文件 | 行数 | 说明 |
+|------|-----|------|
+| `mcp_server_sse.py` | 583 | MCP Server 主程序 |
+| `edgar_client.py` | 600+ | SEC 数据客户端 |
+| `financial_analyzer.py` | 340+ | 财务分析器 |
+| `test_mcp_sse.py` | 232 | 测试套件 |
+| **总计** | **~1,800** | 核心代码行数 |
+
+---
+
+## 依赖关系
+
+```
+mcp_server_sse.py
+    ├── edgar_client.py
+    │   └── sec-edgar-api
+    │   └── requests
+    │
+    └── financial_analyzer.py
+        └── edgar_client.py
+```
+
+---
+
+## 数据流
+
+```
+MCP Client (Claude Desktop)
+    ↓ SSE
+MCP Server (mcp_server_sse.py)
+    ↓
+Financial Analyzer (financial_analyzer.py)
+    ↓
+EDGAR Client (edgar_client.py)
+    ↓ HTTPS
+SEC EDGAR API
+```
+
+---
+
+## 开发工作流
+
+### 1. 本地开发
+```bash
+# 启动服务器
+python mcp_server_sse.py
+
+# 运行测试
+python test_mcp_sse.py
+```
+
+### 2. 部署到 HF Space
+```bash
+git add .
+git commit -m "Update"
+git push
+```
+
+### 3. 验证部署
+```bash
+curl https://jc321-easyreportdatemcp.hf.space/health
+```
+
+---
+
+## 项目特点
+
+✅ **简洁** - 核心文件少，结构清晰  
+✅ **专注** - 只保留 MCP Server 相关代码  
+✅ **完整** - 包含服务器、测试、文档  
+✅ **可维护** - 代码组织良好，易于理解  
+✅ **生产就绪** - 可直接部署到 HF Space
+
+---
+
+**总大小**: ~70 KB (不含 Python 缓存)  
+**文件数**: 9 个核心文件  
+**依赖数**: 5 个 Python 包

USAGE.md

@@ -0,0 +1,254 @@
+# 📘 使用指南
+
+## 🚀 快速开始
+
+### 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-easyreportdatemcp.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-easyreportdatemcp.hf.space/health
+
+# 查看工具列表
+curl https://jc321-easyreportdatemcp.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-easyreportdatemcp.hf.space/  
+**查看文档**: 主页包含完整的配置说明和示例
+
+---
+
+**享受你的 MCP Server！** 🚀

requirements.txt

@@ -0,0 +1,11 @@
+# FastAPI RESTful API Server (original)
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+pydantic==2.5.3
+
+# FastMCP - Standard MCP Server
+fastmcp==0.3.0
+
+# SEC EDGAR API
+sec-edgar-api==1.1.0
+requests==2.31.0

test_mcp_sse.py

@@ -0,0 +1,231 @@
+"""
+Test script for MCP Server with SSE transport
+Tests all endpoints and MCP protocol compliance
+"""
+
+import requests
+import json
+import time
+
+# Configuration
+BASE_URL = "http://localhost:7860"  # Change to your HF Space URL for remote testing
+
+def test_health_check():
+    """Test health check endpoint"""
+    print("🔍 Testing health check...")
+    response = requests.get(f"{BASE_URL}/health")
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    assert response.status_code == 200
+    assert response.json()["status"] == "healthy"
+    print("✅ Health check passed\n")
+
+
+def test_tools_list():
+    """Test tools listing endpoint"""
+    print("🔍 Testing tools list...")
+    response = requests.get(f"{BASE_URL}/tools")
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Number of tools: {len(data['tools'])}")
+    for tool in data['tools']:
+        print(f"  - {tool['name']}")
+    assert response.status_code == 200
+    assert len(data['tools']) == 7
+    print("✅ Tools list passed\n")
+
+
+def test_mcp_initialize():
+    """Test MCP initialize method"""
+    print("🔍 Testing MCP initialize...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {
+                "name": "test-client",
+                "version": "1.0.0"
+            }
+        }
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    assert response.status_code == 200
+    assert response.json()["result"]["serverInfo"]["name"] == "sec-financial-data"
+    print("✅ MCP initialize passed\n")
+
+
+def test_mcp_tools_list():
+    """Test MCP tools/list method"""
+    print("🔍 Testing MCP tools/list...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list"
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Number of tools: {len(data['result']['tools'])}")
+    assert response.status_code == 200
+    assert len(data['result']['tools']) == 7
+    print("✅ MCP tools/list passed\n")
+
+
+def test_search_company():
+    """Test search_company tool"""
+    print("🔍 Testing search_company tool...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "tools/call",
+        "params": {
+            "name": "search_company",
+            "arguments": {
+                "company_name": "Microsoft"
+            }
+        }
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Response preview: {data['result']['content'][0]['text'][:200]}...")
+    assert response.status_code == 200
+    assert "content" in data["result"]
+    print("✅ search_company passed\n")
+
+
+def test_get_company_info():
+    """Test get_company_info tool"""
+    print("🔍 Testing get_company_info tool...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 4,
+        "method": "tools/call",
+        "params": {
+            "name": "get_company_info",
+            "arguments": {
+                "cik": "0000789019"  # Microsoft
+            }
+        }
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Response preview: {data['result']['content'][0]['text'][:200]}...")
+    assert response.status_code == 200
+    print("✅ get_company_info passed\n")
+
+
+def test_get_latest_financial_data():
+    """Test get_latest_financial_data tool"""
+    print("🔍 Testing get_latest_financial_data tool...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 5,
+        "method": "tools/call",
+        "params": {
+            "name": "get_latest_financial_data",
+            "arguments": {
+                "cik": "0000789019"  # Microsoft
+            }
+        }
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Response preview: {data['result']['content'][0]['text'][:300]}...")
+    assert response.status_code == 200
+    print("✅ get_latest_financial_data passed\n")
+
+
+def test_extract_financial_metrics():
+    """Test extract_financial_metrics tool"""
+    print("🔍 Testing extract_financial_metrics tool...")
+    payload = {
+        "jsonrpc": "2.0",
+        "id": 6,
+        "method": "tools/call",
+        "params": {
+            "name": "extract_financial_metrics",
+            "arguments": {
+                "cik": "0000789019",  # Microsoft
+                "years": 2
+            }
+        }
+    }
+    response = requests.post(f"{BASE_URL}/message", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Response preview: {data['result']['content'][0]['text'][:300]}...")
+    assert response.status_code == 200
+    print("✅ extract_financial_metrics passed\n")
+
+
+def test_sse_endpoint():
+    """Test SSE endpoint (basic connection)"""
+    print("🔍 Testing SSE endpoint...")
+    try:
+        response = requests.get(f"{BASE_URL}/sse", stream=True, timeout=5)
+        print(f"Status: {response.status_code}")
+        print("Reading first event...")
+        
+        # Read first event
+        for line in response.iter_lines():
+            if line:
+                decoded_line = line.decode('utf-8')
+                print(f"Received: {decoded_line}")
+                if decoded_line.startswith('data:'):
+                    break
+        
+        print("✅ SSE endpoint passed\n")
+    except requests.exceptions.Timeout:
+        print("⚠️  SSE endpoint timeout (expected for streaming)\n")
+
+
+def main():
+    """Run all tests"""
+    print("=" * 60)
+    print("🧪 MCP Server SSE Transport Test Suite")
+    print("=" * 60)
+    print()
+    
+    tests = [
+        ("Health Check", test_health_check),
+        ("Tools List", test_tools_list),
+        ("MCP Initialize", test_mcp_initialize),
+        ("MCP Tools List", test_mcp_tools_list),
+        ("Search Company", test_search_company),
+        ("Get Company Info", test_get_company_info),
+        ("Get Latest Financial Data", test_get_latest_financial_data),
+        ("Extract Financial Metrics", test_extract_financial_metrics),
+        ("SSE Endpoint", test_sse_endpoint),
+    ]
+    
+    passed = 0
+    failed = 0
+    
+    for name, test_func in tests:
+        try:
+            test_func()
+            passed += 1
+        except Exception as e:
+            print(f"❌ {name} failed: {e}\n")
+            failed += 1
+    
+    print("=" * 60)
+    print(f"✅ Tests passed: {passed}/{len(tests)}")
+    if failed > 0:
+        print(f"❌ Tests failed: {failed}/{len(tests)}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    print("\n⚠️  Make sure the server is running:")
+    print("   python mcp_server_sse.py\n")
+    time.sleep(1)
+    main()