股票研究助手

mindmap
  root((MCP))
    Tools
      get_stock_price
      search_news
      analyse_fundamentals
      compare_stocks
    Resources
      nse_symbols.json
      market_glossary.md
      portfolio_template.txt
    Prompts
      stock_analysis_prompt
      portfolio_review_prompt

sequenceDiagram
    participant U as 👤 User
    participant C as MCP Client
    participant O as Ollama LLM
    participant S as MCP Server
    participant Y as yfinance API

    U->>C: "What is the price of TCS?"
    C->>C: Keyword router detects price + TCS
    C->>S: tools/call → get_stock_price(ticker="TCS.NS")
    S->>Y: yf.Ticker("TCS.NS").info
    Y-->>S: Live JSON data
    S-->>C: TextContent(JSON)
    C->>O: Summarise this JSON for user
    O-->>C: Natural language response
    C-->>U: "TCS is trading at ₹2,410.50 (−1.31%)"

graph TB
    subgraph USER["👤 User Interface"]
        U[Terminal Chat Loop]
    end

    subgraph CLIENT["🖥️ MCP Client — finsight_client.py"]
        KR[Keyword Router\nFAST PATH]
        LLM[Ollama llama3.2\nSLOW PATH]
        AF[Argument Auto-Fixer]
        CW[Context Window Manager]
    end

    subgraph SERVER["⚙️ MCP Server — finsight_server.py"]
        direction TB
        subgraph TOOLS["🔧 Tools"]
            T1[get_stock_price]
            T2[search_news]
            T3[analyse_fundamentals]
            T4[compare_stocks]
        end
        subgraph RESOURCES["📁 Resources"]
            R1[nse_symbols.json]
            R2[market_glossary.md]
            R3[portfolio_template.txt]
        end
        subgraph PROMPTS["💬 Prompts"]
            P1[stock_analysis_prompt]
            P2[portfolio_review_prompt]
        end
    end

    subgraph DATA["🌐 Data Sources"]
        YF[yfinance\nYahoo Finance]
        NA[NewsAPI\nFree Tier]
        FS[Local Filesystem]
    end

    U --> KR
    U --> LLM
    KR -->|direct tool call| SERVER
    LLM --> AF
    AF -->|fixed tool call| SERVER
    T1 & T2 & T3 & T4 --> YF
    T2 --> NA
    R1 & R2 & R3 --> FS
    SERVER -->|JSON-RPC stdio| CLIENT
    CW --> LLM

    style USER fill:#1a1a2e,color:#e0e0e0
    style CLIENT fill:#16213e,color:#e0e0e0
    style SERVER fill:#0f3460,color:#e0e0e0
    style DATA fill:#533483,color:#e0e0e0
    style TOOLS fill:#1a472a,color:#e0e0e0
    style RESOURCES fill:#4a1942,color:#e0e0e0
    style PROMPTS fill:#7b2d00,color:#e0e0e0

flowchart TD
    A([👤 User types:\n'What is the price of TCS?']) --> B

    B{Keyword\nRouter}
    B -->|Detects 'price' + 'tcs'| C
    B -->|Complex query| G

    C[Maps 'tcs' → 'TCS.NS'\nBuilds tool call directly]
    C --> D

    D[/"MCP tools/call\n{name: get_stock_price,\n arguments: {ticker: TCS.NS}}"/]
    D --> E

    E["⚙️ Server executes\nyf.Ticker('TCS.NS').info\n→ Yahoo Finance API"]
    E --> F

    F[/"Returns JSON:\n{current_price: 2410.5,\n price_change_pct: -1.31,\n market_cap: ₹8.72 Lakh Cr}"/]
    F --> H

    G["🧠 Ollama LLM\nInterprets query\nGenerates tool call JSON"]
    G --> D

    H["🧠 Ollama summarises JSON\ninto natural language"]
    H --> I

    I([✅ Output:\n'TCS is trading at ₹2,410.50\ndown 1.31% today on NSE'])

    style A fill:#1a472a,color:#fff
    style I fill:#1a472a,color:#fff
    style B fill:#7b2d00,color:#fff
    style D fill:#0f3460,color:#fff
    style F fill:#0f3460,color:#fff
    style E fill:#533483,color:#fff

flowchart LR
    A([analyse RELIANCE.NS]) --> B

    B["Client calls\nprompts/get on server\n\nname: stock_analysis_prompt\nargs: {ticker: RELIANCE.NS,\n       timeframe: medium-term}"]

    B --> C["Server reads\nstock_analysis.txt\n\nFills {{ticker}} → RELIANCE.NS\nFills {{timeframe}} → medium-term\n\nReturns PromptMessage"]

    C --> D

    D["Client auto-calls\n2 tools in parallel"]

    D --> E["analyse_fundamentals\n→ P/E, ROE, EPS\n   margins, debt"]
    D --> F["search_news\n→ Latest 5 headlines\n   about Reliance"]

    E --> G["Both results\ninjected into\nLLM context"]
    F --> G

    G --> H["🧠 Ollama generates\n8-section report\nusing template +\nreal tool data"]

    H --> I(["✅ Full structured\nanalysis report\nwith live data\nand verdict"])

    style A fill:#1a472a,color:#fff
    style I fill:#1a472a,color:#fff
    style D fill:#7b2d00,color:#fff
    style H fill:#0f3460,color:#fff

stateDiagram-v2
    [*] --> Initialising : python client/finsight_client.py

    Initialising --> Discovering : session.initialize()
    note right of Discovering
        list_tools() → 4 tools
        list_resources() → 3 resources
        list_prompts() → 2 prompts
    end note

    Discovering --> LoadingContext : Resources read
    note right of LoadingContext
        read_resource(portfolio_template)
        Injected as system message
        LLM now knows user holdings
    end note

    LoadingContext --> ChatLoop : Ready

    ChatLoop --> KeywordRoute : Simple query\n(price, compare, news)
    ChatLoop --> LLMRoute : Complex query
    ChatLoop --> BuiltinCmd : tools / analyse / portfolio

    KeywordRoute --> ToolCall : Direct, no LLM
    LLMRoute --> ArgFix : LLM generates JSON
    ArgFix --> ToolCall : Auto-fix wrong arg names
    BuiltinCmd --> PromptCall : get_prompt()

    ToolCall --> Summarise : JSON result back
    PromptCall --> Summarise : Template + tool data

    Summarise --> ChatLoop : Response shown
    ChatLoop --> [*] : quit

graph LR
    subgraph Schema["JSON Schema Validation"]
        direction TB
        S1["get_stock_price\nrequired: ticker string"]
        S2["search_news\nrequired: query string\noptional: max_results int"]
        S3["analyse_fundamentals\nrequired: ticker string"]
        S4["compare_stocks\nrequired: tickers string array"]
    end

    subgraph Output["Returns"]
        direction TB
        O1["price, change%, volume\nmarket cap, timestamp"]
        O2["headlines, source\ndescription, date"]
        O3["P/E, P/B, ROE, EPS\nmargins, debt, 52W range"]
        O4["side-by-side table\nauto-rankings"]
    end

    S1 --> O1
    S2 --> O2
    S3 --> O3
    S4 --> O4

# How a tool is registered on the server
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="get_stock_price",
            description="Fetch the current live price for an Indian NSE stock. "
                        "Use NSE ticker format: TCS.NS, RELIANCE.NS, INFY.NS",
            inputSchema={
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "NSE ticker symbol e.g. TCS.NS"
                    }
                },
                "required": ["ticker"]
            }
        )
    ]

graph TD
    subgraph RES["MCP Resources"]
        R1["📄 file://nse_symbols\nnse_symbols.json\n50 NSE tickers + sectors"]
        R2["📖 file://market_glossary\nmarket_glossary.md\n30+ finance term definitions"]
        R3["💼 file://portfolio_template\nportfolio_template.txt\n7-stock sample portfolio"]
    end

    subgraph USAGE["Injected into LLM as..."]
        U1["LLM knows all valid tickers\navoids hallucinating symbols"]
        U2["LLM explains P/E, ROE etc.\naccurately from glossary"]
        U3["System message at startup\nLLM knows user holdings\nfor entire session"]
    end

    R1 --> U1
    R2 --> U2
    R3 --> U3

    style RES fill:#4a1942,color:#fff
    style USAGE fill:#1a472a,color:#fff

graph LR
    subgraph Client
        C1["client calls\nget_prompt()"]
    end

    subgraph Server
        T["stock_analysis.txt\n\nPerform a {{timeframe}}\nanalysis of {{ticker}}...\n[8 structured sections]"]
    end

    subgraph Filled
        F["Perform a medium-term\nanalysis of RELIANCE.NS...\n[sections filled in]"]
    end

    subgraph Result
        R["Returned as\nPromptMessage\nrole: user"]
    end

    C1 -->|"ticker=RELIANCE.NS\ntimeframe=medium-term"| T
    T --> F
    F --> R

    style Server fill:#7b2d00,color:#fff
    style Filled fill:#0f3460,color:#fff
    style Result fill:#1a472a,color:#fff

finsight-mcp/
│
├── 📂 server/                        ← MCP Server  (the "what")
│   ├── finsight_server.py            ← Tools + Resources + Prompts registered here
│   ├── 📂 tools/
│   │   ├── stock_price.py            ← get_stock_price  (yfinance)
│   │   ├── news_search.py            ← search_news      (NewsAPI + yfinance fallback)
│   │   ├── fundamentals.py           ← analyse_fundamentals  (50+ metrics)
│   │   └── compare_stocks.py         ← compare_stocks   (multi-ticker, auto-ranked)
│   └── 📂 resources/
│       ├── nse_symbols.json          ← 50 NSE tickers + company names + sectors
│       ├── market_glossary.md        ← 30+ financial term definitions
│       └── portfolio_template.txt    ← 7-stock sample user portfolio
│
├── 📂 client/
│   └── finsight_client.py            ← MCP Client  (the "how")
│                                        • Keyword router (fast path)
│                                        • Ollama integration (slow path)
│                                        • Argument name auto-fixer
│                                        • Context window management
│
├── 📂 prompts/
│   ├── stock_analysis.txt            ← 8-section deep analysis template
│   └── portfolio_review.txt          ← Portfolio score + buy/hold/sell template
│
├── 📂 tests/
│   └── test_tools.py                 ← Unit tests for all 4 tools
│
├── 📂 screenshots/                   ← Demo screenshots for this README
├── .env.example                      ← Config template (Ollama model, NewsAPI key)
├── requirements.txt
└── README.md

graph LR
    subgraph Free["💰 Total Cost: ₹0"]
        direction TB
        A["🐍 Python 3.11\nLanguage"]
        B["🔌 MCP SDK\nAnthropic official"]
        C["🧠 Ollama + llama3.2\nLocal LLM on M1 Mac"]
        D["📈 yfinance\nYahoo Finance API"]
        E["📰 NewsAPI\nFree tier 100 req/day"]
        F["🎨 rich\nTerminal UI"]
        G["🌐 httpx\nAsync HTTP client"]
    end

    style Free fill:#1a1a2e,color:#e0e0e0

# 1. Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Python 3.11
brew install python@3.11 && python3 --version

# 3. Ollama (local LLM runtime)
brew install ollama

# 4. Node.js (for MCP Inspector)
brew install node

git clone https://github.com/Akash-47-tank/finsight-mcp.git
cd finsight-mcp

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

# Terminal 1 — keep running
ollama serve

# Terminal 2
ollama pull llama3.2
ollama list    # confirm it appears

# Terminal 1: keep Ollama running
ollama serve

# Terminal 2: launch FinSight
source venv/bin/activate
python client/finsight_client.py

npx @modelcontextprotocol/inspector python server/finsight_server.py
# Open http://localhost:5173

python tests/test_tools.py

flowchart TD
    A["User Input"] --> B{Keyword\nRouter}

    B -->|price / compare / news\nkeywords detected| C["FAST PATH\nDirect tool call\nNo LLM needed\nCorrect args guaranteed"]

    B -->|Complex / ambiguous\nquery| D["SLOW PATH\nOllama generates\ntool call JSON"]

    D --> E{Arg names\ncorrect?}

    E -->|Yes| F["Call MCP tool\ndirectly"]
    E -->|No — e.g. param\ninstead of ticker| G["Auto-fixer remaps:\nparam → ticker\nsymbol → ticker\nstock → ticker"]

    G --> F
    C --> F

    F --> H["Tool executes\non server"]

    style C fill:#1a472a,color:#fff
    style G fill:#7b2d00,color:#fff
    style F fill:#0f3460,color:#fff

# Auto-fixer in extract_tool_call()
wrong_keys = {"param", "symbol", "stock", "ticker_symbol", "stock_ticker"}
for wrong in wrong_keys:
    if wrong in args and "ticker" not in args:
        args["ticker"] = args.pop(wrong)   # remap silently

# Always keep system prompts + last 20 messages
if len(messages) > 22:
    messages = messages[:2] + messages[-20:]

# Loaded ONCE — stays in LLM context for entire session
portfolio = await session.read_resource("file://portfolio_template")
messages.append({
    "role": "system",
    "content": f"USER PORTFOLIO:\n{portfolio_text}"
})
# LLM now knows all 7 holdings throughout the conversation

Price    : ₹1,380.70 (+0.25%)
P/E      : 22.47  vs sector avg 20.12  → slightly overvalued
ROE      : 0.6%   (below 15% ideal)    → concern flagged
D/E      : 35.65                        → high leverage
52W Range: ₹1,142 – ₹1,611
Trend    : Bullish (above 50 DMA ₹1,420 and 200 DMA ₹1,448)
News     : $300B US refinery · Venezuela oil strategy
Verdict  : Overvalued on P/E and P/B vs sector peers