Upload mcp_server.py

mcp_server.py

@@ -143,23 +143,127 @@ class MetricsListResponse(BaseModel):
 # API Endpoints
 @app.get("/")
 async def root():
-    """Root endpoint with API information"""
+    """Root endpoint with API information and usage guide"""
     return {
         "service": "SEC Financial Report MCP Server",
         "version": "1.0.0",
-        "description": "MCP Server for querying SEC EDGAR financial data",
+        "description": "MCP Server for querying SEC EDGAR financial data - A tool-ready API for AI agents and applications",
+        "status": "operational",
+        "user_agent": "Juntao Peng (jtyxabc@gmail.com)",
+        
+        "quick_start": {
+            "interactive_docs": "/docs",
+            "api_documentation": "/redoc",
+            "health_check": "/health",
+            "example_usage": {
+                "step_1": "Search company: POST /api/advanced_search with {\"company_input\": \"NVIDIA\"}",
+                "step_2": "Get latest data: POST /api/get_latest_financial_data with {\"cik\": \"0001045810\"}",
+                "step_3": "Get trends: POST /api/extract_financial_metrics with {\"cik\": \"0001045810\", \"years\": 3}"
+            }
+        },
+        
         "endpoints": {
-            "health": "/health",
-            "search_company": "/api/search_company",
-            "advanced_search": "/api/advanced_search",
-            "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",
-            "extract_financial_metrics": "/api/extract_financial_metrics",
-            "get_latest_financial_data": "/api/get_latest_financial_data"
+            "basic_tools": {
+                "search_company": {
+                    "path": "/api/search_company",
+                    "method": "POST",
+                    "description": "Search company by name only",
+                    "input": {"company_name": "string"}
+                },
+                "get_company_info": {
+                    "path": "/api/get_company_info",
+                    "method": "POST",
+                    "description": "Get company information by CIK",
+                    "input": {"cik": "string"}
+                },
+                "get_company_filings": {
+                    "path": "/api/get_company_filings",
+                    "method": "POST",
+                    "description": "Get company SEC filings (10-K, 10-Q, 20-F)",
+                    "input": {"cik": "string", "form_types": "array or null"}
+                },
+                "get_company_facts": {
+                    "path": "/api/get_company_facts",
+                    "method": "POST",
+                    "description": "Get complete XBRL financial facts",
+                    "input": {"cik": "string"}
+                },
+                "get_financial_data": {
+                    "path": "/api/get_financial_data",
+                    "method": "POST",
+                    "description": "Get financial data for specific period",
+                    "input": {"cik": "string", "period": "YYYY or YYYYQX"}
+                },
+                "health": {
+                    "path": "/health",
+                    "method": "GET",
+                    "description": "Server health check"
+                }
+            },
+            
+            "advanced_tools": {
+                "advanced_search": {
+                    "path": "/api/advanced_search",
+                    "method": "POST",
+                    "description": "Smart search - accepts company name OR CIK",
+                    "input": {"company_input": "string"},
+                    "recommended": true
+                },
+                "extract_financial_metrics": {
+                    "path": "/api/extract_financial_metrics",
+                    "method": "POST",
+                    "description": "Extract multi-year metrics (annual + quarterly)",
+                    "input": {"cik": "string", "years": "integer (1-10)"},
+                    "recommended": true
+                },
+                "get_latest_financial_data": {
+                    "path": "/api/get_latest_financial_data",
+                    "method": "POST",
+                    "description": "Get most recent annual financial data automatically",
+                    "input": {"cik": "string"},
+                    "recommended": true
+                }
+            }
         },
-        "user_agent": "Juntao Peng (jtyxabc@gmail.com)"
+        
+        "usage_guide": {
+            "for_ai_agents": "Use advanced_search → get_latest_financial_data for quick queries. Use extract_financial_metrics for trend analysis.",
+            "for_developers": "Visit /docs for interactive API testing with Swagger UI",
+            "data_source": "US SEC EDGAR system (real-time)",
+            "supported_forms": ["10-K (annual)", "10-Q (quarterly)", "20-F (foreign annual)"],
+            "rate_limit": "Follow SEC guidelines: 10 requests/second"
+        },
+        
+        "example_workflows": [
+            {
+                "name": "Get Latest Company Financials",
+                "steps": [
+                    "POST /api/advanced_search {\"company_input\": \"Apple\"}",
+                    "POST /api/get_latest_financial_data {\"cik\": \"<from_step_1>\"}"
+                ]
+            },
+            {
+                "name": "Analyze 5-Year Trends",
+                "steps": [
+                    "POST /api/advanced_search {\"company_input\": \"TSMC\"}",
+                    "POST /api/extract_financial_metrics {\"cik\": \"<from_step_1>\", \"years\": 5}"
+                ]
+            },
+            {
+                "name": "Get Specific Quarter Data",
+                "steps": [
+                    "POST /api/advanced_search {\"company_input\": \"NVIDIA\"}",
+                    "POST /api/get_financial_data {\"cik\": \"<from_step_1>\", \"period\": \"2024Q3\"}"
+                ]
+            }
+        ],
+        
+        "links": {
+            "interactive_docs": "/docs",
+            "redoc": "/redoc",
+            "github": "https://github.com/JC321/EasyReportDateMCP",
+            "huggingface_space": "https://huggingface.co/spaces/JC321/EasyReportDateMCP"
+        }
     }