绿科 MCP 服务集合（独立发行版 lvke-mcp）

本目录是独立的 MCP（Model Context Protocol）服务发行版，包名 lvke-mcp， 有自己的 pyproject.toml、src/ 布局和自有 runtime（src/lvke_mcp/runtime/）。

独立边界（MCP_INDEPENDENCE_PLAN §6.1、§10）： MCP 服务不读取、不调用、不依赖 Hermes（hermes_cli / tools / 根 pyproject）的任何代码、配置、环境变量或文件系统路径。 MCP 运行所需的配置（数据目录、临时目录、profile、Tavily key）全部来自 LVKE_MCP_* 自有环境变量，缺省落在 ~/.lvke/。不读取任何 HERMES_* 环境变量。 本目录内的 业务实现是 MCP 自有的领域代码，不是 Hermes 的复用层。

架构状态（2026-08-06）

• WP-01（独立 pyproject + runtime 骨架）已完成构建：mcp_servers/pyproject.toml、 src/lvke_mcp/runtime/（10 个直接搬移模块 + config.py / jobs.py 两个新模块）、 参考 server src/lvke_mcp/servers/scaffold/。验收标准（§29.3）：scaffold server 在 未安装 Hermes 且不依赖当前仓库根目录虚拟环境的干净 venv 中完成 initialize、 tools/list、call_tool、resources/list、resources/read。

• 纵向切片（§29.4）已完成：全部正式服务和支撑服务均由 src/lvke_mcp/servers/ 提供入口，业务实现位于 domains/，基础设施实现位于 adapters/ 和 runtime/。仓库根目录下的旧 server 兼容包已删除。

• 独立性扫描升级为 AST v2（2026-08-04）：scripts/independence_scan.py 改用 ast 解析，只统计真实 import / 动态加载 / HERMES_* 环境变量读取，不再把 docstring、注释、字符串字面量计为依赖。当前结果： forward（MCP → 外部）= 0，即 src/lvke_mcp 不调用任何其他项目代码； 新发行版只扫描和运行 src/lvke_mcp 自有代码，不保留旧顶层导入入口。

Related MCP server: MCP Business AI Transformation

核心业务工具面（十三个领域服务）

聚合参考服务

第 14 个进程 lvke-reference 原样路由档案、模板、客户、专家、政策、统计、 行业、环境和地图实现。finance-calc 的七类纯计算由 lvke-finance-model.finance_calculate 路由；excel-bridge 的五类工作簿检查由 lvke-source-files.source_inspect_workbook 路由。旧实现模块继续作为内部库存在， 种子数据、档案索引、公式和返回业务字段不迁移。

公开面固定为 14 个 Lvke MCP 进程、169 个工具。完整输入/输出 schema 仍由服务端 执行；tools/list 只发布紧凑输入投影，大型完整 schema 通过 lvke://schemas/<server>/<tool>/input Resource 按需读取。紧凑投影始终保留顶层参数、 必填项、容器类型及数组元素类型，只省略可按 Resource 读取的深层结构。以下稳定别名不依赖工具名： finance-spec-v3、asset-acquisition-spec、review-target、 review-finding-disposition、report-preparation、project-planning-candidate，以及 project-planning-validate/confirm/prepare/create， 均位于 lvke://schemas/ 下。85 项旧工具迁移关系见 dev-docs/config/mcp-compression-migration.json； 第二轮 32 项迁移见 dev-docs/config/mcp-compression-migration-v2.json。

统一 Resource 入口为 lvke-feasibility-delivery.lvke_list_resources 和 lvke_read_resource。asset-acquisition 域可分页列举并读取 spec、run、scenario matrix、工件、十三表 package、XLSX 和 13 个 CSV；URI 中的 workspace 必须与显式 workspace_id 一致，二进制内容以 base64 返回。

工作簿聚合契约为 source_inspect_workbook(workspace_id, file_id, operation, sheet?, range?, options?)；旧路径调用须先 source_import_local_path。地图聚合入口 公开 geo_query(..., limit?)，距离矩阵的确定性模式固定为 haversine_with_highway_estimate，不伪装成在线导航路线。 规划行业路由清单显式覆盖能源前缀和 solar_power 资产；合法 ProjectContext 不得因缺少 route 而回退到 generic 行业。

目录结构

mcp_servers/
├── pyproject.toml            # 独立发行版 lvke-mcp
├── README.md                 # 本文档
├── dev-docs/                 # 工程文档（架构、计划、验证与报告）
├── src/lvke_mcp/
│   ├── runtime/              # MCP 自有运行时（config/workspace/storage/resources/
│   │                         #  jobs/transport/stdio/errors/responses/schemas/logging）
│   ├── contracts/            # 领域契约（pydantic / JSON Schema），随切片填充
│   ├── domains/              # 领域业务层，随切片迁入
│   └── servers/
│       ├── scaffold/         # 参考 server（无 sys.path hack，零 Hermes 依赖）
│       └── <domain>/         # 14 个公开领域与参考 server
├── skills/                   # Skill 源码；Codex 插件发布 15 个非前端父 Skill
├── plugins/lvke-mcp/         # Codex 插件：14 个 MCP + 15 个 Skill
├── scripts/                  # 独立性扫描与基线工具
└── tests/

构建与安装

本项目使用 conda 管理环境（不用 venv）。环境名 lvke-mcp：

cd mcp_servers
conda create -y -n lvke-mcp python=3.13
conda run -n lvke-mcp python -m pip install -e .
conda run -n lvke-mcp python -m pip install pytest

conda 环境默认会把用户级 ~/.local/lib/pythonX.Y/site-packages 挂进 sys.path 且优先级高于环境自身，导致外部包 shadow 本项目的 exact-pin 依赖。 本环境已放置 zzz-no-user-site.pth 将其摘除，保证与旧 venv 同等隔离； 重建环境后需要重新放置，见「重建环境」。

单独运行一个 server（调试用）

scaffold（参考 server，运行后会通过 stdio 接收 JSON-RPC）：

cd mcp_servers
conda run -n lvke-mcp lvke-mcp-scaffold
# 或
conda run -n lvke-mcp python -m lvke_mcp.servers.scaffold.server

领域 server：

conda run -n lvke-mcp python -m lvke_mcp.servers.lvke_data_acquisition.server
conda run -n lvke-mcp python -m lvke_mcp.servers.lvke_finance_model.server
# 其余 server 使用 lvke_mcp.servers.<server>.server

重建环境

删除并重建后，必须重新隔离 user site，否则 ~/.local 里的包会 shadow 本项目 exact-pin 依赖（曾导致 starlette 未真正装进环境）：

SP="$(conda run -n lvke-mcp python -c 'import sysconfig;print(sysconfig.get_paths()["purelib"])')"
printf '%s\n' 'import site, sys; sys.path[:] = [p for p in sys.path if p != getattr(site, "USER_SITE", None)]' \
  > "$SP/zzz-no-user-site.pth"
# 自检：应输出 none
conda run -n lvke-mcp python -c "import sys;print([p for p in sys.path if '/.local/lib/python' in p] or 'none')"

在 Codex 中启用

使用 plugins/lvke-mcp/ 中的 Codex 插件发布 14 个 stdio MCP 和 15 个非前端 Skill。 完整安装、更新、范围和验证说明见 dev-docs/config/CODEX_USER_CONFIG.md。

本产品只有 MCP + Codex Skills；Tavily 是唯一联网 provider。产品不提供前端、语音、 协同办公、登录、身份、tenant、角色、RBAC、权限管理、安全审查或专业签审。

共用约定

1. 响应格式：内部旧 handler 保留 success/data/source 包装；正式服务使用明确字段， 并至少返回 success/status/resource_uris/warnings/blockers/next_actions。

2. 错误码命名：<server-name>.<error-tag>，如 mcp_lvke_archive.not_found。

3. 日志：使用 stderr（避免污染 stdio 协议），统一前缀 [mcp-<server>]。

4. 本地对象：MCP 交换对象存放于工作区 mcp_objects/，ID/URI 安全校验、原子写入且 内容不可变。

5. 测试：外部行为基线位于 tests/fixtures/baseline/，协议测试工具和 stdio smoke 驱动位于 src/lvke_mcp/testing/。

6. Agent 协调契约：正式 SDK Server 和 stdio fallback 都在响应中附加 coordination.contract_version=agent-coordination.v1。其中包含当前阶段、输入/输出对象 ID、质量状态、证据资格、结构化 next_actions、重试策略、恢复令牌和 lineage。该字段只帮助 Codex 在 MCP 重启、分支或失败后继续协调；它不把 MCP 变成工作流引擎，也不生成报告正文。

7. 职责边界：MCP 负责来源固化、确定性计算、十三表、版本和门禁；Codex 负责意图理解、 候选选择、冲突解释、章节写作和补资料循环；Skills 负责调用顺序和停止条件。partial、 missing_inputs、blocked、incomplete、failed 和 upstream_failure 均不是业务成功。

8. MCP 2.0 协议面：共用 runtime 同时支持 2024-11-05 至 2025-11-25 的 legacy initialize 握手和 2026-07-28 的逐请求 _meta envelope。server/discover、 tools/list 和 resources/list 只返回 private cache hint。规范 input_required 仅向 modern 客户端透传，legacy 客户端收到可操作的 blocked 结果。Tasks 仅在 服务显式注册持久化 TaskAdapter 后启用；现有短同步工具均为 taskSupport=forbidden。stdio 仍是生产默认，Streamable HTTP 只通过共享适配器显式构建。

开发新 MCP server

参考 src/lvke_mcp/servers/scaffold/：复制其 server.py 到 lvke_mcp/servers/<new-name>/ 后修改 SERVER_NAME / SERVER_VERSION 并注册具体工具。scaffold 的 build_server() 返回 lvke_mcp.runtime.transport.OfficialStdioServer，main() 调 serve_forever()。