Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
Easy-Financial-Report
Running

App Files Community
Easy-Financial-Report / README.md
JC321's picture
JC321
Upload README.md
982da0c verified
preview code
|
raw
history blame
8.31 kB
metadata
license: mit
title: 'Easy Financial Report '
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
emoji: 🚀
colorFrom: red
colorTo: red
pinned: true
hf_oauth: true
hf_oauth_scopes:
  - inference-api
short_description: An AI-driven financial intelligence platform
tags:
  - mcp-in-action-track-consumer
  - building-mcp-track-consumer
  - ai-finance
  - agentic
  - mcp
  - model-context-protocol
  - context-management
  - fastmcp
  - gradio
  - consumer
  - Qwen

📊 Easy Financial Report

🎥 Demo working Video:: [Link to be added]
🌐 Social media -LinkedIn Post: [Link to be added]

🤖 Autonomous Agent Architecture

Built as a Gradio application, Easy Financial Report is powered by two self-developed MCP servers and autonomous agents.

How the Agent Thinks & Acts

  1. Intent Recognition: Classifies user input into tool-based or conversational intent.
  2. Dynamic Tool Planning: Generates a JSON execution plan like:
{
  "plan": [
    {"tool": "search_company", "arguments": {"company_name": "Tesla"}},
    {"tool": "get_financial_data", "arguments": {"cik": "0001318605", "period": "2025Q1"}},
    {"tool": "get_quote", "arguments": {"symbol": "TSLA"}}
  ]
}

  1. Context-Aware Execution: Reuses context data to avoid redundant calls.

  2. Stateful Dialogue: Maintains structured context across turns:

agent_context = {
    'last_company_cik': '0001652044',
    'last_company_name': 'Alibaba Group',
    'last_company_ticker': 'BABA',
    'last_financial_data': {'revenue': 280000000000, 'net_income': 15000000000},
    'last_stock_quote': {'price': 125.42, 'change': 2.15}
}

Error Recovery: Detects missing data, auto-corrects CIKs/tickers, and guides users with actionable suggestions. This creates a closed-loop cognitive system — not just a chatbot, but an analyst that plans, reasoning and execution.

⚙️ Dual Specialized MCP Service Architecture

We implement two purpose-built MCP services to handle different financial data domains:

Service Purpose Transport Key Tools
EasyReportDataMCP SEC financial report intelligence stdio (local MCP process via JSON-RPC 2.0) search_company, get_company_info, get_company_filings, get_financial_data, extract_financial_metrics, get_latest_financial_data, advanced_search_company
MarketandStockMCP Real-time market data & news Gradio API (remote SSE via https://jc321-marketandstockmcp.hf.space) get_quote, get_market_news, get_company_news

🔍 Data Structure Examples

EasyReportDataMCP Response (structured SEC data):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"cik\":\"0001318605\",\"name\":\"TESLA, INC.\",\"tickers\":[\"TSLA\"],\"sic\":\"3711\"}"
      }
    ]
  }
}

MarketandStockMCP Response (real-time market data):

{
  "symbol": "AAPL",
  "price": 198.45,
  "change": 2.34,
  "change_percent": 1.19,
  "volume": 45678900
}

The agent intelligently orchestrates both services in unified workflows—e.g., fetch SEC financials + get current stock quote + retrieve latest company news.

🧠 Advanced Agent Intelligence Features

Feature Implementation Impact
Context Engineering Multi-turn state stored in gr.State; follow-ups reuse real financial data Eliminates re-querying; enables deep analysis chains
RAG over SEC Filings Retrieved during chat Answers grounded in actual 10-K/10-Q/20-F content
Streaming UX Real-time progress indicators + LLM token streaming Users see “thinking in action”, not blank loading
Robust Error Handling Auto-CIK/ticker correction, incomplete-data detection, user-friendly guidance Professional resilience—no silent failures
Performance Diagnostics Timing logs for every MCP call (e.g., 0.037s total) Transparent, debuggable, production-ready

🖥️ App Overview – A Polished Gradio Experience

Just type or select a company (e.g., Apple) — and instantly get:

1️⃣ 📈 Financial Data & Market News Dashboard

  • Real-time Stock Stats: Open, High, Low, Previous Close, Volume (via get_quote)
  • Latest Quarter Metrics: Revenue, Net Income, EPS, Operating Expenses, Operating Cash Flow (via extract_financial_metrics)
  • 3-Year Trend Table: Income statement & cash flow (YoY)
  • Financial Reports: Links of 10-K, 10-Q, 20-F and etc from SEC(via extract_financial_metrics).
  • Live Financial News: Policy updates, earnings reactions (via get_market_news)

All sourced from official SEC filings and market APIs — zero hallucination guaranteed.

2️⃣ 📋 Investment Recommendations

Generated via a multi-step autonomous workflow:

  • MCP Tools:EasyReportDataMCP, MarketandStockMCP.
  1. Search company
  2. Fetch SEC filings
  3. Get current quote
  4. Retrieve latest news
  5. Synthesize report

Includes:

  • Entry / Exit price ranges
  • Stop-loss & take-profit levels
  • Holding horizon (short-term <1mo / long-term >1mo)

3️⃣ 📊 Analysis Report Tab

Deep dive into:

  • MCP Tools:EasyReportDataMCP, MarketandStockMCP.
  • Company Snapshot: Business model, sector, key products
  • Core Investment Theses: Growth drivers, competitive edge
  • Key Risks & Mitigation: Regulatory, execution, market risks
  • Latest Company News: Recent developments affecting valuation

4️⃣ 💬 Financial Assistant Chatbot

A fully autonomous agent that:

  • Plans, reasons, and executes MCP tool calls
  • Answers questions like “What’s Tesla’s latest profit?” using real SEC filings
  • Supports multi-turn, context-aware conversations via Agent-powered Context Engineering

Ask follow-ups like “What’s the current stock price?” — the agent uses retained ticker symbol to call get_quote instantly.

🔄 Example AI Assistant Chatbot Workflow

User: “Analyze NVIDIA’s current investment outlook”

  1. Plan:

    • search_company("NVIDIA") → CIK 0001045810, ticker NVDA
    • get_latest_financial_data(cik="0001045810")
    • get_quote(symbol="NVDA")
    • get_company_news(symbol="NVDA")

  2. Execute:

    • EasyReportDataMCP fetches latest quarterly results via stdio JSON-RPC
    • MarketandStockMCP gets current stock price via Gradio API
    • MarketandStockMCP retrieves latest NVDA news articles

  3. Reason:

    • Compares financial performance vs stock valuation
    • Analyzes news sentiment impact
    • Identifies entry/exit opportunities

  4. Respond:

    • Generates comprehensive investment thesis
    • Stores full context for follow-up questions

All steps are autonomous, auditable, and hallucination-free.

🛠️ Tech Stack

  • Frontend: Gradio 5.49.1 (Blocks, ChatInterface, State, Tabs, Streaming)
  • Agent LLM: Qwen/Qwen2.5-72B-Instruct (via Hugging Face Inference API)
  • MCP Framework: FastMCP 1.0.0+ (Python SDK)
  • MCP Transport:
    • stdio (local subprocess via JSON-RPC 2.0)
    • Gradio API (remote SSE for MarketandStockMCP)
  • MCP Servers:
    • EasyReportDataMCP (SEC EDGAR data via sec-edgar-api 1.1.0)
    • MarketandStockMCP (Finnhub API for real-time market data)
  • Local Processing: pdfplumber 0.7.0+, BeautifulSoup4 4.11.0+, aiohttp 3.8.1+
  • HTTP Client: httpx 0.23.0+ (async), requests 2.32.0+
  • Data Processing: pandas 2.2.2+, plotly 5.24.1+
  • Server Framework: uvicorn 0.27.0, starlette 0.27.0+, sse-starlette 1.6.5+
  • Deployment: Hugging Face Spaces

▶️ Try It Now!

👉 Live App: https://huggingface.co/spaces/MCP-1st-Birthday/Easy-Financial-Report

You can:

  • Analyze any public company in seconds
  • Get AI investment advice — grounded in real filings and market data
  • Chat naturally with the Financial Assistant
  • Monitor live news

All without hallucination.

📝 License

MIT License — free for personal and commercial use.

🙌 Built proudly for the MCP’s 1st Birthday Hackathon!

💬 Code on Hugging Face. Feedback welcome!