yfin-mcp 0.2.5__tar.gz → 0.2.7__tar.gz

yfin_mcp-0.2.7/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

yfin_mcp-0.2.7/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+-   repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+    -   id: black
+        language_version: python3.11
+        args: [--line-length=100]
+
+-   repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+    -   id: isort
+        name: isort (python)
+        args: [--profile=black, --line-length=100]

yfin_mcp-0.2.7/.python-version

@@ -0,0 +1 @@
+3.11

yfin_mcp-0.2.7/.vscode/mcp.json

@@ -0,0 +1,12 @@
+{
+	"servers": {
+		"yfinance": {
+			"type": "stdio",
+			"command": "uvx",
+			"args": [
+				"yahoo-finance-mcp"
+			]
+		}
+	},
+	"inputs": []
+}

yfin_mcp-0.2.7/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

yfin_mcp-0.2.7/Dockerfile

@@ -0,0 +1,41 @@
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS uv
+
+# Install the project into /app
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Copy project files
+COPY pyproject.toml .
+
+# Install the project's dependencies using uv
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install --system -e .
+
+# Copy the rest of the application code
+COPY . .
+
+# Second stage: runtime image
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy the virtual environment from the uv stage
+COPY --from=uv /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=uv /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY . .
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+
+# Command to run the MCP server
+CMD ["uv", "run", "yfin-mcp"]

{yfin_mcp-0.2.5/src/yfin_mcp.egg-info → yfin_mcp-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yfin-mcp
-Version: 0.2.5
+Version: 0.2.7
 Summary: Enhanced Yahoo Finance MCP Server with intelligent pagination, caching, and LLM-optimized responses
 Author: AlexYoung (Original Author)
 Author-email: fritzprix <innocentevil0914@gmail.com>

yfin_mcp-0.2.7/README.zh.md

@@ -0,0 +1,214 @@
+# Yahoo Finance MCP 服务器
+
+> **注意：** 这是一个社区分支。官方包由 [Alex2Yang97](https://github.com/Alex2Yang97/yahoo-finance-mcp) 维护，可在 [PyPI](https://pypi.org/project/yahoo-finance-mcp/) 上获取。
+
+<div align="right">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a>
+</div>
+
+这是一个基于模型上下文协议（MCP）的服务器，提供来自 Yahoo Finance 的全面金融数据。它允许您获取股票的详细信息，包括历史价格、公司信息、财务报表、期权数据和市场新闻。
+
+[![smithery badge](https://smithery.ai/badge/@Alex2Yang97/yahoo-finance-mcp)](https://smithery.ai/server/@Alex2Yang97/yahoo-finance-mcp)
+
+## 演示
+
+![MCP 演示](assets/demo.gif)
+
+## MCP 工具
+
+服务器通过模型上下文协议提供以下工具：
+
+### 股票信息
+
+| 工具 | 描述 |
+|------|-------------|
+| `get_historical_stock_prices` | 获取股票的历史 OHLCV 数据，可自定义时间段和间隔 |
+| `get_stock_info` | 获取全面的股票数据，包括价格、指标和公司详情 |
+| `get_yahoo_finance_news` | 获取股票的最新新闻文章 |
+| `get_stock_actions` | 获取股票分红和拆股历史 |
+
+### 财务报表
+
+| 工具 | 描述 |
+|------|-------------|
+| `get_financial_statement` | 获取利润表、资产负债表或现金流量表（年度/季度） |
+| `get_holder_info` | 获取主要股东、机构股东、共同基金或内幕交易信息 |
+
+### 期权数据
+
+| 工具 | 描述 |
+|------|-------------|
+| `get_option_expiration_dates` | 获取可用的期权到期日期 |
+| `get_option_chain` | 获取特定到期日期和类型（看涨/看跌）的期权链 |
+
+### 分析师信息
+
+| 工具 | 描述 |
+|------|-------------|
+| `get_recommendations` | 获取分析师推荐或评级变更历史 |
+
+## 实际应用场景
+
+使用此 MCP 服务器，您可以利用 Claude 进行：
+
+### 股票分析
+
+- **价格分析**："显示苹果公司过去 6 个月的每日历史股价。"
+- **财务健康**："获取微软的季度资产负债表。"
+- **业绩指标**："从股票信息中获取特斯拉的关键财务指标。"
+- **趋势分析**："比较亚马逊和谷歌的季度利润表。"
+- **现金流分析**："显示英伟达的年度现金流量表。"
+
+### 市场研究
+
+- **新闻分析**："获取关于 Meta Platforms 的最新新闻文章。"
+- **机构活动**："显示苹果股票的机构股东。"
+- **内幕交易**："特斯拉最近的内幕交易有哪些？"
+- **期权分析**："获取 SPY 在 2024-06-21 到期的看涨期权链。"
+- **分析师覆盖**："亚马逊过去 3 个月的分析师推荐是什么？"
+
+### 投资研究
+
+- "使用微软最新的季度财务报表创建其财务健康状况的全面分析。"
+- "比较可口可乐和百事可乐的分红历史和股票拆分。"
+- "分析特斯拉过去一年的机构所有权变化。"
+- "生成一份关于苹果股票 30 天到期的期权市场活动报告。"
+- "总结过去 6 个月科技行业的最新分析师评级变更。"
+
+## 系统要求
+
+- Python 3.11 或更高版本
+- `pyproject.toml` 中列出的依赖项，包括：
+  - mcp
+  - yfinance
+  - pandas
+  - pydantic
+  - 以及其他数据处理包
+
+## 安装
+
+### 方式 1：从 PyPI 安装（推荐）
+
+最简单的安装方式是直接从 PyPI 安装：
+
+```bash
+pip install yahoo-finance-mcp
+```
+
+### 方式 2：从源代码安装
+
+1. 克隆此仓库：
+   ```bash
+   git clone https://github.com/Alex2Yang97/yahoo-finance-mcp.git
+   cd yahoo-finance-mcp
+   ```
+
+2. 创建并激活虚拟环境，安装依赖：
+   ```bash
+   uv venv
+   source .venv/bin/activate  # Windows: .venv\Scripts\activate
+   uv pip install -e .
+   ```
+
+## 使用方法
+
+### 运行服务器
+
+安装包后，您可以运行服务器：
+
+```bash
+# 如果从 PyPI 安装
+python -m yahoo_finance_mcp.server
+
+# 或者如果从源代码安装
+uv run server.py
+```
+
+### 开发模式
+
+您可以通过运行以下命令使用 MCP Inspector 测试服务器：
+
+```bash
+uv run server.py
+```
+
+这将启动服务器并允许您测试可用工具。
+
+### 与 Claude Desktop 集成
+
+要将此服务器与 Claude Desktop 集成：
+
+1. 在本地机器上安装 Claude Desktop。
+
+2. 确保已安装 `uv`。如果没有，请安装：
+   ```bash
+   # macOS/Linux
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   
+   # Windows
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   ```
+
+3. 打开 Claude Desktop 配置文件：
+   - MacOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows：`%APPDATA%\Claude\claude_desktop_config.json`
+
+4. **方式 A：使用 PyPI 包（推荐）**
+
+   添加以下配置：
+
+   ```json
+   {
+     "mcpServers": {
+       "yfinance": {
+         "command": "uvx",
+         "args": ["yahoo-finance-mcp"]
+       }
+     }
+   }
+   ```
+
+   这将自动从 PyPI 下载并运行最新版本。
+
+5. **方式 B：使用本地源代码**
+
+   如果您正在开发或想使用本地版本：
+
+   - macOS/Linux：
+     ```json
+     {
+       "mcpServers": {
+         "yfinance": {
+           "command": "uv",
+           "args": [
+             "--directory",
+             "/ABSOLUTE/PATH/TO/yahoo-finance-mcp",
+             "run",
+             "server.py"
+           ]
+         }
+       }
+     }
+     ```
+   - Windows：
+     ```json
+     {
+       "mcpServers": {
+         "yfinance": {
+           "command": "uv",
+           "args": [
+             "--directory",
+             "C:\\ABSOLUTE\\PATH\\TO\\yahoo-finance-mcp",
+             "run",
+             "server.py"
+           ]
+         }
+       }
+     }
+     ```
+
+6. 重启 Claude Desktop
+
+## 许可证
+
+MIT 

yfin_mcp-0.2.7/TESTING.md

@@ -0,0 +1,155 @@
+# Testing Guide
+
+This guide explains how to test the Yahoo Finance MCP server using the MCP Inspector.
+
+## Quick Start
+
+### Windows
+```bash
+run_inspector.bat
+```
+
+### macOS/Linux
+```bash
+./run_inspector.sh
+```
+
+### Production Testing (via uvx)
+
+If you have published the package or want to test the `uvx` entry point:
+
+#### Windows
+```bash
+run_inspector_prod.bat
+```
+
+#### macOS/Linux
+```bash
+chmod +x run_inspector_prod.sh
+./run_inspector_prod.sh
+```
+
+The MCP Inspector will start on **http://localhost:6274**
+
+---
+
+## What is MCP Inspector?
+
+MCP Inspector is a web-based tool for testing Model Context Protocol servers. It provides:
+- Interactive UI to call MCP tools
+- Real-time response viewing
+- Parameter input forms
+- Error debugging
+
+---
+
+## Testing Workflow
+
+### 1. Start the Inspector
+
+Run the appropriate script for your OS (see Quick Start above).
+
+### 2. Open in Browser
+
+Navigate to **http://localhost:6274** in your web browser.
+
+### 3. Test Tools
+
+The inspector will show all available tools. Try these tests:
+
+#### Test 1: Basic Stock Info
+- Tool: `get_stock_info`
+- Parameters:
+  ```json
+  {
+    "ticker": "AAPL",
+    "fields": ["currentPrice", "marketCap", "trailingPE"]
+  }
+  ```
+- Expected: Only 3 fields returned with cache status
+
+#### Test 2: Pagination
+- Tool: `get_historical_stock_prices`
+- Parameters:
+  ```json
+  {
+    "ticker": "AAPL",
+    "period": "1mo",
+    "interval": "1d",
+    "page": 1
+  }
+  ```
+- Expected: Paginated response with navigation guidance
+
+#### Test 3: Cache Behavior
+- Run the same query twice
+- First call: "Fresh data (not cached)"
+- Second call: "Data cached (age: X seconds)"
+
+#### Test 4: JSON Export
+- Tool: `get_historical_stock_prices`
+- Parameters:
+  ```json
+  {
+    "ticker": "AAPL",
+    "period": "5d",
+    "interval": "1d",
+    "export_path": "./test_export.json"
+  }
+  ```
+- Expected: Export success message and file created
+
+---
+
+## Troubleshooting
+
+### Inspector won't start
+- Make sure Node.js is installed: `node --version`
+- Install npx: `npm install -g npx`
+- Check if port 6274 is available
+
+### Server errors
+- Verify Python 3.11+ is installed
+- Install dependencies: `uv sync` or `pip install -e .`
+- Check yfinance is working: `python -c "import yfinance; print(yfinance.__version__)"`
+
+### Browser can't connect
+- Ensure firewall allows localhost:6274
+- Try 127.0.0.1:6274 instead of localhost
+- Check server logs for errors
+
+---
+
+## Advanced Testing
+
+### Test All Tools
+
+See [manual_testing_guide.md](C:\Users\SKTelecom\.gemini\antigravity\brain\d0950c1d-b04a-415d-ab2c-bcbdf1b6730e\manual_testing_guide.md) for comprehensive test cases.
+
+### Automated Tests
+
+Run unit tests:
+```bash
+python tests/test_pagination.py
+```
+
+### Performance Testing
+
+Monitor cache hit rates and response times in the inspector output.
+
+---
+
+## Stopping the Inspector
+
+Press **Ctrl+C** in the terminal to stop the server.
+
+---
+
+## Next Steps
+
+After testing:
+1. Verify all tools work correctly
+2. Check pagination appears on large datasets
+3. Confirm cache behavior
+4. Test JSON export functionality
+5. Ready for production use!

yfin_mcp-0.2.7/publish_package.bat

@@ -0,0 +1,88 @@
+@echo off
+REM Publication script for yfin-mcp (Windows)
+REM This script builds and publishes the package to PyPI using uv
+
+echo ========================================
+echo Publishing yfin-mcp to PyPI
+echo ========================================
+echo.
+
+REM Version bumping logic
+set BUMP_TYPE=%1
+if "%BUMP_TYPE%"=="major" goto :bump
+if "%BUMP_TYPE%"=="minor" goto :bump
+if "%BUMP_TYPE%"=="patch" goto :bump
+goto :start_build
+
+:bump
+echo Step 0: Bumping version (%BUMP_TYPE%)...
+uv run scripts/bump_version.py %BUMP_TYPE%
+if %ERRORLEVEL% neq 0 (
+    echo [ERROR] Version bump failed.
+    pause
+    exit /b %ERRORLEVEL%
+)
+echo.
+
+:start_build
+echo Step 1: Cleaning dist directory...
+if exist dist (
+    rmdir /s /q dist
+)
+
+echo Step 2: Building package...
+uv build
+if %ERRORLEVEL% neq 0 (
+    echo.
+    echo [ERROR] Build failed. Aborting.
+    pause
+    exit /b %ERRORLEVEL%
+)
+
+echo.
+echo [SUCCESS] Build complete.
+echo.
+
+set /p CONFIRM="Do you want to publish to PyPI now? (y/n): "
+if /i "%CONFIRM%" neq "y" (
+    echo.
+    echo [INFO] Publication cancelled by user.
+    exit /b 0
+)
+
+echo.
+echo Step 3: Publishing to PyPI via twine...
+echo.
+echo [TIP] PyPI authentication now REQUIRES API tokens.
+echo [TIP] Username: '__token__'
+echo [TIP] Password: 'pypi-YourTokenHere'
+echo.
+
+echo [INFO] Installing/Updating twine...
+uv pip install twine
+
+echo [INFO] Running twine upload...
+uv run twine upload dist/*
+
+if %ERRORLEVEL% neq 0 (
+    echo.
+    echo [ERROR] Publication failed.
+    echo.
+    echo [GUIDE] If you're using a token:
+    echo        - Username: __token__
+    echo        - Password: pypi-YOUR_TOKEN_STRING
+    echo.
+    echo [INFO] Current HOME is: %HOME%
+    echo [INFO] Current USERPROFILE is: %USERPROFILE%
+    echo.
+    echo [TIP] Try setting the environment variables to automate:
+    echo       set TWINE_USERNAME=__token__
+    echo       set TWINE_PASSWORD=pypi-XXXXXX
+    echo       ...and run this script again.
+    pause
+    exit /b %ERRORLEVEL%
+)
+
+echo.
+echo [SUCCESS] Package published successfully!
+pause

yfin_mcp-0.2.7/publish_package.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Publication script for yfin-mcp (Unix/Linux/macOS)
+# This script builds and publishes the package to PyPI using uv
+
+echo "========================================"
+echo "Publishing yfin-mcp to PyPI"
+echo "========================================"
+echo ""
+
+# Version bumping logic
+BUMP_TYPE=$1
+if [[ "$BUMP_TYPE" == "major" || "$BUMP_TYPE" == "minor" || "$BUMP_TYPE" == "patch" ]]; then
+    echo "Step 0: Bumping version ($BUMP_TYPE)..."
+    uv run scripts/bump_version.py $BUMP_TYPE
+    if [ $? -ne 0 ]; then
+        echo "[ERROR] Version bump failed."
+        exit 1
+    fi
+    echo ""
+fi
+
+echo "Step 1: Cleaning dist directory..."
+rm -rf dist/
+
+echo "Step 2: Building package..."
+uv build
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "[ERROR] Build failed. Aborting."
+    exit 1
+fi
+
+echo ""
+echo "[SUCCESS] Build complete."
+echo ""
+
+read -p "Do you want to publish to PyPI now? (y/n): " CONFIRM
+if [[ "$CONFIRM" != "y" ]]; then
+    echo ""
+    echo "[INFO] Publication cancelled by user."
+    exit 0
+fi
+
+echo ""
+echo "Step 3: Publishing to PyPI via twine..."
+echo ""
+echo "[TIP] PyPI authentication now REQUIRES API tokens."
+echo "[TIP] Username: '__token__'"
+echo "[TIP] Password: 'pypi-YourTokenHere'"
+echo ""
+
+uv pip install twine
+uv run twine upload dist/*
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "[ERROR] Publication failed."
+    echo "[INFO] Make sure your .pypirc is correct or set TWINE_PASSWORD/TWINE_USERNAME variables."
+    exit 1
+fi
+
+echo ""
+echo "[SUCCESS] Package published successfully!"

{yfin_mcp-0.2.5 → yfin_mcp-0.2.7}/pyproject.toml

@@ -1,10 +1,14 @@
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["yfin_mcp*"]
+
 [project]
 name = "yfin-mcp"
-version = "0.2.5"
+version = "0.2.7"
 description = "Enhanced Yahoo Finance MCP Server with intelligent pagination, caching, and LLM-optimized responses"
 readme = "README.md"
 requires-python = ">=3.11"

yfin_mcp-0.2.7/run_inspector.bat

@@ -0,0 +1,13 @@
+@echo off
+REM MCP Inspector Launcher for Windows
+REM This script starts the MCP Inspector to test the Yahoo Finance MCP server
+
+echo ========================================
+echo Starting MCP Inspector
+echo ========================================
+echo.
+echo The inspector will start on http://localhost:6274
+echo Press Ctrl+C to stop the server
+echo.
+
+npx @modelcontextprotocol/inspector uv --directory . run yfin-mcp

yfin_mcp-0.2.7/run_inspector.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# MCP Inspector Launcher for Unix/Linux/macOS
+# This script starts the MCP Inspector to test the Yahoo Finance MCP server
+
+echo "========================================"
+echo "Starting MCP Inspector"
+echo "========================================"
+echo ""
+echo "The inspector will start on http://localhost:6274"
+echo "Press Ctrl+C to stop the server"
+echo ""
+
+npx @modelcontextprotocol/inspector uv --directory . run yfin-mcp

yfin_mcp-0.2.7/run_inspector_prod.bat

@@ -0,0 +1,14 @@
+@echo off
+REM Production MCP Inspector Launcher for Windows
+REM This script starts the MCP Inspector to test the PUBLISHED yfin-mcp package
+
+echo ========================================
+echo Starting Production MCP Inspector
+echo ========================================
+echo.
+echo This script tests the server via 'uvx yfin-mcp'
+echo The inspector will start on http://localhost:6274
+echo Press Ctrl+C to stop the server
+echo.
+
+npx @modelcontextprotocol/inspector uvx yfin-mcp

yfin_mcp-0.2.7/run_inspector_prod.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Production MCP Inspector Launcher for Unix/Linux/macOS
+# This script starts the MCP Inspector to test the PUBLISHED yfin-mcp package
+
+echo "========================================"
+echo "Starting Production MCP Inspector"
+echo "========================================"
+echo ""
+echo "This script tests the server via 'uvx yfin-mcp'"
+echo "The inspector will start on http://localhost:6274"
+echo "Press Ctrl+C to stop the server"
+echo ""
+
+npx @modelcontextprotocol/inspector uvx yfin-mcp