Upload 8 files

API_USAGE.md

@@ -0,0 +1,500 @@
+# API Usage Guide
+
+Complete guide for using the SEC Financial Report MCP Server API.
+
+## Base URL
+
+After deployment: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
+
+## Interactive Documentation
+
+- **Swagger UI**: `{BASE_URL}/docs`
+- **ReDoc**: `{BASE_URL}/redoc`
+
+## Quick Start
+
+### Python Example
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_SPACE_URL.hf.space"
+
+# 1. Search company
+response = requests.post(
+    f"{BASE_URL}/api/search_company",
+    json={"company_name": "NVIDIA"}
+)
+company = response.json()
+print(f"Found: {company['name']} (CIK: {company['cik']})")
+
+# 2. Get financial data
+response = requests.post(
+    f"{BASE_URL}/api/get_financial_data",
+    json={"cik": company['cik'], "period": "2024"}
+)
+data = response.json()
+print(f"Revenue: ${data['total_revenue']:,.0f}")
+print(f"Net Income: ${data['net_income']:,.0f}")
+print(f"EPS: ${data['earnings_per_share']:.2f}")
+```
+
+## Base URL
+
+```
+https://your-space-name.hf.space
+```
+
+## API Endpoints
+
+### 1. Search Company by Name
+
+**Endpoint:** `POST /api/search_company`
+
+**Request:**
+```json
+{
+  "company_name": "NVIDIA"
+}
+```
+
+**Response:**
+```json
+{
+  "cik": "0001045810",
+  "name": "NVIDIA CORP",
+  "ticker": "NVDA",
+  "error": null
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST "https://your-space-name.hf.space/api/search_company" \
+  -H "Content-Type: application/json" \
+  -d '{"company_name": "NVIDIA"}'
+```
+
+**Python Example:**
+```python
+import requests
+
+url = "https://your-space-name.hf.space/api/search_company"
+payload = {"company_name": "NVIDIA"}
+response = requests.post(url, json=payload)
+print(response.json())
+```
+
+---
+
+### 2. Get Company Information
+
+**Endpoint:** `POST /api/get_company_info`
+
+**Request:**
+```json
+{
+  "cik": "0001045810"
+}
+```
+
+**Response:**
+```json
+{
+  "cik": "0001045810",
+  "name": "NVIDIA CORP",
+  "tickers": ["NVDA"],
+  "sic": "3674",
+  "sic_description": "Semiconductors & Related Devices",
+  "error": null
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST "https://your-space-name.hf.space/api/get_company_info" \
+  -H "Content-Type: application/json" \
+  -d '{"cik": "0001045810"}'
+```
+
+**Python Example:**
+```python
+import requests
+
+url = "https://your-space-name.hf.space/api/get_company_info"
+payload = {"cik": "0001045810"}
+response = requests.post(url, json=payload)
+print(response.json())
+```
+
+---
+
+### 3. Get Company Filings
+
+**Endpoint:** `POST /api/get_company_filings`
+
+**Request (All form types):**
+```json
+{
+  "cik": "0001045810",
+  "form_types": null
+}
+```
+
+**Request (Specific form types):**
+```json
+{
+  "cik": "0001045810",
+  "form_types": ["10-K", "10-Q"]
+}
+```
+
+**Response:**
+```json
+{
+  "filings": [
+    {
+      "form_type": "10-K",
+      "filing_date": "2024-02-21",
+      "accession_number": "0001045810-24-000029",
+      "primary_document": "nvda-20240128.htm"
+    },
+    {
+      "form_type": "10-Q",
+      "filing_date": "2024-05-22",
+      "accession_number": "0001045810-24-000067",
+      "primary_document": "nvda-20240428.htm"
+    }
+  ],
+  "error": null
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST "https://your-space-name.hf.space/api/get_company_filings" \
+  -H "Content-Type: application/json" \
+  -d '{"cik": "0001045810", "form_types": ["10-K", "10-Q"]}'
+```
+
+**Python Example:**
+```python
+import requests
+
+url = "https://your-space-name.hf.space/api/get_company_filings"
+payload = {
+    "cik": "0001045810",
+    "form_types": ["10-K", "10-Q"]
+}
+response = requests.post(url, json=payload)
+print(response.json())
+```
+
+---
+
+### 4. Get Company Facts
+
+**Endpoint:** `POST /api/get_company_facts`
+
+**Request:**
+```json
+{
+  "cik": "0001045810"
+}
+```
+
+**Response:**
+```json
+{
+  "facts": {
+    "dei": {
+      "EntityCommonStockSharesOutstanding": {...},
+      "EntityPublicFloat": {...}
+    },
+    "us-gaap": {
+      "Revenues": {...},
+      "NetIncomeLoss": {...},
+      "EarningsPerShareBasic": {...}
+    }
+  },
+  "error": null
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST "https://your-space-name.hf.space/api/get_company_facts" \
+  -H "Content-Type: application/json" \
+  -d '{"cik": "0001045810"}'
+```
+
+**Python Example:**
+```python
+import requests
+
+url = "https://your-space-name.hf.space/api/get_company_facts"
+payload = {"cik": "0001045810"}
+response = requests.post(url, json=payload)
+print(response.json())
+```
+
+---
+
+### 5. Get Financial Data for Period
+
+**Endpoint:** `POST /api/get_financial_data`
+
+**Request (Annual Data):**
+```json
+{
+  "cik": "0001045810",
+  "period": "2024"
+}
+```
+
+**Request (Quarterly Data):**
+```json
+{
+  "cik": "0001045810",
+  "period": "2024Q3"
+}
+```
+
+**Response:**
+```json
+{
+  "period": "2024",
+  "total_revenue": 60922000000,
+  "net_income": 29760000000,
+  "earnings_per_share": 12.04,
+  "operating_expenses": 11822000000,
+  "operating_cash_flow": 28091000000,
+  "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000029",
+  "source_form": "10-K",
+  "data_source": "us-gaap",
+  "additional_details": {
+    "total_revenue_details": {
+      "tag": "Revenues",
+      "form": "10-K",
+      "fy": 2024,
+      "fp": "FY",
+      "val": 60922000000,
+      "start": "2023-01-30",
+      "end": "2024-01-28",
+      "accn": "0001045810-24-000029",
+      "filed": "2024-02-21",
+      "frame": "CY2023",
+      "data_source": "us-gaap"
+    }
+  },
+  "error": null
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST "https://your-space-name.hf.space/api/get_financial_data" \
+  -H "Content-Type: application/json" \
+  -d '{"cik": "0001045810", "period": "2024"}'
+```
+
+**Python Example:**
+```python
+import requests
+
+url = "https://your-space-name.hf.space/api/get_financial_data"
+payload = {
+    "cik": "0001045810",
+    "period": "2024"
+}
+response = requests.post(url, json=payload)
+data = response.json()
+print(f"Total Revenue: ${data['total_revenue']:,.0f}")
+print(f"Net Income: ${data['net_income']:,.0f}")
+print(f"EPS: ${data['earnings_per_share']:.2f}")
+```
+
+---
+
+## Complete Python Client Example
+
+```python
+import requests
+import json
+
+
+class SECMCPClient:
+    """Client for SEC Financial Report MCP Server"""
+    
+    def __init__(self, base_url):
+        self.base_url = base_url.rstrip('/')
+    
+    def search_company(self, company_name):
+        """Search company by name"""
+        url = f"{self.base_url}/api/search_company"
+        response = requests.post(url, json={"company_name": company_name})
+        return response.json()
+    
+    def get_company_info(self, cik):
+        """Get company information"""
+        url = f"{self.base_url}/api/get_company_info"
+        response = requests.post(url, json={"cik": cik})
+        return response.json()
+    
+    def get_company_filings(self, cik, form_types=None):
+        """Get company filings"""
+        url = f"{self.base_url}/api/get_company_filings"
+        payload = {"cik": cik, "form_types": form_types}
+        response = requests.post(url, json=payload)
+        return response.json()
+    
+    def get_company_facts(self, cik):
+        """Get company facts"""
+        url = f"{self.base_url}/api/get_company_facts"
+        response = requests.post(url, json={"cik": cik})
+        return response.json()
+    
+    def get_financial_data(self, cik, period):
+        """Get financial data for period"""
+        url = f"{self.base_url}/api/get_financial_data"
+        payload = {"cik": cik, "period": period}
+        response = requests.post(url, json=payload)
+        return response.json()
+
+
+# Usage example
+if __name__ == "__main__":
+    # Initialize client
+    client = SECMCPClient("https://your-space-name.hf.space")
+    
+    # Search for a company
+    company = client.search_company("NVIDIA")
+    print(f"Found: {company['name']} (CIK: {company['cik']})")
+    
+    # Get company information
+    info = client.get_company_info(company['cik'])
+    print(f"Industry: {info['sic_description']}")
+    
+    # Get recent filings
+    filings = client.get_company_filings(company['cik'], ["10-K"])
+    print(f"Recent 10-K filings: {len(filings['filings'])}")
+    
+    # Get financial data for 2024
+    financial_data = client.get_financial_data(company['cik'], "2024")
+    print(f"FY2024 Revenue: ${financial_data['total_revenue']:,.0f}")
+    print(f"FY2024 Net Income: ${financial_data['net_income']:,.0f}")
+    print(f"FY2024 EPS: ${financial_data['earnings_per_share']:.2f}")
+```
+
+---
+
+## Complete JavaScript/Node.js Client Example
+
+```javascript
+const axios = require('axios');
+
+class SECMCPClient {
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+
+    async searchCompany(companyName) {
+        const response = await axios.post(
+            `${this.baseUrl}/api/search_company`,
+            { company_name: companyName }
+        );
+        return response.data;
+    }
+
+    async getCompanyInfo(cik) {
+        const response = await axios.post(
+            `${this.baseUrl}/api/get_company_info`,
+            { cik: cik }
+        );
+        return response.data;
+    }
+
+    async getCompanyFilings(cik, formTypes = null) {
+        const response = await axios.post(
+            `${this.baseUrl}/api/get_company_filings`,
+            { cik: cik, form_types: formTypes }
+        );
+        return response.data;
+    }
+
+    async getCompanyFacts(cik) {
+        const response = await axios.post(
+            `${this.baseUrl}/api/get_company_facts`,
+            { cik: cik }
+        );
+        return response.data;
+    }
+
+    async getFinancialData(cik, period) {
+        const response = await axios.post(
+            `${this.baseUrl}/api/get_financial_data`,
+            { cik: cik, period: period }
+        );
+        return response.data;
+    }
+}
+
+// Usage example
+(async () => {
+    const client = new SECMCPClient('https://your-space-name.hf.space');
+    
+    // Search for a company
+    const company = await client.searchCompany('NVIDIA');
+    console.log(`Found: ${company.name} (CIK: ${company.cik})`);
+    
+    // Get financial data
+    const financialData = await client.getFinancialData(company.cik, '2024');
+    console.log(`FY2024 Revenue: $${financialData.total_revenue.toLocaleString()}`);
+    console.log(`FY2024 Net Income: $${financialData.net_income.toLocaleString()}`);
+    console.log(`FY2024 EPS: $${financialData.earnings_per_share.toFixed(2)}`);
+})();
+```
+
+---
+
+## Error Handling
+
+All endpoints return standard HTTP status codes:
+
+- **200 OK**: Successful request
+- **422 Unprocessable Entity**: Invalid request parameters
+- **500 Internal Server Error**: Server error
+
+Error response format:
+```json
+{
+  "detail": "Error message description"
+}
+```
+
+Or for API-specific errors:
+```json
+{
+  "error": "No company found matching 'INVALID_NAME'"
+}
+```
+
+---
+
+## Notes
+
+- All monetary values are in USD (original values, not converted to millions)
+- The `earnings_per_share` value is per share
+- Data source: US SEC EDGAR system
+- Supports US-GAAP and IFRS standards
+- User-Agent: Juntao Peng (jtyxabc@gmail.com)
+- Rate limiting follows SEC EDGAR API guidelines (10 requests per second)
+
+---
+
+## Interactive API Documentation
+
+Once deployed, you can access interactive API documentation at:
+
+- Swagger UI: `https://your-space-name.hf.space/docs`
+- ReDoc: `https://your-space-name.hf.space/redoc`

DEPLOYMENT.md

@@ -0,0 +1,121 @@
+# Hugging Face Space Deployment Guide
+
+## Quick Deployment Steps
+
+### 1. Create a New Space
+
+1. Visit https://huggingface.co/spaces
+2. Click **"Create new Space"**
+3. Configure:
+   - **Name**: Choose a unique name (e.g., `sec-financial-mcp`)
+   - **License**: MIT
+   - **SDK**: **Docker** ⚠️ Important!
+   - **Visibility**: Public or Private
+
+### 2. Clone and Upload
+
+```bash
+# Clone your Space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+
+# Copy all project files
+cp /path/to/EasyReportDateMCP/* .
+
+# Commit and push
+git add .
+git commit -m "Initial deployment: SEC Financial MCP Server"
+git push
+```
+
+### 3. Required Files
+
+Make sure these files are in your Space repository:
+
+```
+✓ Dockerfile          # Docker configuration
+✓ mcp_server.py       # FastAPI application
+✓ edgar_client.py     # EDGAR client
+✓ requirements.txt    # Dependencies
+✓ README.md           # Space description
+✓ .gitignore          # Git ignore rules
+```
+
+### 4. Wait for Build
+
+Hugging Face will automatically build your Space (takes 3-5 minutes).
+
+Monitor the build in the **"Logs"** tab.
+
+### 5. Access Your API
+
+Once deployed, your API will be available at:
+
+```
+https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
+```
+
+**Interactive Documentation**:
+- Swagger UI: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs`
+- ReDoc: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/redoc`
+
+## Testing Your Deployment
+
+### Health Check
+
+```bash
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
+```
+
+### Search Company
+
+```bash
+curl -X POST "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/search_company" \
+  -H "Content-Type: application/json" \
+  -d '{"company_name": "NVIDIA"}'
+```
+
+### Python Test
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space"
+
+# Search company
+response = requests.post(
+    f"{BASE_URL}/api/search_company",
+    json={"company_name": "NVIDIA"}
+)
+print(response.json())
+```
+
+## Troubleshooting
+
+### Build Fails
+- Check the **Logs** tab for errors
+- Verify all files are present
+- Ensure `Dockerfile` is correct
+
+### Server Not Responding
+- Check if build completed successfully
+- Verify port 7860 is exposed in Dockerfile
+- Check application logs in Logs tab
+
+### API Errors
+- Test with Swagger UI at `/docs`
+- Check request JSON format
+- Review error messages in response
+
+## Notes
+
+- Free Spaces sleep after 48 hours of inactivity
+- Port 7860 is standard for Hugging Face Spaces
+- Docker SDK is required for this deployment
+- All API endpoints use POST method except `/health`
+
+## Support
+
+- Documentation: See `API_USAGE.md`
+- Interactive Testing: Visit `/docs` after deployment
+- Hugging Face Docs: https://huggingface.co/docs/hub/spaces

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY edgar_client.py .
+COPY financial_analyzer.py .
+COPY mcp_server.py .
+
+# Expose port
+EXPOSE 7860
+
+# Set environment variable
+ENV PYTHONUNBUFFERED=1
+
+# Run the MCP server
+CMD ["uvicorn", "mcp_server:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,12 +1,84 @@
----
-title: EasyReportDateMCP
-emoji: 🔥
-colorFrom: red
-colorTo: green
-sdk: docker
-pinned: false
-license: mit
-short_description: EasyReportDateMCP
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: SEC Financial Report MCP Server
+emoji: 📊
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+---
+
+# SEC Financial Report MCP Server
+
+A FastAPI-based MCP (Model Context Protocol) Server for querying SEC EDGAR financial data.
+
+## Features
+
+- **Company Search**: Search companies by name and get CIK information
+- **Company Information**: Retrieve detailed company information from SEC EDGAR
+- **Filings Retrieval**: Get all historical filings (10-K, 10-Q, 20-F)
+- **Financial Facts**: Access complete financial facts data
+- **Financial Metrics**: Extract key financial metrics for specific periods (annual/quarterly)
+  - Total Revenue
+  - Net Income
+  - Earnings Per Share (EPS)
+  - Operating Expenses
+  - Operating Cash Flow
+
+## Supported Report Types
+
+- **10-K**: Annual reports (US companies)
+- **10-Q**: Quarterly reports (US companies)
+- **20-F**: Annual reports (Foreign private issuers)
+
+## Data Standards
+
+- US-GAAP (US Generally Accepted Accounting Principles)
+- IFRS (International Financial Reporting Standards)
+
+## API Documentation
+
+Once deployed, visit `/docs` for interactive Swagger UI documentation or `/redoc` for ReDoc documentation.
+
+## API Endpoints
+
+- `POST /api/search_company` - Search company by name
+- `POST /api/get_company_info` - Get company information
+- `POST /api/get_company_filings` - Get company filings
+- `POST /api/get_company_facts` - Get company financial facts
+- `POST /api/get_financial_data` - Get financial data for period
+- `GET /health` - Health check
+
+## Usage Example
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_SPACE_URL.hf.space"
+
+# Search company
+response = requests.post(
+    f"{BASE_URL}/api/search_company",
+    json={"company_name": "NVIDIA"}
+)
+print(response.json())
+# Output: {'cik': '0001045810', 'name': 'NVIDIA CORP', 'ticker': 'NVDA'}
+
+# Get financial data
+response = requests.post(
+    f"{BASE_URL}/api/get_financial_data",
+    json={"cik": "0001045810", "period": "2024"}
+)
+data = response.json()
+print(f"Revenue: ${data['total_revenue']:,.0f}")
+print(f"Net Income: ${data['net_income']:,.0f}")
+```
+
+## Data Source
+
+All data is retrieved from the US Securities and Exchange Commission (SEC) EDGAR system.
+
+## User Agent
+
+This service uses the following User-Agent (required by SEC API):
+- Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)

edgar_client.py

@@ -0,0 +1,342 @@
+"""EDGAR API Client Module"""
+
+import requests
+try:
+    from sec_edgar_api.EdgarClient import EdgarClient
+except ImportError:
+    EdgarClient = None
+import json
+import time
+
+
+class EdgarDataClient:
+    def __init__(self, user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"):
+        """Initialize EDGAR client"""
+        self.user_agent = user_agent
+        if EdgarClient:
+            self.edgar = EdgarClient(user_agent=user_agent)
+        else:
+            self.edgar = None
+        
+    def search_company_by_name(self, company_name):
+        """Search company CIK by company name"""
+        try:
+            # Use SEC company ticker database
+            url = "https://www.sec.gov/files/company_tickers.json"
+            headers = {"User-Agent": self.user_agent}
+            
+            response = requests.get(url, headers=headers)
+            response.raise_for_status()
+            
+            companies = response.json()
+            
+            # Search for matching company names
+            matches = []
+            exact_matches = []
+            for _, company in companies.items():
+                company_title = company["title"].lower()
+                search_name = company_name.lower()
+                
+                # Exact match
+                if search_name == company_title:
+                    exact_matches.append({
+                        "cik": str(company["cik_str"]).zfill(10),
+                        "name": company["title"],
+                        "ticker": company["ticker"]
+                    })
+                # Partial match
+                elif search_name in company_title or \
+                     search_name in company["ticker"].lower():
+                    matches.append({
+                        "cik": str(company["cik_str"]).zfill(10),
+                        "name": company["title"],
+                        "ticker": company["ticker"]
+                    })
+            
+            # Return exact match first, then partial match
+            if exact_matches:
+                return exact_matches[0]
+            elif matches:
+                return matches[0]
+            else:
+                return None
+            
+        except Exception as e:
+            print(f"搜索公司时出错: {e}")
+            return None
+    
+    def get_company_info(self, cik):
+        """
+        获取公司基本信息
+        
+        Args:
+            cik (str): 公司CIK码
+            
+        Returns:
+            dict: 包含公司信息的字典
+        """
+        if not self.edgar:
+            print("sec_edgar_api库未安装")
+            return None
+            
+        try:
+            # 获取公司提交信息
+            submissions = self.edgar.get_submissions(cik=cik)
+            
+            return {
+                "cik": cik,
+                "name": submissions.get("name", ""),
+                "tickers": submissions.get("tickers", []),
+                "sic": submissions.get("sic", ""),
+                "sic_description": submissions.get("sicDescription", "")
+            }
+        except Exception as e:
+            print(f"获取公司信息时出错: {e}")
+            return None
+    
+    def get_company_filings(self, cik, form_types=None):
+        """
+        获取公司所有财报文件列表
+        
+        Args:
+            cik (str): 公司CIK码
+            form_types (list): 财报类型列表，如['10-K', '10-Q']，默认为None表示获取所有类型
+            
+        Returns:
+            list: 财报文件列表
+        """
+        if not self.edgar:
+            print("sec_edgar_api库未安装")
+            return []
+            
+        try:
+            # 获取公司提交信息
+            submissions = self.edgar.get_submissions(cik=cik)
+            
+            # 提取财报信息
+            filings = []
+            recent = submissions.get("filings", {}).get("recent", {})
+            
+            # 获取各个字段的数据
+            form_types_list = recent.get("form", [])
+            filing_dates = recent.get("filingDate", [])
+            accession_numbers = recent.get("accessionNumber", [])
+            primary_documents = recent.get("primaryDocument", [])
+            
+            # 遍历所有财报
+            for i in range(len(form_types_list)):
+                form_type = form_types_list[i]
+                
+                # 如果指定了财报类型，则只返回匹配的类型
+                if form_types and form_type not in form_types:
+                    continue
+                
+                filing_date = filing_dates[i] if i < len(filing_dates) else ""
+                accession_number = accession_numbers[i] if i < len(accession_numbers) else ""
+                primary_document = primary_documents[i] if i < len(primary_documents) else ""
+                
+                filing = {
+                    "form_type": form_type,
+                    "filing_date": filing_date,
+                    "accession_number": accession_number,
+                    "primary_document": primary_document
+                }
+                
+                filings.append(filing)
+            
+            return filings
+        except Exception as e:
+            print(f"获取公司财报列表时出错: {e}")
+            return []
+    
+    def get_company_facts(self, cik):
+        """
+        获取公司所有财务事实数据
+        
+        Args:
+            cik (str): 公司CIK码
+            
+        Returns:
+            dict: 公司财务事实数据
+        """
+        if not self.edgar:
+            print("sec_edgar_api库未安装")
+            return {}
+            
+        try:
+            facts = self.edgar.get_company_facts(cik=cik)
+            return facts
+        except Exception as e:
+            print(f"获取公司财务事实时出错: {e}")
+            return {}
+    
+    def get_financial_data_for_period(self, cik, period):
+        """
+        获取指定期间的财务数据（支持年度和季度）
+        
+        Args:
+            cik (str): 公司CIK码
+            period (str): 期间，格式为'YYYY'或'YYYYQX'（如'2025'或'2025Q3'）
+            
+        Returns:
+            dict: 财务数据字典
+        """
+        if not self.edgar:
+            print("sec_edgar_api库未安装")
+            return {}
+            
+        try:
+            # 获取公司财务事实
+            facts = self.get_company_facts(cik)
+            
+            if not facts:
+                return {}
+            
+            # 提取us-gaap和ifrs-full部分的财务数据（20-F可能使用IFRS）
+            us_gaap = facts.get("facts", {}).get("us-gaap", {})
+            ifrs_full = facts.get("facts", {}).get("ifrs-full", {})
+            
+            # 定义要获取的财务指标及其XBRL标签
+            # 包含多个可能的标签以提高匹配率（包括US-GAAP和IFRS标签）
+            financial_metrics = {
+                "total_revenue": ["Revenues", "RevenueFromContractWithCustomerExcludingAssessedTax", "RevenueFromContractWithCustomerIncludingAssessedTax", "SalesRevenueNet", "RevenueFromContractWithCustomer", "Revenue"],
+                "net_income": ["NetIncomeLoss", "ProfitLoss", "NetIncome", "ProfitLossAttributableToOwnersOfParent"],
+                "earnings_per_share": ["EarningsPerShareBasic", "EarningsPerShare", "BasicEarningsPerShare", "BasicEarningsLossPerShare"],
+                "operating_expenses": ["OperatingExpenses", "OperatingCostsAndExpenses", "OperatingExpensesExcludingDepreciationAndAmortization", "CostsAndExpenses", "GeneralAndAdministrativeExpense", "CostOfRevenue", "ResearchAndDevelopmentExpense", "SellingAndMarketingExpense"],
+                "operating_cash_flow": ["NetCashProvidedByUsedInOperatingActivities", "NetCashProvidedUsedInOperatingActivities", "NetCashFlowsFromUsedInOperatingActivities", "CashFlowsFromUsedInOperatingActivities"],
+            }
+            
+            # 存储结果
+            result = {"period": period}
+            
+            # 确定要查找的表格类型
+            if 'Q' in period:
+                # 季度数据，主要查找10-Q（20-F通常没有季度报告）
+                target_forms = ["10-Q"]
+                target_forms_annual = ["10-K", "20-F"]  # 用于回退查找
+                year = int(period.split('Q')[0])
+                quarter = period.split('Q')[1]
+            else:
+                # 年度数据，查找10-K和20-F年度表格
+                target_forms = ["10-K", "20-F"]
+                target_forms_annual = target_forms
+                year = int(period)
+                quarter = None
+            
+            # 遍历每个财务指标
+            for metric_key, metric_tags in financial_metrics.items():
+                # 支持多个可能的标签
+                for metric_tag in metric_tags:
+                    # 同时查找US-GAAP和IFRS标签
+                    metric_data = None
+                    data_source = None
+                    
+                    if metric_tag in us_gaap:
+                        metric_data = us_gaap[metric_tag]
+                        data_source = "us-gaap"
+                    elif metric_tag in ifrs_full:
+                        metric_data = ifrs_full[metric_tag]
+                        data_source = "ifrs-full"
+                    
+                    if metric_data:
+                        units = metric_data.get("units", {})
+                        
+                        # 查找美元单位的数据（支持USD和USD/shares）
+                        usd_data = None
+                        if "USD" in units:
+                            usd_data = units["USD"]
+                        elif "USD/shares" in units and metric_key == "earnings_per_share":
+                            # EPS使用USD/shares单位
+                            usd_data = units["USD/shares"]
+                        
+                        if usd_data:
+                            # 首先尝试精确匹配，然后尝试宽松匹配
+                            matched_entry = None
+                            
+                            # 查找指定期间的数据
+                            for entry in usd_data:
+                                form = entry.get("form", "")
+                                fy = entry.get("fy", 0)
+                                fp = entry.get("fp", "")
+                                end_date = entry.get("end", "")
+                                
+                                if not end_date or len(end_date) < 4:
+                                    continue
+                                    
+                                entry_year = int(end_date[:4])
+                                
+                                # 检查表格类型是否匹配
+                                if form in target_forms:
+                                    if quarter:
+                                        # 季度数据匹配
+                                        if entry_year == year and fp == f"Q{quarter}":
+                                            # 如果已有匹配，比较end date，选择最新的
+                                            if matched_entry:
+                                                if entry.get("end", "") > matched_entry.get("end", ""):
+                                                    matched_entry = entry
+                                            else:
+                                                matched_entry = entry
+                                    else:
+                                        # 年度数据匹配 - 优先匹配FY字段
+                                        if fy == year and (fp == "FY" or fp == "" or not fp):
+                                            # 如果已有匹配，比较end date，选择最新的（最近的财年结束日期）
+                                            if matched_entry:
+                                                if entry.get("end", "") > matched_entry.get("end", ""):
+                                                    matched_entry = entry
+                                            else:
+                                                matched_entry = entry
+                                        # 备选：匹配end日期的年份（仅当没有FY匹配时）
+                                        elif not matched_entry and entry_year == year and (fp == "FY" or fp == "" or not fp):
+                                            matched_entry = entry
+                                        # 20-F特殊处理：有些20-F没有FY标记，通过frame字段匹配
+                                        elif not matched_entry and form == "20-F" and "frame" in entry:
+                                            frame = entry.get("frame", "")
+                                            if f"CY{year}" in frame or str(year) in end_date:
+                                                matched_entry = entry
+                            
+                            # 如果季度数据没找到，尝试从年度报告中查找（回退策略）
+                            if not matched_entry and quarter and target_forms_annual:
+                                for entry in usd_data:
+                                    form = entry.get("form", "")
+                                    end_date = entry.get("end", "")
+                                    fp = entry.get("fp", "")
+                                    
+                                    if form in target_forms_annual and end_date:
+                                        # 检查结束日期是否在该季度范围内
+                                        if str(year) in end_date and f"Q{quarter}" in fp:
+                                            matched_entry = entry
+                                            break
+                            
+                            # 应用匹配的数据
+                            if matched_entry:
+                                result[metric_key] = matched_entry.get("val", 0)
+                                # 添加数据来源信息
+                                accn = matched_entry.get('accn', '').replace('-', '')
+                                result["source_url"] = f"https://www.sec.gov/Archives/edgar/data/{cik}/{accn}"
+                                result["source_form"] = matched_entry.get("form", "")
+                                result["data_source"] = data_source
+                                # 添加详细信息
+                                result[f"{metric_key}_details"] = {
+                                    "tag": metric_tag,
+                                    "form": matched_entry.get("form", ""),
+                                    "fy": matched_entry.get("fy", 0),
+                                    "fp": matched_entry.get("fp", ""),
+                                    "val": matched_entry.get("val", 0),
+                                    "start": matched_entry.get("start", ""),
+                                    "end": matched_entry.get("end", ""),
+                                    "accn": matched_entry.get("accn", ""),
+                                    "filed": matched_entry.get("filed", ""),
+                                    "frame": matched_entry.get("frame", ""),
+                                    "data_source": data_source
+                                }
+                        
+                        # 如果找到了数据，就跳出标签循环
+                        if metric_key in result:
+                            break
+            
+            return result
+        except Exception as e:
+            print(f"获取{period}期间财务数据时出错: {e}")
+            return {}
+
+

mcp_client_examples.json

@@ -0,0 +1,490 @@
+{
+  "mcp_server_info": {
+    "name": "SEC Financial Report MCP Server",
+    "description": "FastAPI-based MCP Server for querying SEC EDGAR financial data",
+    "base_url_local": "http://localhost:7860",
+    "base_url_deployed": "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space",
+    "documentation": {
+      "swagger_ui": "/docs",
+      "redoc": "/redoc"
+    }
+  },
+
+  "api_endpoints": {
+
+    "1_search_company": {
+      "name": "Search Company by Name",
+      "endpoint": "/api/search_company",
+      "method": "POST",
+      "description": "Search for a company by name and retrieve its CIK number",
+      
+      "request_example": {
+        "company_name": "NVIDIA"
+      },
+      
+      "response_success": {
+        "cik": "0001045810",
+        "name": "NVIDIA CORP",
+        "ticker": "NVDA",
+        "error": null
+      },
+      
+      "response_not_found": {
+        "cik": null,
+        "name": null,
+        "ticker": null,
+        "error": "No company found matching 'INVALID_COMPANY'"
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/search_company' -H 'Content-Type: application/json' -d '{\"company_name\": \"NVIDIA\"}'",
+      
+      "python_example": "import requests\nresponse = requests.post('https://YOUR_SPACE.hf.space/api/search_company', json={'company_name': 'NVIDIA'})\nprint(response.json())",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/search_company', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({company_name: 'NVIDIA'})\n}).then(r => r.json()).then(console.log)",
+      
+      "notes": [
+        "Returns exact match first, then partial matches",
+        "CIK is zero-padded to 10 digits",
+        "Search is case-insensitive"
+      ]
+    },
+
+    "2_get_company_info": {
+      "name": "Get Company Information",
+      "endpoint": "/api/get_company_info",
+      "method": "POST",
+      "description": "Retrieve detailed company information using CIK",
+      
+      "request_example": {
+        "cik": "0001045810"
+      },
+      
+      "response_success": {
+        "cik": "0001045810",
+        "name": "NVIDIA CORP",
+        "tickers": ["NVDA"],
+        "sic": "3674",
+        "sic_description": "Semiconductors & Related Devices",
+        "error": null
+      },
+      
+      "response_not_found": {
+        "cik": null,
+        "name": null,
+        "tickers": null,
+        "sic": null,
+        "sic_description": null,
+        "error": "No company information found for CIK: 9999999999"
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_company_info' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\"}'",
+      
+      "python_example": "import requests\nresponse = requests.post('https://YOUR_SPACE.hf.space/api/get_company_info', json={'cik': '0001045810'})\ninfo = response.json()\nprint(f\"Company: {info['name']}\")\nprint(f\"Industry: {info['sic_description']}\")",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/get_company_info', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810'})\n}).then(r => r.json()).then(data => console.log(data.name))",
+      
+      "notes": [
+        "CIK must be zero-padded to 10 digits",
+        "SIC code represents industry classification",
+        "Multiple tickers may exist for one company"
+      ]
+    },
+
+    "3_get_company_filings": {
+      "name": "Get Company Filings",
+      "endpoint": "/api/get_company_filings",
+      "method": "POST",
+      "description": "Retrieve company SEC filings with optional form type filter",
+      
+      "request_all_forms": {
+        "cik": "0001045810",
+        "form_types": null
+      },
+      
+      "request_specific_forms": {
+        "cik": "0001045810",
+        "form_types": ["10-K", "10-Q"]
+      },
+      
+      "response_success": {
+        "filings": [
+          {
+            "form_type": "10-K",
+            "filing_date": "2024-02-21",
+            "accession_number": "0001045810-24-000029",
+            "primary_document": "nvda-20240128.htm"
+          },
+          {
+            "form_type": "10-Q",
+            "filing_date": "2024-11-20",
+            "accession_number": "0001045810-24-000147",
+            "primary_document": "nvda-20241027.htm"
+          }
+        ],
+        "error": null
+      },
+      
+      "response_not_found": {
+        "filings": [],
+        "error": "No filings found for CIK: 0001045810"
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_company_filings' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\", \"form_types\": [\"10-K\", \"10-Q\"]}'",
+      
+      "python_example": "import requests\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/get_company_filings',\n    json={'cik': '0001045810', 'form_types': ['10-K', '10-Q']}\n)\nfilings = response.json()['filings']\nfor filing in filings[:5]:\n    print(f\"{filing['form_type']}: {filing['filing_date']}\")",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/get_company_filings', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810', form_types: ['10-K']})\n}).then(r => r.json()).then(data => data.filings.forEach(f => console.log(f.form_type)))",
+      
+      "form_types_reference": {
+        "10-K": "Annual report (US companies)",
+        "10-Q": "Quarterly report (US companies)",
+        "20-F": "Annual report (Foreign private issuers)",
+        "8-K": "Current report (major events)",
+        "S-1": "Registration statement"
+      },
+      
+      "notes": [
+        "Set form_types to null to get all filing types",
+        "Filings are returned in reverse chronological order",
+        "Most companies file multiple forms per year"
+      ]
+    },
+
+    "4_get_company_facts": {
+      "name": "Get Company Financial Facts",
+      "endpoint": "/api/get_company_facts",
+      "method": "POST",
+      "description": "Retrieve complete XBRL financial facts data for a company",
+      
+      "request_example": {
+        "cik": "0001045810"
+      },
+      
+      "response_structure": {
+        "facts": {
+          "us-gaap": {
+            "Revenues": {
+              "label": "Revenues",
+              "description": "Amount of revenue recognized...",
+              "units": {
+                "USD": [
+                  {
+                    "end": "2024-01-28",
+                    "val": 60922000000,
+                    "accn": "0001045810-24-000029",
+                    "fy": 2024,
+                    "fp": "FY",
+                    "form": "10-K",
+                    "filed": "2024-02-21",
+                    "frame": "CY2023"
+                  }
+                ]
+              }
+            },
+            "NetIncomeLoss": "...",
+            "EarningsPerShareBasic": "..."
+          },
+          "ifrs-full": {
+            "Revenue": "..."
+          },
+          "dei": {
+            "EntityCommonStockSharesOutstanding": "..."
+          }
+        },
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_company_facts' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\"}'",
+      
+      "python_example": "import requests\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/get_company_facts',\n    json={'cik': '0001045810'}\n)\nfacts = response.json()['facts']\nprint(f\"Available standards: {list(facts.keys())}\")\nif 'us-gaap' in facts:\n    print(f\"US-GAAP metrics count: {len(facts['us-gaap'])}\")",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/get_company_facts', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810'})\n}).then(r => r.json()).then(data => console.log(Object.keys(data.facts)))",
+      
+      "notes": [
+        "Response can be very large (several MB)",
+        "Contains historical data for all reported periods",
+        "Supports both US-GAAP and IFRS standards",
+        "Best for advanced analysis requiring raw XBRL data"
+      ]
+    },
+
+    "5_get_financial_data_annual": {
+      "name": "Get Annual Financial Data",
+      "endpoint": "/api/get_financial_data",
+      "method": "POST",
+      "description": "Extract key financial metrics for a specific fiscal year",
+      
+      "request_example": {
+        "cik": "0001045810",
+        "period": "2024"
+      },
+      
+      "response_success": {
+        "period": "2024",
+        "total_revenue": 60922000000,
+        "net_income": 29760000000,
+        "earnings_per_share": 12.04,
+        "operating_expenses": 11822000000,
+        "operating_cash_flow": 28091000000,
+        "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000029",
+        "source_form": "10-K",
+        "data_source": "us-gaap",
+        "additional_details": {
+          "total_revenue_details": {
+            "tag": "Revenues",
+            "form": "10-K",
+            "fy": 2024,
+            "fp": "FY",
+            "val": 60922000000,
+            "start": "2023-01-30",
+            "end": "2024-01-28",
+            "accn": "0001045810-24-000029",
+            "filed": "2024-02-21",
+            "frame": "CY2023",
+            "data_source": "us-gaap"
+          }
+        },
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_financial_data' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\", \"period\": \"2024\"}'",
+      
+      "python_example": "import requests\nresponse = requests.post(\n    'https://YOUR_SPACE.hf.space/api/get_financial_data',\n    json={'cik': '0001045810', 'period': '2024'}\n)\ndata = response.json()\nprint(f\"Period: FY{data['period']}\")\nprint(f\"Revenue: ${data['total_revenue']:,.0f}\")\nprint(f\"Net Income: ${data['net_income']:,.0f}\")\nprint(f\"EPS: ${data['earnings_per_share']:.2f}\")\nprint(f\"Source: {data['source_form']}\")",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/api/get_financial_data', {\n  method: 'POST',\n  headers: {'Content-Type': 'application/json'},\n  body: JSON.stringify({cik: '0001045810', period: '2024'})\n}).then(r => r.json()).then(data => {\n  console.log(`Revenue: $${(data.total_revenue / 1e9).toFixed(2)}B`);\n  console.log(`Net Income: $${(data.net_income / 1e9).toFixed(2)}B`);\n})",
+      
+      "notes": [
+        "Period format: 'YYYY' for annual data",
+        "All monetary values in USD (original values)",
+        "EPS is per share value",
+        "Data sourced from 10-K (US) or 20-F (foreign) forms"
+      ]
+    },
+
+    "6_get_financial_data_quarterly": {
+      "name": "Get Quarterly Financial Data",
+      "endpoint": "/api/get_financial_data",
+      "method": "POST",
+      "description": "Extract key financial metrics for a specific quarter",
+      
+      "request_example": {
+        "cik": "0001045810",
+        "period": "2024Q3"
+      },
+      
+      "response_success": {
+        "period": "2024Q3",
+        "total_revenue": 30040000000,
+        "net_income": 19309000000,
+        "earnings_per_share": 7.81,
+        "operating_expenses": 3932000000,
+        "operating_cash_flow": 14502000000,
+        "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581024000147",
+        "source_form": "10-Q",
+        "data_source": "us-gaap",
+        "additional_details": null,
+        "error": null
+      },
+      
+      "curl_example": "curl -X POST 'https://YOUR_SPACE.hf.space/api/get_financial_data' -H 'Content-Type: application/json' -d '{\"cik\": \"0001045810\", \"period\": \"2024Q3\"}'",
+      
+      "python_example": "import requests\n\n# Get multiple quarters for comparison\nquarters = ['2024Q1', '2024Q2', '2024Q3']\nfor quarter in quarters:\n    response = requests.post(\n        'https://YOUR_SPACE.hf.space/api/get_financial_data',\n        json={'cik': '0001045810', 'period': quarter}\n    )\n    data = response.json()\n    if not data.get('error'):\n        print(f\"{quarter}: Revenue ${data['total_revenue']/1e9:.2f}B\")",
+      
+      "javascript_example": "// Compare Q3 vs Q2\nconst periods = ['2024Q3', '2024Q2'];\nPromise.all(periods.map(period =>\n  fetch('https://YOUR_SPACE.hf.space/api/get_financial_data', {\n    method: 'POST',\n    headers: {'Content-Type': 'application/json'},\n    body: JSON.stringify({cik: '0001045810', period})\n  }).then(r => r.json())\n)).then(results => results.forEach(d => \n  console.log(`${d.period}: $${(d.total_revenue/1e9).toFixed(2)}B`)\n))",
+      
+      "quarter_reference": {
+        "Q1": "First quarter (typically Jan-Mar or similar)",
+        "Q2": "Second quarter (typically Apr-Jun or similar)",
+        "Q3": "Third quarter (typically Jul-Sep or similar)",
+        "Q4": "Fourth quarter (typically Oct-Dec or similar)"
+      },
+      
+      "notes": [
+        "Period format: 'YYYYQX' where X is 1, 2, 3, or 4",
+        "Data sourced from 10-Q forms",
+        "Foreign companies (20-F filers) typically don't file quarterly reports",
+        "Quarters may not align with calendar year for all companies"
+      ]
+    },
+
+    "7_health_check": {
+      "name": "Health Check",
+      "endpoint": "/health",
+      "method": "GET",
+      "description": "Check if the MCP server is running and healthy",
+      
+      "request": "No request body required (GET request)",
+      
+      "response": {
+        "status": "healthy",
+        "service": "SEC Financial Report MCP Server"
+      },
+      
+      "curl_example": "curl https://YOUR_SPACE.hf.space/health",
+      
+      "python_example": "import requests\nresponse = requests.get('https://YOUR_SPACE.hf.space/health')\nif response.json()['status'] == 'healthy':\n    print('✓ Server is running')",
+      
+      "javascript_example": "fetch('https://YOUR_SPACE.hf.space/health')\n  .then(r => r.json())\n  .then(data => console.log(`Status: ${data.status}`))",
+      
+      "notes": [
+        "No authentication required",
+        "Use for monitoring and health checks",
+        "Always returns 200 if server is running"
+      ]
+    }
+  },
+
+  "complete_workflow_examples": {
+    
+    "example_1_basic_company_analysis": {
+      "name": "Basic Company Financial Analysis",
+      "description": "Search a company and get its latest annual financial data",
+      "steps": [
+        {
+          "step": 1,
+          "action": "Search for company",
+          "endpoint": "/api/search_company",
+          "request": {
+            "company_name": "Apple"
+          },
+          "extract": "cik"
+        },
+        {
+          "step": 2,
+          "action": "Get company information",
+          "endpoint": "/api/get_company_info",
+          "request": {
+            "cik": "{{cik_from_step_1}}"
+          },
+          "extract": "name, tickers, sic_description"
+        },
+        {
+          "step": 3,
+          "action": "Get latest annual financial data",
+          "endpoint": "/api/get_financial_data",
+          "request": {
+            "cik": "{{cik_from_step_1}}",
+            "period": "2024"
+          },
+          "extract": "total_revenue, net_income, earnings_per_share"
+        }
+      ],
+      "python_code": "import requests\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\n\n# Step 1: Search company\nresponse = requests.post(f'{BASE_URL}/api/search_company', \n                         json={'company_name': 'Apple'})\ncompany = response.json()\ncik = company['cik']\nprint(f\"Found: {company['name']} (CIK: {cik})\")\n\n# Step 2: Get company info\nresponse = requests.post(f'{BASE_URL}/api/get_company_info',\n                         json={'cik': cik})\ninfo = response.json()\nprint(f\"Industry: {info['sic_description']}\")\n\n# Step 3: Get financial data\nresponse = requests.post(f'{BASE_URL}/api/get_financial_data',\n                         json={'cik': cik, 'period': '2024'})\ndata = response.json()\nprint(f\"FY2024 Revenue: ${data['total_revenue']:,.0f}\")\nprint(f\"FY2024 Net Income: ${data['net_income']:,.0f}\")\nprint(f\"FY2024 EPS: ${data['earnings_per_share']:.2f}\")"
+    },
+
+    "example_2_quarterly_trend_analysis": {
+      "name": "Quarterly Revenue Trend Analysis",
+      "description": "Analyze revenue trends across multiple quarters",
+      "steps": [
+        {
+          "step": 1,
+          "action": "Get Q1 2024 data",
+          "endpoint": "/api/get_financial_data",
+          "request": {
+            "cik": "0001045810",
+            "period": "2024Q1"
+          }
+        },
+        {
+          "step": 2,
+          "action": "Get Q2 2024 data",
+          "endpoint": "/api/get_financial_data",
+          "request": {
+            "cik": "0001045810",
+            "period": "2024Q2"
+          }
+        },
+        {
+          "step": 3,
+          "action": "Get Q3 2024 data",
+          "endpoint": "/api/get_financial_data",
+          "request": {
+            "cik": "0001045810",
+            "period": "2024Q3"
+          }
+        }
+      ],
+      "python_code": "import requests\nimport pandas as pd\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\nCIK = '0001045810'  # NVIDIA\n\n# Get quarterly data\nquarters = ['2024Q1', '2024Q2', '2024Q3']\ndata_list = []\n\nfor quarter in quarters:\n    response = requests.post(\n        f'{BASE_URL}/api/get_financial_data',\n        json={'cik': CIK, 'period': quarter}\n    )\n    data = response.json()\n    if not data.get('error'):\n        data_list.append({\n            'Quarter': quarter,\n            'Revenue': data['total_revenue'] / 1e9,  # Convert to billions\n            'Net Income': data['net_income'] / 1e9,\n            'EPS': data['earnings_per_share']\n        })\n\n# Create DataFrame and analyze\ndf = pd.DataFrame(data_list)\nprint(df)\nprint(f\"\\nRevenue Growth Q2->Q3: {((df.iloc[2]['Revenue'] / df.iloc[1]['Revenue']) - 1) * 100:.1f}%\")"
+    },
+
+    "example_3_multi_company_comparison": {
+      "name": "Compare Multiple Companies",
+      "description": "Compare financial metrics across different companies",
+      "companies": ["NVIDIA", "AMD", "Intel"],
+      "python_code": "import requests\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\ncompanies = ['NVIDIA', 'AMD', 'Intel']\nperiod = '2024'\n\nresults = []\nfor company_name in companies:\n    # Search company\n    response = requests.post(\n        f'{BASE_URL}/api/search_company',\n        json={'company_name': company_name}\n    )\n    company = response.json()\n    \n    if not company.get('error'):\n        # Get financial data\n        response = requests.post(\n            f'{BASE_URL}/api/get_financial_data',\n            json={'cik': company['cik'], 'period': period}\n        )\n        data = response.json()\n        \n        if not data.get('error'):\n            results.append({\n                'Company': company['name'],\n                'Revenue (B)': data['total_revenue'] / 1e9,\n                'Net Income (B)': data['net_income'] / 1e9,\n                'EPS': data['earnings_per_share']\n            })\n\n# Print comparison\nfor result in results:\n    print(f\"{result['Company']}:\")\n    print(f\"  Revenue: ${result['Revenue (B)']:.2f}B\")\n    print(f\"  Net Income: ${result['Net Income (B)']:.2f}B\")\n    print(f\"  EPS: ${result['EPS']:.2f}\\n\")"
+    },
+
+    "example_4_filing_history_analysis": {
+      "name": "Analyze Filing History",
+      "description": "Get and analyze a company's filing history",
+      "python_code": "import requests\nfrom datetime import datetime\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\nCIK = '0001045810'\n\n# Get all 10-K filings\nresponse = requests.post(\n    f'{BASE_URL}/api/get_company_filings',\n    json={'cik': CIK, 'form_types': ['10-K']}\n)\nfilings = response.json()['filings']\n\nprint(f\"Found {len(filings)} annual reports (10-K)\\n\")\n\n# Analyze filing dates\nfor filing in filings[:5]:  # Last 5 years\n    filing_date = datetime.strptime(filing['filing_date'], '%Y-%m-%d')\n    print(f\"Form: {filing['form_type']}\")\n    print(f\"Filed: {filing_date.strftime('%B %d, %Y')}\")\n    print(f\"Document: {filing['primary_document']}\")\n    print(f\"Accession: {filing['accession_number']}\")\n    print()"
+    }
+  },
+
+  "error_handling_examples": {
+    
+    "handling_company_not_found": {
+      "scenario": "Company name not found in database",
+      "python_code": "import requests\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\n\nresponse = requests.post(\n    f'{BASE_URL}/api/search_company',\n    json={'company_name': 'INVALID_COMPANY_XYZ'}\n)\nresult = response.json()\n\nif result.get('error'):\n    print(f\"Error: {result['error']}\")\n    # Handle error: ask user to try again, suggest alternatives, etc.\nelse:\n    print(f\"Found: {result['name']}\")"
+    },
+
+    "handling_no_financial_data": {
+      "scenario": "No financial data available for requested period",
+      "python_code": "import requests\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\n\nresponse = requests.post(\n    f'{BASE_URL}/api/get_financial_data',\n    json={'cik': '0001045810', 'period': '1990'}\n)\ndata = response.json()\n\nif data.get('error'):\n    print(f\"No data available: {data['error']}\")\n    # Try different period or notify user\nelif not data.get('total_revenue'):\n    print(\"Warning: Incomplete data for this period\")\n    # Handle partial data\nelse:\n    print(f\"Revenue: ${data['total_revenue']:,.0f}\")"
+    },
+
+    "handling_network_errors": {
+      "scenario": "Handle network errors and timeouts",
+      "python_code": "import requests\nfrom requests.exceptions import RequestException, Timeout\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\n\ntry:\n    response = requests.post(\n        f'{BASE_URL}/api/search_company',\n        json={'company_name': 'NVIDIA'},\n        timeout=10  # 10 seconds timeout\n    )\n    response.raise_for_status()  # Raise error for 4xx/5xx status\n    data = response.json()\n    print(f\"Success: {data['name']}\")\n    \nexcept Timeout:\n    print(\"Request timed out. Server may be slow or unavailable.\")\nexcept RequestException as e:\n    print(f\"Network error occurred: {e}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")"
+    },
+
+    "handling_validation_errors": {
+      "scenario": "Handle request validation errors (422 status)",
+      "python_code": "import requests\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\n\n# Invalid request (missing required field)\nresponse = requests.post(\n    f'{BASE_URL}/api/search_company',\n    json={'wrong_field': 'value'}\n)\n\nif response.status_code == 422:\n    errors = response.json()['detail']\n    print(\"Validation errors:\")\n    for error in errors:\n        field = error['loc'][-1]\n        message = error['msg']\n        print(f\"  - {field}: {message}\")\nelse:\n    data = response.json()\n    print(data)"
+    }
+  },
+
+  "best_practices": {
+    "rate_limiting": {
+      "description": "SEC EDGAR API has rate limits (10 requests per second)",
+      "recommendation": "Add delays between requests when fetching multiple companies",
+      "python_example": "import requests\nimport time\n\nBASE_URL = 'https://YOUR_SPACE.hf.space'\ncompanies = ['NVIDIA', 'AMD', 'Intel', 'TSMC']\n\nfor company in companies:\n    response = requests.post(\n        f'{BASE_URL}/api/search_company',\n        json={'company_name': company}\n    )\n    print(response.json())\n    time.sleep(0.2)  # 200ms delay = max 5 requests/second"
+    },
+
+    "caching_results": {
+      "description": "Cache results to avoid repeated API calls for same data",
+      "python_example": "import requests\nimport json\nfrom pathlib import Path\n\ncache_file = Path('financial_data_cache.json')\n\ndef get_financial_data(cik, period):\n    # Try to load from cache\n    cache = {}\n    if cache_file.exists():\n        cache = json.loads(cache_file.read_text())\n    \n    cache_key = f\"{cik}_{period}\"\n    if cache_key in cache:\n        print(\"Using cached data\")\n        return cache[cache_key]\n    \n    # Fetch from API\n    response = requests.post(\n        'https://YOUR_SPACE.hf.space/api/get_financial_data',\n        json={'cik': cik, 'period': period}\n    )\n    data = response.json()\n    \n    # Save to cache\n    cache[cache_key] = data\n    cache_file.write_text(json.dumps(cache, indent=2))\n    \n    return data"
+    },
+
+    "error_handling": {
+      "description": "Always check for errors in API responses",
+      "python_example": "def safe_api_call(endpoint, payload):\n    try:\n        response = requests.post(endpoint, json=payload, timeout=10)\n        response.raise_for_status()\n        data = response.json()\n        \n        if data.get('error'):\n            print(f\"API Error: {data['error']}\")\n            return None\n        \n        return data\n    except Exception as e:\n        print(f\"Request failed: {e}\")\n        return None\n\n# Usage\nresult = safe_api_call(\n    'https://YOUR_SPACE.hf.space/api/search_company',\n    {'company_name': 'NVIDIA'}\n)\nif result:\n    print(f\"Found: {result['name']}\")"
+    },
+
+    "data_validation": {
+      "description": "Validate data before using it in calculations",
+      "python_example": "def calculate_profit_margin(financial_data):\n    revenue = financial_data.get('total_revenue')\n    net_income = financial_data.get('net_income')\n    \n    # Validate data exists and is valid\n    if not revenue or not net_income:\n        return None\n    if revenue <= 0:\n        return None\n    \n    # Calculate margin\n    margin = (net_income / revenue) * 100\n    return round(margin, 2)\n\n# Usage\ndata = get_financial_data('0001045810', '2024')\nmargin = calculate_profit_margin(data)\nif margin:\n    print(f\"Profit Margin: {margin}%\")\nelse:\n    print(\"Unable to calculate profit margin\")"
+    }
+  },
+
+  "notes": {
+    "data_format": "All monetary values are in USD (original amounts, not scaled)",
+    "eps_format": "Earnings per share is per-share value",
+    "period_formats": {
+      "annual": "YYYY (e.g., '2024')",
+      "quarterly": "YYYYQX (e.g., '2024Q3')"
+    },
+    "supported_forms": {
+      "10-K": "Annual report for US companies",
+      "10-Q": "Quarterly report for US companies",
+      "20-F": "Annual report for foreign private issuers"
+    },
+    "accounting_standards": ["US-GAAP", "IFRS"],
+    "user_agent": "Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)",
+    "rate_limiting": "Follow SEC EDGAR guidelines (10 requests per second)",
+    "documentation_urls": {
+      "swagger_ui": "/docs",
+      "redoc": "/redoc"
+    }
+  }
+}

mcp_server.py

@@ -0,0 +1,312 @@
+"""
+MCP Server for SEC Financial Report Data Query
+Based on FastAPI framework
+"""
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+from edgar_client import EdgarDataClient
+import uvicorn
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="SEC Financial Report MCP Server",
+    description="MCP Server for querying SEC EDGAR financial data",
+    version="1.0.0"
+)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize EDGAR client with user information
+edgar_client = EdgarDataClient(
+    user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
+)
+
+
+# Request/Response Models
+class UserAgentRequest(BaseModel):
+    user_agent: str = Field(
+        default="Financial Report Metrics App (your-email@example.com)",
+        description="User agent string for identifying request source"
+    )
+
+
+class CompanySearchRequest(BaseModel):
+    company_name: str = Field(..., description="Company name to search")
+
+
+class CompanyInfoRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+
+
+class CompanyFilingsRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+    form_types: Optional[List[str]] = Field(
+        None, 
+        description="List of form types (e.g., ['10-K', '10-Q']), None for all types"
+    )
+
+
+class CompanyFactsRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+
+
+class FinancialDataRequest(BaseModel):
+    cik: str = Field(..., description="Company CIK code")
+    period: str = Field(
+        ..., 
+        description="Period in format 'YYYY' or 'YYYYQX' (e.g., '2025' or '2025Q3')"
+    )
+
+
+class CompanySearchResponse(BaseModel):
+    cik: Optional[str] = None
+    name: Optional[str] = None
+    ticker: Optional[str] = None
+    error: Optional[str] = None
+
+
+class CompanyInfoResponse(BaseModel):
+    cik: Optional[str] = None
+    name: Optional[str] = None
+    tickers: Optional[List[str]] = None
+    sic: Optional[str] = None
+    sic_description: Optional[str] = None
+    error: Optional[str] = None
+
+
+class FilingItem(BaseModel):
+    form_type: str
+    filing_date: str
+    accession_number: str
+    primary_document: str
+
+
+class CompanyFilingsResponse(BaseModel):
+    filings: List[FilingItem] = []
+    error: Optional[str] = None
+
+
+class CompanyFactsResponse(BaseModel):
+    facts: Dict[str, Any] = {}
+    error: Optional[str] = None
+
+
+class FinancialDataResponse(BaseModel):
+    period: Optional[str] = None
+    total_revenue: Optional[float] = None
+    net_income: Optional[float] = None
+    earnings_per_share: Optional[float] = None
+    operating_expenses: Optional[float] = None
+    operating_cash_flow: Optional[float] = None
+    source_url: Optional[str] = None
+    source_form: Optional[str] = None
+    data_source: Optional[str] = None
+    additional_details: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+# API Endpoints
+@app.get("/")
+async def root():
+    """Root endpoint with API information"""
+    return {
+        "service": "SEC Financial Report MCP Server",
+        "version": "1.0.0",
+        "description": "MCP Server for querying SEC EDGAR financial data",
+        "endpoints": {
+            "health": "/health",
+            "search_company": "/api/search_company",
+            "get_company_info": "/api/get_company_info",
+            "get_company_filings": "/api/get_company_filings",
+            "get_company_facts": "/api/get_company_facts",
+            "get_financial_data": "/api/get_financial_data"
+        },
+        "user_agent": "Juntao Peng (jtyxabc@gmail.com)"
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {"status": "healthy", "service": "SEC Financial Report MCP Server"}
+
+
+@app.post("/api/search_company", response_model=CompanySearchResponse)
+async def search_company_by_name(request: CompanySearchRequest):
+    """
+    Search company CIK by company name
+    
+    Args:
+        company_name (str): Company name
+        
+    Returns:
+        dict: Dictionary containing company information
+    """
+    try:
+        result = edgar_client.search_company_by_name(request.company_name)
+        
+        if result is None:
+            return CompanySearchResponse(
+                error=f"No company found matching '{request.company_name}'"
+            )
+        
+        return CompanySearchResponse(
+            cik=result.get("cik"),
+            name=result.get("name"),
+            ticker=result.get("ticker")
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/get_company_info", response_model=CompanyInfoResponse)
+async def get_company_info(request: CompanyInfoRequest):
+    """
+    Get basic company information
+    
+    Args:
+        cik (str): Company CIK code
+        
+    Returns:
+        dict: Dictionary containing company information
+    """
+    try:
+        result = edgar_client.get_company_info(request.cik)
+        
+        if result is None:
+            return CompanyInfoResponse(
+                error=f"No company information found for CIK: {request.cik}"
+            )
+        
+        return CompanyInfoResponse(
+            cik=result.get("cik"),
+            name=result.get("name"),
+            tickers=result.get("tickers"),
+            sic=result.get("sic"),
+            sic_description=result.get("sic_description")
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/get_company_filings", response_model=CompanyFilingsResponse)
+async def get_company_filings(request: CompanyFilingsRequest):
+    """
+    Get all company filing documents
+    
+    Args:
+        cik (str): Company CIK code
+        form_types (list): List of form types (e.g., ['10-K', '10-Q']), None for all types
+        
+    Returns:
+        list: List of filing documents
+    """
+    try:
+        result = edgar_client.get_company_filings(request.cik, request.form_types)
+        
+        if not result:
+            return CompanyFilingsResponse(
+                filings=[],
+                error=f"No filings found for CIK: {request.cik}"
+            )
+        
+        filings = [
+            FilingItem(
+                form_type=filing.get("form_type", ""),
+                filing_date=filing.get("filing_date", ""),
+                accession_number=filing.get("accession_number", ""),
+                primary_document=filing.get("primary_document", "")
+            )
+            for filing in result
+        ]
+        
+        return CompanyFilingsResponse(filings=filings)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/get_company_facts", response_model=CompanyFactsResponse)
+async def get_company_facts(request: CompanyFactsRequest):
+    """
+    Get all company financial facts data
+    
+    Args:
+        cik (str): Company CIK code
+        
+    Returns:
+        dict: Company financial facts data
+    """
+    try:
+        result = edgar_client.get_company_facts(request.cik)
+        
+        if not result:
+            return CompanyFactsResponse(
+                facts={},
+                error=f"No financial facts found for CIK: {request.cik}"
+            )
+        
+        return CompanyFactsResponse(facts=result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/get_financial_data", response_model=FinancialDataResponse)
+async def get_financial_data_for_period(request: FinancialDataRequest):
+    """
+    Get financial data for a specific period (supports annual and quarterly)
+    
+    Args:
+        cik (str): Company CIK code
+        period (str): Period in format 'YYYY' or 'YYYYQX' (e.g., '2025' or '2025Q3')
+        
+    Returns:
+        dict: Financial data dictionary
+    """
+    try:
+        result = edgar_client.get_financial_data_for_period(request.cik, request.period)
+        
+        if not result or "period" not in result:
+            return FinancialDataResponse(
+                error=f"No financial data found for CIK: {request.cik}, Period: {request.period}"
+            )
+        
+        # Collect additional details
+        additional_details = {}
+        for key, value in result.items():
+            if key.endswith("_details"):
+                additional_details[key] = value
+        
+        return FinancialDataResponse(
+            period=result.get("period"),
+            total_revenue=result.get("total_revenue"),
+            net_income=result.get("net_income"),
+            earnings_per_share=result.get("earnings_per_share"),
+            operating_expenses=result.get("operating_expenses"),
+            operating_cash_flow=result.get("operating_cash_flow"),
+            source_url=result.get("source_url"),
+            source_form=result.get("source_form"),
+            data_source=result.get("data_source"),
+            additional_details=additional_details if additional_details else None
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    # Run the server
+    uvicorn.run(
+        "mcp_server:app",
+        host="0.0.0.0",
+        port=7860,
+        reload=True
+    )

requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+pydantic==2.5.3
+sec-edgar-api==1.1.0
+requests==2.31.0