AI导哈

股票数据助手

一个基于AI的股票数据查询工具，支持从Yahoo Finance获取实时数据或从CSV文件获取离线数据，并提供多种实现方式（原始stdio、MCP SDK、Gemini路由）。

  • by aidamian
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aidamian/mcp-workshop

使用说明

MCP研讨会

Alglrithms&Flows

  • 使用案例： 一个会话式股票助手，将自然语言提示转化为工具调用(get_stock_price, compare_stocks)，首先从雅虎财经获取数据，然后回落到 stocks_data.csv 用于确定性回复。
  • 常见流程： 用户提示→ 路由器选择工具/args（人工智能辅助启发式回退）→ 服务器对实时/CSV数据执行→ 客户端呈现一个简洁的、颜色编码的响应。
  • 原始工作室 ： 子流程客户端和服务器之间stdio上的最小JSON；运行速度最快，是测试的默认值。
  • MCP-SDK： 使用官方 mcp 带有stdio或进程内内存传输的包；集成外部MCP功能工具时效果最佳。
  • 课程/双子座： 镜像MCP传输，但要求Google Gemini选择工具/args；专为展示备选布线模型的教程而设计。

此存储库演示了一个基于Deepseek的股票数据助理，它有三个可互换的实现：

  • 原始stdio变体(raw_version/) --在客户端和服务器之间使用轻量级的JSONoverstdio合约来镜像原始研讨会；测试和快速演示的默认设置。
  • MCP SDK变体(mcp_version/) --使用官方重新实施运输 mcp PyPI包，因此任何支持MCP的工具都可以通过stdio连接。
  • 课程/教程变体(course_version/) --以教学为重点的MCP构建，将Deepseek路由替换为Google Gemini，以不同的模型说明工具选择。

根入口点(mcp_client.py, mcp_server.py)重新导出原始实现以实现向后兼容性。MCP和课程变体在其文件夹下是独立的，可以由测试线束明确地定位。

特性

  • 🤖 人工智能辅助路由：Deepseek为原始和MCP构建提供动力（在没有密钥的情况下，确定性启发式作为回退）；该课程在Google Gemini中构建交换，用于教程流程中的工具选择。
  • 📊 双重数据来源：雅虎财经 yfinance 在线时，以及 stocks_data.csv 用于确定性离线覆盖。
  • 🧰 并行构建：原始JSON stdio、MCP SDK stdio/内存以及共享相同库存工具的Gemini驱动的课程变体。
  • 💬 交互式CLIs：每个变体都会提供一个会话REPL，反映相同的用户体验。
  • 🛡️ 优雅的降级：路由器和数据提供商会自动回退，因此即使没有网络访问，现场研讨会也会继续运行。

建筑

原始变体(raw_version/)

  • raw_version/client.py 包含原始的Deepseek路由器、stdio子进程客户端和REPL。
  • raw_version/server.py 暴露 get_stock_price 和 compare_stocks 工具覆盖换行符分隔的JSON。
  • 根模块(mcp_client.py, mcp_server.py)包装此包以保持旧的导入和脚本正常工作。

MCP变体(mcp_version/)

  • mcp_version/server.py 重复使用 StockDataProvider 但在上注册工具 fastmcp 从官方 mcp 包装，通过stdio供应。
  • mcp_version/client.py 在进程中启动MCP服务器，使用以下命令建立MCP会话 StdioServerParameters/stdio_client，并保持相同的路由逻辑和终端UX。
  • 任何支持MCP的外部客户端（例如IDE集成或代理框架）都可以连接到 mcp_version/server.py 直接。

课程变体(course_version/)

  • course_version/server.py 是另一个FastMCP服务器，它使用与其他版本相同的CSV/y金融数据流和颜色编码日志。
  • course_version/client.py 演示使用Google Gemini进行工具路由(gemini-2.0-flash-001)而不是Deepseek。它从服务器获取工具列表，要求Gemini选择一个工具和参数，然后通过MCP stdio执行调用。
  • 从内部运行此变体 course_version/ 目录（或调整 cwd 在客户端中），以便客户端可以生成 server.py 正确地。集 GEMINI_API_KEY 在你的 .env 在开始REPL之前。

入门指南

先决条件

  • Python 3.10或更高版本
  • 深度搜索API密钥（集 DEEPSEEK_KEY 在 .env)用于人工智能辅助路由
  • 雅虎财经实时数据的可选互联网连接

通用设置

  1. 使用创建和激活虚拟环境 紫外线:
    uv venv
source .venv/bin/activate
  2. 安装依赖项：
    uv pip install -r requirements.txt
  3. 提供配置：
    DEEPSEEK_KEY=your_deepseek_key_here
  4. 确保 stocks_data.csv 保留在存储库根目录中。它为离线测试提供确定性夹具。

运行原始JSON变量

  1. 启动客户端（保留传统行为）。默认情况下，详细生命周期日志记录处于打开状态：
    uv run python mcp_client.py
  2. 示例提示：
    What's the current price of AAPL?
Compare Apple and Microsoft stocks
  3. 要减少输出，请显式禁用调试日志：
    uv run python mcp_client.py --no-debug

日志记录流（原始变量和共享调色板）

  • [agent] （亮白色）：REPL中的用户端事件和提示。
  • [model] （蓝色）：选择工具和参数的深度搜索/启发式分析。
  • [mcp-client] （紫色）：从客户端传输开始的stdio调度/响应生命周期（所有变体都重用相同的调色板）。
  • [mcp-server] （紫色）：被调用工具的服务器执行日志（stderr以避免JSON噪声）。
  • [model] （黄色）：基于工具有效载荷的模型绘制。
  • [model] （绿色）：最终模型面向用户显示回复。
  • [warning] （红色）：验证问题和执行错误；与代理白日志不同。

运行MCP SDK变体

  1. 启动MCP感知客户端：
    uv run python -m mcp_version.client
  2. 交互式循环反映了在引擎盖下使用MCP运输时的原始体验。
  3. 或者，只运行外部MCP客户端的服务器：
    uv run python -m mcp_version.server
    通过将其配置为通过stdio生成此模块，连接您首选的启用MCP的工具。

运行课程教程变体

  1. 集 GEMINI_API_KEY 在 .env 因此客户端可以通过Gemini路由。
  2. 从存储库根目录，切换到课程文件夹以保持路径对齐：
    cd course_version
  3. 启动Gemini路由客户端（它会为每个提示自动生成FastMCP服务器）：
    uv run python client.py
  4. 要为另一个支持MCP的客户端而不是捆绑的REPL托管课程服务器，请执行以下操作：
    uv run python server.py

测试

  • 现场测试 tests/ 并默认为原始变体，这样您就可以在没有API密钥或可选包的情况下运行它们。
  • 通过中的选择器定位特定构建 tests/run_tests.py:
    uv run python tests/run_tests.py raw     # default
uv run python tests/run_tests.py mcp     # requires `mcp` installed
uv run python tests/run_tests.py course  # requires `google-genai` and `GEMINI_API_KEY` for Gemini routing
  • 您还可以设置 TEST_VARIANT （例如， TEST_VARIANT=mcp uv run python tests/run_tests.py)以避免传递CLI参数。
  • 课程教程客户端有意轻量级，可能与共享的pytest用例不同；专注于自动化运行的raw/mcp，或者在运行完整的教程帮助程序之前对齐教程帮助程序 uv run python -m pytest tests/ 扫。

仓库布局

├── mcp_client.py          # Wrapper around the raw client implementation
├── mcp_server.py          # Wrapper around the raw server implementation
├── raw_version/
│   ├── __init__.py
│   ├── client.py          # Original Deepseek router and stdio transport
│   └── server.py          # JSON-over-stdio tool server
├── mcp_version/
│   ├── __init__.py
│   ├── client.py          # Official MCP client using OpenAI SDK routing
│   └── server.py          # Official MCP server using fastmcp
├── course_version/        # Course-oriented MCP variant using google-genai routing
│   ├── client.py
│   └── server.py
├── stocks_data.csv        # Offline stock price cache
├── requirements.txt       # Python dependencies for both variants
├── tests/                 # Variant-aware integration tests and helpers
└── README.md              # Project overview

工具

get_stock_price

  • 目的： 检索单个股票的最新价格。
  • 论据： symbol （字符串，大写股票代码）
  • 典型提示： “给我看看NVDA”，“AAPL的价格是多少？”

compare_stocks

  • 目的： 对比两个符号的价格。
  • 论据： symbol_one, symbol_two （字符串，大写股票代码）
  • 典型提示： “比较苹果和微软”，“TSLA比AMZN高吗？”

配置参考

  • .env 必须定义 DEEPSEEK_KEY没有它，路由器就会回到关键字启发式。
  • .env 包括 DEEPSEEK_BASE_URL 覆盖OpenAI客户端使用的Deepseek端点。
  • .env 可包括 GEMINI_API_KEY 在中启用Gemini路由 course_version.
  • 集 MCP_FORCE_MEMORY=1 强制MCP客户端使用进程内内存传输，而不是生成stdio子进程（有助于CI和离线运行）。
  • stocks_data.csv 跟随 symbol,price,last_updated。通过添加更多行来扩展它，以获得更多的离线覆盖。

数据源

  • 主要的，重要的 yfinance 用于实时数据（需要出站HTTPS）。
  • 退路： stocks_data.csv 用于研讨会或离线会议期间的确定性响应。

故障排除

  • Deepseek路由错误： 确认 DEEPSEEK_KEY 以及网络接入。当API调用失败时，客户端会自动返回试探法。
  • 雅虎财经连接问题： 网络/SSL问题会触发CSV回退。填充 stocks_data.csv 有了你需要的自动收报机。
  • 集成外部MCP客户端： 跑 python -m mcp_version.server 并将MCP工具指向生成的流程。确保该工具接受stdio传输。

依赖项

  • python-dotenv --从加载环境变量 .env.
  • requests -调用深度搜索REST API。
  • yfinance --在可用时获取实时股票价格。
  • mcp --官方MCP客户端/服务器包为SDK变体提供支持。
  • openai --用于MCP客户端Deepseek路由的官方SDK。
  • google-genai --Google Gemini SDK用于课程变体路由。

跑 python -m compileall 在提交更改之前，请使用touch服务器工具及早发现语法问题。

相关 MCP