Upload 3 files

app.py

@@ -23,44 +23,27 @@ financial_analyzer = FinancialAnalyzer(
     user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
 )
 
-# Define MCP tools with detailed descriptions for LLM
+# Define MCP tools with optimized descriptions for LLM
 @mcp.tool()
 def search_company(company_name: str) -> dict:
     """
-    **STEP 1: START HERE** - Search for a company by name to get its CIK code.
+    [STEP 1] Find company CIK by name/ticker. Always call this FIRST before other tools.
     
-    IMPORTANT: You MUST call this tool FIRST when the user mentions a company name.
-    The CIK code returned by this tool is REQUIRED for all other financial data tools.
-    
-    When to use:
-    - User mentions a company name ("Tesla", "Apple", "Microsoft")
-    - Before calling ANY other tool that requires a CIK parameter
-    - User asks about a company without providing CIK
-    
-    Workflow:
-    1. User asks: "Show me Tesla's financials"
-    2. YOU MUST: Call search_company("Tesla") FIRST
-    3. Get CIK from result: {"cik": "0001318605", ...}
-    4. THEN use that CIK in other tools: extract_financial_metrics("0001318605")
-    
-    Args:
-        company_name: Company name (e.g., "Tesla", "Apple Inc", "Microsoft")
-    
-    Returns:
-        dict with cik (REQUIRED for other tools), name, ticker, sic, sic_description
+    Args: company_name - Company name or ticker (e.g. "Tesla", "TSLA", "google")
+    Returns: {cik, name, ticker} - Use cik for subsequent tool calls
     """
     result = edgar_client.search_company_by_name(company_name)
     return result if result else {"error": f"No company found with name: {company_name}"}
 
 @mcp.tool()
 def get_company_info(cik: str) -> dict:
-    """Get detailed company information."""
+    """Get company details (name, SIC, industry). Requires CIK from search_company."""
     result = edgar_client.get_company_info(cik)
     return result if result else {"error": f"No company found with CIK: {cik}"}
 
 @mcp.tool()
 def get_company_filings(cik: str, form_types: list[str] | None = None) -> dict:
-    """Get list of company SEC filings."""
+    """List SEC filings (10-K, 10-Q, etc). Requires CIK. Use form_types to filter."""
     form_types_tuple = tuple(form_types) if form_types else None
     result = edgar_client.get_company_filings(cik, form_types_tuple)
     if result:
@@ -74,37 +57,24 @@ def get_company_filings(cik: str, form_types: list[str] | None = None) -> dict:
 
 @mcp.tool()
 def get_financial_data(cik: str, period: str) -> dict:
-    """Get financial data for a specific period."""
+    """Get financial data for specific period (e.g. '2024', '2024Q3'). Requires CIK."""
     result = edgar_client.get_financial_data_for_period(cik, period)
     return result if result and "period" in result else {"error": f"No financial data found for CIK: {cik}, Period: {period}"}
 
 @mcp.tool()
 def extract_financial_metrics(cik: str, years: int = 3) -> dict:
     """
-    **RECOMMENDED TOOL** - Extract multi-year financial data (annual + quarterly).
+    [PRIMARY TOOL] Get multi-year financials (annual+quarterly). Includes latest data.
     
-    CRITICAL: This tool requires a valid 10-digit CIK code.
-    If you don't have the CIK, you MUST call search_company() or advanced_search_company() FIRST!
-    
-    When to use:
-    - User asks about financial trends, growth, or multi-period analysis
-    - "Show me [company]'s financials" (most common use case)
-    - Need comprehensive financial overview
-    
-    CORRECT Workflow:
-    1. User: "Show me Tesla's financial metrics"
-    2. YOU: Call search_company("Tesla") → get CIK "0001318605"
-    3. YOU: Call extract_financial_metrics("0001318605", 3)
-    
-    WRONG Workflow (DO NOT DO THIS):
-    ❌ extract_financial_metrics("0001198872") ← Wrong CIK! Will fail!
+    Use for: Any financial query (trends, growth, comparisons, or latest data)
+    Workflow: search_company(name) → extract_financial_metrics(cik, years)
     
     Args:
-        cik: 10-digit CIK code (e.g., "0001318605") from search_company()
-        years: Number of years (1-10, default 3)
+        cik: 10-digit CIK from search_company
+        years: Years to retrieve (1-10, default 3)
     
-    Returns:
-        Multi-year financial data with annual and quarterly metrics
+    Returns: {periods, data: [{period, revenue, net_income, eps, ...}]}
+    Note: Data includes latest year, so no need to call get_latest_financial_data separately.
     """
     if years < 1 or years > 10:
         return {"error": "Years parameter must be between 1 and 10"}
@@ -118,28 +88,11 @@ def extract_financial_metrics(cik: str, years: int = 3) -> dict:
 @mcp.tool()
 def get_latest_financial_data(cik: str) -> dict:
     """
-    Get the most recent financial snapshot (latest annual report only).
-    
-    CRITICAL: This tool requires a valid 10-digit CIK code.
-    If you don't have the CIK, you MUST call search_company() or advanced_search_company() FIRST!
+    Get ONLY most recent annual report. Use extract_financial_metrics instead (it includes latest).
     
-    When to use:
-    - User asks for "latest" or "most recent" financial data
-    - Quick snapshot of current financial status
-    
-    CORRECT Workflow:
-    1. User: "What's Tesla's latest financial data?"
-    2. YOU: Call search_company("Tesla") → get CIK "0001318605"
-    3. YOU: Call get_latest_financial_data("0001318605")
-    
-    WRONG Workflow (DO NOT DO THIS):
-    ❌ get_latest_financial_data("0001198872") ← Wrong CIK! Will fail!
-    
-    Args:
-        cik: 10-digit CIK code (e.g., "0001318605") from search_company()
-    
-    Returns:
-        Latest annual financial data
+    Only use when: User explicitly wants ONLY the latest snapshot (rare case).
+    Args: cik - 10-digit CIK from search_company
+    Returns: {period, revenue, net_income, eps, ...}
     """
     result = financial_analyzer.get_latest_financial_data(cik)
     return result if result and "period" in result else {"error": f"No latest financial data found for CIK: {cik}"}
@@ -147,20 +100,10 @@ def get_latest_financial_data(cik: str) -> dict:
 @mcp.tool()
 def advanced_search_company(company_input: str) -> dict:
     """
-    **ALTERNATIVE TO search_company** - Flexible search supporting company name or CIK.
-    
-    Use this when:
-    - You need to find a company's CIK before calling other tools
-    - User provides either a company name OR a CIK code
-    - You want a single tool that handles both search types
-    
-    This tool returns the SAME format as search_company(), including the CIK needed for other tools.
-    
-    Args:
-        company_input: Company name OR CIK code
+    Alternative to search_company. Accepts company name OR CIK. Same output format.
     
-    Returns:
-        dict with cik (REQUIRED for other tools), name, ticker
+    Args: company_input - Name, ticker, or CIK
+    Returns: {cik, name, ticker}
     """
     result = financial_analyzer.search_company(company_input)
     return result if not result.get("error") else {"error": result["error"]}

edgar_client.py

@@ -470,7 +470,7 @@ class EdgarDataClient:
     
     def get_financial_data_for_period(self, cik, period):
         """
-        Get financial data for a specific period (supports annual and quarterly)
+        Get financial data for a specific period (supports annual and quarterly) - Cached
         
         Args:
             cik (str): Company CIK code
@@ -482,6 +482,14 @@ class EdgarDataClient:
         if not self.edgar:
             print("sec_edgar_api library not installed")
             return {}
+        
+        # 实例级缓存（避免重复计算）
+        cache_key = f"period_{cik}_{period}"
+        if hasattr(self, '_period_cache') and cache_key in self._period_cache:
+            return self._period_cache[cache_key]
+        
+        if not hasattr(self, '_period_cache'):
+            self._period_cache = {}
             
         try:
             # Get company financial facts
@@ -683,6 +691,10 @@ class EdgarDataClient:
                         if metric_key in result:
                             break
             
+            # 缓存结果
+            if result and "period" in result:
+                self._period_cache[cache_key] = result
+            
             return result
         except Exception as e:
             print(f"Error getting financial data for period {period}: {e}")

financial_analyzer.py

@@ -2,6 +2,7 @@
 
 from edgar_client import EdgarDataClient
 from datetime import datetime
+from functools import lru_cache
 import json
 
 
@@ -14,6 +15,9 @@ class FinancialAnalyzer:
             user_agent (str): User agent string for identifying request source
         """
         self.edgar_client = EdgarDataClient(user_agent)
+        # 新增：实例级缓存，进一步提升性能
+        self._search_cache = {}
+        self._extract_metrics_cache = {}  # 缓存 extract_financial_metrics 结果
         
     def search_company(self, company_input):
         """
@@ -25,11 +29,16 @@ class FinancialAnalyzer:
         Returns:
             dict: Company information
         """
+        # 实例级缓存检查
+        if company_input in self._search_cache:
+            return self._search_cache[company_input]
+        
         # If input is numeric, assume it's a CIK
         if company_input.isdigit() and len(company_input) >= 8:
             # Get company information from cache (will use @lru_cache)
             company_info = self.edgar_client.get_company_info(company_input)
             if company_info:
+                self._search_cache[company_input] = company_info
                 return company_info
             else:
                 return {"error": "Company not found for specified CIK"}
@@ -43,12 +52,14 @@ class FinancialAnalyzer:
                 
                 # For basic searches, the ticker data is sufficient
                 # This eliminates the 3-5 second delay from get_company_info
-                return {
+                result = {
                     "cik": company['cik'],
                     "name": company['name'],
                     "tickers": [company['ticker']] if company.get('ticker') else [],
                     "_source": "company_tickers_cache"  # Debug info
                 }
+                self._search_cache[company_input] = result
+                return result
             else:
                 return {"error": "No matching company found"}
     
@@ -77,6 +88,11 @@ class FinancialAnalyzer:
         Returns:
             list: List of financial data
         """
+        # 实例级缓存检查（避免重复计算）
+        cache_key = f"{cik}_{years}"
+        if cache_key in self._extract_metrics_cache:
+            return self._extract_metrics_cache[cache_key]
+        
         financial_data = []
         
         # Step 1: Get company facts ONCE (will be cached)
@@ -189,6 +205,10 @@ class FinancialAnalyzer:
                 
                 financial_data.append(data)
         
+        # 缓存结果
+        if financial_data:
+            self._extract_metrics_cache[cache_key] = financial_data
+        
         return financial_data
     
     def get_latest_financial_data(self, cik):