---
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**:https://www.linkedin.com/posts/jackie-cui-bb1582337_ai-fintech-agenticai-activity-7400822253061312512-71Aw?utm_source=share&utm_medium=member_desktop&rcm=ACoAAFSfyDUBInZNBoPst2dD1lCjLXS-IdaZFTE

> 🌐 **Social media -LinkedIn Post**: https://www.linkedin.com/posts/jackie-cui-bb1582337_ai-fintech-agenticai-activity-7400822253061312512-71Aw?utm_source=share&utm_medium=member_desktop&rcm=ACoAAFSfyDUBInZNBoPst2dD1lCjLXS-IdaZFTE

---


## 🤖 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:

```json
{
  "plan": [
    {"tool": "search_company", "arguments": {"company_name": "Tesla"}},
    {"tool": "get_financial_data", "arguments": {"cik": "0001318605", "period": "2025Q1"}},
    {"tool": "get_quote", "arguments": {"symbol": "TSLA"}}
  ]
}
```

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

4. **Stateful Dialogue**: Maintains structured context across turns:

```python
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):

```json
{
  "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):

```json
{
  "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](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!