Upload README.md

README.md

@@ -1,132 +1,137 @@
----
-title: SEC Financial Report MCP Server
-emoji: 📊
-colorFrom: blue
-colorTo: green
-sdk: docker
-pinned: true
-license: mit
-app_port: 7860
-short_description: MCP Server for querying SEC EDGAR financial data
----
-
-# 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
-
-### Basic 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
-
-### Advanced Endpoints (FinancialAnalyzer)
-- `POST /api/advanced_search` - Advanced search (supports name or CIK)
-- `POST /api/extract_financial_metrics` - Extract multi-year metrics
-- `POST /api/get_latest_financial_data` - Get latest annual data
-
-## 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)
-
-## Service Infrastructure
-
-### Production Configuration
-
-- **Platform**: Hugging Face Spaces with CPU Upgrade
-- **Always-On**: Enabled (Don't Sleep mode)
-- **Process**: Single Uvicorn worker (optimized for HF Spaces)
-- **Health Check**: Automatic monitoring every 30 seconds
-- **Timeout**: 75s keep-alive for stable connections
-- **Concurrency**: Up to 200 concurrent requests
-
-### Performance Characteristics
-
-- **Uptime**: 99.9% (always-on mode)
-- **Response Time**: <200ms for cached queries, 1-3s for fresh SEC data
-- **Rate Limit**: Follows SEC guidelines (10 requests/second max)
-- **Data Freshness**: Real-time from SEC EDGAR
-
-### Monitoring
-
-**Health Check Endpoint:**
-```bash
-curl https://jc321-easyreportdatemcp.hf.space/health
-```
-
-Expected response:
-```json
-{
-  "status": "healthy",
-  "service": "SEC Financial Report MCP Server"
-}
-```
-
-**Service Information:**
-```bash
-curl https://jc321-easyreportdatemcp.hf.space/
-```
-
-Returns complete API metadata including all endpoints, usage examples, and workflows.
+---
+title: SEC Financial Report MCP Server
+emoji: 📊
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: true
+license: mit
+app_port: 7860
+short_description: MCP Server for querying SEC EDGAR financial data
+---
+
+# 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
+
+### Basic 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
+
+### Advanced Endpoints (FinancialAnalyzer)
+- `POST /api/advanced_search` - Advanced search (supports name or CIK)
+- `POST /api/extract_financial_metrics` - Extract multi-year metrics
+- `POST /api/get_latest_financial_data` - Get latest annual data
+
+## Usage Example
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_SPACE_URL.hf.space"
+
+# IMPORTANT: Use adequate timeout (at least 120 seconds)
+# First request after service restart may take 30-60 seconds
+
+# Search company
+response = requests.post(
+    f"{BASE_URL}/api/search_company",
+    json={"company_name": "NVIDIA"},
+    timeout=120  # Important!
+)
+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"},
+    timeout=120  # Important!
+)
+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)
+
+## Service Infrastructure
+
+### Production Configuration
+
+- **Platform**: Hugging Face Spaces with CPU Upgrade
+- **Always-On**: Enabled (Don't Sleep mode)
+- **Process**: Single Uvicorn worker (optimized for HF Spaces)
+- **Health Check**: Automatic monitoring every 30 seconds
+- **Timeout**: 75s keep-alive for stable connections
+- **Concurrency**: Up to 200 concurrent requests
+
+### Performance Characteristics
+
+- **Uptime**: 99.9% (always-on mode)
+- **Response Time**: <200ms for cached queries, 1-3s for fresh SEC data
+- **Rate Limit**: Follows SEC guidelines (10 requests/second max)
+- **Data Freshness**: Real-time from SEC EDGAR
+
+### Monitoring
+
+**Health Check Endpoint:**
+```bash
+curl https://jc321-easyreportdatemcp.hf.space/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "service": "SEC Financial Report MCP Server"
+}
+```
+
+**Service Information:**
+```bash
+curl https://jc321-easyreportdatemcp.hf.space/
+```
+
+Returns complete API metadata including all endpoints, usage examples, and workflows.