Upload mcp_server_fastmcp.py

mcp_server_fastmcp.py

@@ -16,20 +16,38 @@ financial_analyzer = FinancialAnalyzer(
     user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"
 )
 
-# Create FastMCP server with pure JSON response
-mcp = FastMCP("sec-financial-data", json_response=True)
+# Create FastMCP server with pure JSON response and stateless HTTP
+mcp = FastMCP("sec-financial-data", json_response=True, stateless_http=True)
 
 
 @mcp.tool()
 def search_company(company_name: str) -> dict:
     """
-    Search for a company by name in SEC EDGAR database.
+    Search for a company by name in the SEC EDGAR database. Use this tool when the user mentions 
+    a company name or asks about a company without providing its CIK code. This tool will find the 
+    company's official information needed for other financial queries.
+    
+    When to use:
+    - User mentions a company name (e.g., "Tesla", "Apple", "Microsoft")
+    - Need to find a company's CIK code for other tool calls
+    - User asks "tell me about [company name]"
+    - Need to verify company ticker symbols
+    
+    Examples:
+    - "Search for Tesla" → Returns Tesla's CIK, ticker (TSLA), and industry info
+    - "Find Apple" → Returns Apple's CIK, ticker (AAPL), and classification
+    - "What's Microsoft's CIK?" → Returns CIK code and full company details
     
     Args:
-        company_name: Company name to search (e.g., Microsoft, Apple, Tesla)
+        company_name: Company name to search (e.g., "Microsoft", "Apple Inc", "Tesla Motors")
     
     Returns:
-        dict: Company information including CIK, name, and ticker symbol
+        dict: Company information containing:
+              - cik: Company Central Index Key (unique identifier needed for other tools)
+              - name: Official company name registered with SEC
+              - tickers: Stock ticker symbol(s) (e.g., ["TSLA"], ["AAPL"])
+              - sic: Standard Industrial Classification code
+              - sic_description: Industry/sector description
     """
     result = edgar_client.search_company_by_name(company_name)
     if result:
@@ -41,13 +59,19 @@ def search_company(company_name: str) -> dict:
 @mcp.tool()
 def get_company_info(cik: str) -> dict:
     """
-    Get detailed company information including name, tickers, SIC code, and industry description.
+    Get detailed company information using CIK code. Use this when you already have a company's 
+    CIK code and need to retrieve or verify its official details.
+    
+    When to use:
+    - Already have a CIK code from search_company
+    - Need to verify company details
+    - User provides a CIK code directly
     
     Args:
-        cik: Company CIK code (10-digit format, e.g., 0000789019)
+        cik: Company CIK code in 10-digit format (e.g., "0000789019" for Microsoft)
     
     Returns:
-        dict: Company information
+        dict: Detailed company information including name, tickers, SIC code, and industry description
     """
     result = edgar_client.get_company_info(cik)
     if result:
@@ -59,14 +83,32 @@ def get_company_info(cik: str) -> dict:
 @mcp.tool()
 def get_company_filings(cik: str, form_types: list[str] | None = None) -> dict:
     """
-    Get list of company SEC filings (10-K, 10-Q, 20-F, etc.) with filing dates and document links.
+    Get a list of SEC filings for a company. SEC filings are official documents companies must 
+    submit, including annual reports (10-K), quarterly reports (10-Q), and foreign company 
+    annual reports (20-F). Use this to see what reports are available or to get filing dates.
+    
+    When to use:
+    - User asks "what reports has [company] filed?"
+    - Need to see filing history or dates
+    - Want to know what documents are available
+    - Checking if specific report types exist
+    
+    Common form types:
+    - 10-K: Annual report (comprehensive yearly financial statement)
+    - 10-Q: Quarterly report (financial updates every 3 months)
+    - 20-F: Annual report for foreign companies
+    - 8-K: Current report (major events/changes)
     
     Args:
         cik: Company CIK code
-        form_types: Optional filter by form types (e.g., [10-K, 10-Q])
+        form_types: Optional list to filter by specific form types (e.g., ["10-K", "10-Q"])
+                   If None, returns all filing types
     
     Returns:
-        dict: Filings list with total count and limited results
+        dict: Filing information containing:
+              - total: Total number of filings found
+              - returned: Number of filings in response (max 20)
+              - filings: List of filing details with dates, form types, and document links
     """
     result = edgar_client.get_company_filings(cik, form_types)
     if result:
@@ -83,14 +125,33 @@ 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 including revenue, net income, EPS, operating expenses, and cash flow.
+    Get financial data for a specific time period (year or quarter). Use this when the user asks 
+    about financials for a particular period, like "2024 results" or "Q3 2024 performance".
+    
+    When to use:
+    - User specifies a particular year (e.g., "2024 financials")
+    - User asks about a specific quarter (e.g., "Q3 2024 results")
+    - Need data for a single, specific time period
+    - Comparing specific periods (call multiple times)
+    
+    Period format:
+    - Annual: "YYYY" (e.g., "2024" for fiscal year 2024)
+    - Quarterly: "YYYYQX" (e.g., "2024Q3" for Q3 of 2024, "2023Q4" for Q4 of 2023)
     
     Args:
         cik: Company CIK code
-        period: Period in format YYYY for annual or YYYYQX for quarterly (e.g., 2024, 2024Q3)
+        period: Time period in format "YYYY" for annual or "YYYYQX" for quarterly
+                Examples: "2024", "2023", "2024Q3", "2023Q4"
     
     Returns:
-        dict: Financial data for the specified period
+        dict: Financial metrics for the specified period including:
+              - total_revenue: Total sales/revenue for the period
+              - net_income: Profit (or loss) after all expenses
+              - earnings_per_share: Profit per share of stock (EPS)
+              - operating_expenses: Costs of running business operations
+              - operating_cash_flow: Cash generated from business operations
+              - source_url: Link to the SEC filing document
+              - source_form: Type of SEC form (10-K, 10-Q, or 20-F)
     """
     result = edgar_client.get_financial_data_for_period(cik, period)
     if result and "period" in result:
@@ -102,15 +163,52 @@ def get_financial_data(cik: str, period: str) -> dict:
 @mcp.tool()
 def extract_financial_metrics(cik: str, years: int = 3) -> dict:
     """
-    Extract comprehensive financial metrics for multiple years including both annual and quarterly data.
-    Returns data in chronological order (newest first): FY -> Q4 -> Q3 -> Q2 -> Q1.
+    Extract comprehensive financial metrics spanning multiple years with both annual and quarterly 
+    data. This is the MOST POWERFUL tool for financial analysis - it returns complete multi-year 
+    trends including all quarters. Perfect for understanding company performance over time, 
+    identifying growth patterns, and comprehensive financial analysis.
+    
+    When to use (RECOMMENDED for most financial analysis):
+    - User asks about "trends over time"
+    - Questions about "growth", "performance over years"
+    - "Show me [company]'s financials" (without specifying a period)
+    - Comparative analysis needs
+    - "How has [company] been doing?"
+    - ANY request for multiple periods of data
+    
+    What makes this tool special:
+    - Returns BOTH annual (FY) and quarterly (Q1-Q4) data
+    - Sorted newest to oldest (FY2024 → Q4 → Q3 → Q2 → Q1 → FY2023...)
+    - Includes multiple years in one call (saves time)
+    - Ideal for trend analysis and year-over-year comparisons
+    
+    Example use cases:
+    - "Show Tesla's financial trends for 3 years" → Perfect use case
+    - "How has Apple's revenue grown?" → Use this (default 3 years)
+    - "Compare Microsoft's quarterly performance" → Returns all quarters
+    - "What are Amazon's financial metrics?" → Comprehensive overview
     
     Args:
         cik: Company CIK code
         years: Number of recent years to extract (1-10, default: 3)
+               - 3 years = ~15 data points (3 annual + ~12 quarterly)
+               - 5 years = ~25 data points (5 annual + ~20 quarterly)
+               - More years = more comprehensive trend analysis
     
     Returns:
-        dict: Financial metrics with periods and data
+        dict: Comprehensive financial dataset containing:
+              - periods: Total number of time periods returned
+              - data: List of financial records, each with:
+                * period: Time identifier (e.g., "FY2024", "2024Q3", "2023Q1")
+                * total_revenue: Company's total sales/revenue for that period
+                * net_income: Profit after all expenses (can be negative for losses)
+                * earnings_per_share: Profit per share of stock (EPS)
+                * operating_expenses: Costs of running the business
+                * operating_cash_flow: Actual cash generated from operations
+                * source_url: Link to SEC filing document
+                * source_form: SEC form type (10-K for annual, 10-Q for quarterly)
+              
+              Data is sorted newest first: FY2024 → 2024Q4 → 2024Q3 → 2024Q2 → 2024Q1 → FY2023...
     """
     if years < 1 or years > 10:
         return {"error": "Years parameter must be between 1 and 10"}
@@ -165,13 +263,40 @@ 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 data available for a company.
+    Get the most recent financial snapshot for a company - returns only the latest annual report 
+    data. Use this for quick checks of current financial status or when the user asks about 
+    "latest" or "most recent" results without needing historical data.
+    
+    When to use:
+    - User asks "what are [company]'s latest financials?"
+    - "How is [company] doing currently?"
+    - "Show me [company]'s most recent results"
+    - Quick status check without historical context
+    - Need just the newest data point (faster than extract_financial_metrics)
+    
+    What this returns:
+    - Only the most recent ANNUAL (fiscal year) data
+    - Does NOT include quarterly breakdowns
+    - Fastest way to get current snapshot
+    
+    Examples:
+    - "What's Tesla's latest revenue?" → Returns most recent annual revenue
+    - "How much did Apple earn recently?" → Returns latest annual net income
+    - "Show me Microsoft's current financials" → Returns latest fiscal year data
     
     Args:
         cik: Company CIK code
     
     Returns:
-        dict: Latest financial data
+        dict: Latest financial data from most recent fiscal year including:
+              - period: The fiscal year (e.g., "FY2024")
+              - total_revenue: Most recent annual revenue
+              - net_income: Most recent annual profit
+              - earnings_per_share: Latest annual EPS
+              - operating_expenses: Latest annual operating costs
+              - operating_cash_flow: Latest annual cash from operations
+              - source_url: Link to the SEC filing
+              - source_form: SEC form type (usually 10-K or 20-F)
     """
     result = financial_analyzer.get_latest_financial_data(cik)
     if result and "period" in result:
@@ -183,13 +308,37 @@ def get_latest_financial_data(cik: str) -> dict:
 @mcp.tool()
 def advanced_search_company(company_input: str) -> dict:
     """
-    Advanced search supporting both company name and CIK code. Automatically detects input type.
+    Flexible smart search that accepts ANY type of company identifier - company name, stock ticker 
+    symbol (like TSLA, AAPL, MSFT), or CIK code. The tool automatically detects what type of 
+    identifier you provide. Use this when you're uncertain what type of identifier the user gave.
+    
+    When to use:
+    - User provides just a ticker symbol (e.g., "TSLA", "AAPL")
+    - Unclear if user gave name, ticker, or CIK
+    - Want most flexible search option
+    - User input could be any identifier type
+    
+    What it accepts:
+    - Company names: "Tesla", "Apple Inc", "Microsoft Corporation"
+    - Ticker symbols: "TSLA", "AAPL", "MSFT", "GOOGL"
+    - CIK codes: "0001318605", "0000320193"
+    
+    Examples:
+    - Input: "TSLA" → Recognizes as ticker, returns Tesla info
+    - Input: "Tesla" → Searches by name, returns Tesla info
+    - Input: "0001318605" → Recognizes as CIK, returns Tesla info
+    - Input: "AAPL" → Returns Apple information
     
     Args:
-        company_input: Company name, ticker, or CIK code
+        company_input: Any company identifier - name ("Tesla"), ticker ("TSLA"), or CIK ("0001318605")
     
     Returns:
-        dict: Company information
+        dict: Complete company information including:
+              - cik: Company's Central Index Key
+              - name: Official registered company name
+              - tickers: Stock ticker symbol(s)
+              - sic: Standard Industrial Classification code
+              - sic_description: Industry/sector description
     """
     result = financial_analyzer.search_company(company_input)
     if result.get("error"):
@@ -216,5 +365,5 @@ if __name__ == "__main__":
     
     uvicorn.Config.__init__ = patched_init
     
-    # Run FastMCP with SSE transport (it will use our patched config)
-    mcp.run(transport="sse")
+    # Run FastMCP with HTTP transport (stateless mode)
+    mcp.run(transport="http")