WIND 市场数据 MCP 服务

这是一个只读 MCP 服务，把 Oracle 中的股票类指数、A 股标的基础信息和股东大会信息提供给本机及局域网智能体。

目前提供四个工具：

• get_index_by_code(code)：按 S_INFO_CODE 精确查询，例如 000300；

• search_indices_by_name(name, limit=20)：按指数名称片段搜索，最多返回 100 条；

• resolve_a_share(query, limit=10)：按 Wind 代码、六位代码、证券简称、公司全称或名称片段识别 A 股公司；

• get_shareholder_meetings(wind_code, meeting_date=None, limit=10)：按代码或公司名称查询股东大会、召开时间、相关议案及表决结果。

服务不接受 SQL，不提供数据库写操作。查询使用固定 SQL 和 Oracle 绑定参数。

A 股标的识别

resolve_a_share 是可供股东大会、行情、财务等领域复用的独立标的解析工具：

• query="002311.SZ"：按完整 Wind 代码精确识别；

• query="002311"：按六位股票代码精确识别；

• query="海大集团"：先按证券简称或公司全称精确识别；

• query="海大"：精确匹配不到时，对证券简称和公司全称做包含搜索；

• 唯一匹配时返回 status="resolved" 和公司基本资料；

• 多个匹配时返回 status="ambiguous" 和最多 limit 个候选，不会自动猜测；

• 无匹配时返回 status="not_found"；

• limit 默认 10、最大 50；输入中的 %、_ 和 \ 会按普通字符处理。

公司身份来自 WIND_IMP.ASHAREDESCRIPTION，公司简介来自 WIND_IMP.ASHAREINTRODUCTION，两表通过 S_INFO_WINDCODE 关联。存在多条公司简介时使用最新记录；没有简介时仍可返回代码、简称和全称。

股东大会查询

get_shareholder_meetings 的 wind_code 参数兼容原有完整 Wind 代码，同时支持六位代码、证券简称、公司全称和名称片段。例如，用户可以直接说“查询海大集团最近的股东大会议题”。名称存在多个候选时，服务会提示候选代码，用户指定后再查询。

• 不传 meeting_date 时，按会议日期倒序返回最近的股东大会；

• 传入 meeting_date="20260820" 时，只返回该日期召开的会议；

• limit 限制会议场数，默认 10、最大 50，不是议案条数；

• 每场会议的 proposals 包含议案序号、名称、表决方式、标准化结果和数据库原始结果；

• result 为 passed、rejected 或 unknown，分别表示通过、未通过和数据库未提供明确结果。

• 会议表只读取 IS_NEW = 1 或历史空值记录；IS_NEW = 0 表示已被更新版本替代，查询时会排除以免重复。

数据来自：

• WIND_IMP.ASHAREDESCRIPTION：Wind 代码、证券简称和公司全称；

• WIND_IMP.ASHAREINTRODUCTION：公司简介、地区、管理层、网站及主营业务等；

• WIND_IMP.ASHAREHOLDERSMEETING：大会日期、时间、类型、名称和会议内容；

• WIND_IMP.ASHAREINTERNETVOTING：逐项议案、表决方式和是否通过；

• 两表通过 MEETEVENT_ID = S_EVENT_ID 关联。

运行环境

• Windows 10/11；

• Python 3.11 或更高版本；

• 已准备可访问的 Oracle 主机、端口和 Service Name；

• 首版使用 python-oracledb Thin 模式，无需安装 Oracle Client。

安装

在 PowerShell 中运行：

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e '.[dev]'

将 .env.example 复制为 .env 并填写真实配置。本机已创建可运行的 .env；该文件被 .gitignore 排除，不会进入版本库。

本机 stdio 模式

手工启动时，进程会等待 MCP 客户端从标准输入发送消息：

.\.venv\Scripts\python.exe -m index_mcp.run_stdio

Codex 使用项目级或用户级 config.toml。以下配置让 Codex 直接拉起本机服务：

[mcp_servers.wind_index]
command = 'D:\1.Project\19.CodexProject\9.MCP\.venv\Scripts\python.exe'
args = ["-m", "index_mcp.run_stdio"]
cwd = 'D:\1.Project\19.CodexProject\9.MCP'
required = true
default_tools_approval_mode = "auto"

保存配置后重启 Codex，在 /mcp 中检查 wind_index。Codex 官方文档说明其桌面端、CLI 和 IDE 扩展共享 MCP 配置，并支持 stdio 与 Streamable HTTP：Codex MCP 文档。

局域网 HTTP 模式

启动服务：

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
.\.venv\Scripts\python.exe -m index_mcp.run_http

当前配置：

• 本机地址：http://127.0.0.1:8765/mcp

• 局域网地址：http://172.18.3.114:8765/mcp

• 健康检查：http://172.18.3.114:8765/health

• MCP 端点必须携带 Authorization: Bearer <MCP_API_KEY>；

• /health 不要求 API Key，只返回 {"status":"ok"}。

如 Windows 防火墙阻止局域网连接，可在管理员 PowerShell 中只为本地子网开放端口：

New-NetFirewallRule -DisplayName 'WIND Index MCP 8765' `
  -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8765 `
  -RemoteAddress LocalSubnet

不要把 8765 端口直接映射到公网。跨不可信网络使用时，应在前置代理启用 HTTPS，并升级为 OAuth。

Codex 连接局域网服务

先在运行 Codex 的电脑上设置一个环境变量，其值为服务端 .env 中的 MCP_API_KEY：

$env:WIND_INDEX_MCP_API_KEY = '<从服务端安全复制 API Key>'

然后在 Codex config.toml 中配置：

[mcp_servers.wind_index_lan]
url = "http://172.18.3.114:8765/mcp"
bearer_token_env_var = "WIND_INDEX_MCP_API_KEY"
required = true
default_tools_approval_mode = "auto"

官方配置项 bearer_token_env_var 会从环境变量读取 Bearer Token，避免把密钥直接写入 config.toml。其他支持 Streamable HTTP 的 MCP 客户端使用同一 URL，并设置相同的 Authorization 请求头即可。

验证

运行自动化测试：

.\.venv\Scripts\python.exe -m pytest

验证 stdio 端到端调用：

.\.venv\Scripts\python.exe .\scripts\smoke_test.py stdio

HTTP 服务启动后，在另一个 PowerShell 窗口验证：

.\.venv\Scripts\python.exe .\scripts\smoke_test.py http

配置项

如果 DHCP 导致服务器局域网 IP 变化，需要同时更新 .env 中的 MCP_ALLOWED_HOSTS 和客户端 URL。

API Key 轮换

生成新 Key：

.\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(48))"

把输出写入服务端 .env 的 MCP_API_KEY，重启 HTTP 服务，再更新各客户端的环境变量。不要把 Key 提交到 Git、聊天记录或日志。

扩展其他表

每张新表或每组紧密相关的查询建立独立领域模块：

src/index_mcp/domains/<domain>/
├─ models.py
├─ repository.py
├─ service.py
└─ tools.py

Repository 只能保存固定、参数化的只读 SQL；Service 负责输入规范化和业务边界；Tools 负责 MCP 契约。在 server.py 注册新工具即可复用现有连接池、鉴权、日志和双传输入口。

安全说明

• .env 和 .venv 已被 Git 忽略；

• stdio 日志只写 stderr，不会污染 MCP 协议流；

• HTTP 使用 Bearer API Key 和 Host 白名单；

• CORS 默认关闭；

• API Key over HTTP 只适用于可信局域网，网络监听者仍可能截获明文流量；

• 数据库账号应在 Oracle 侧保持最小只读权限。