spark-mcp

56 Commits 1 Branch 2 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
tao.chenandClaude	f374ebfdb4	uploads,tools,config,main: 将 upload_file 返回路径改为服务器端绝对路径并透传给 spark_submit 之前 upload_file 把文件写到 DataDir/uploads/<filename>，返回相对路径 uploads/hello.txt。MCP 服务器与 agent 不在同一台机器，agent 无法构造服务器本地路径，因此 spark_submit 无法定位脚本。改为由新的 internal/uploads 包 mint 一个 32 字符十六进制 file_id，文件落盘为 DataDir/uploads/<file_id>，元数据写入 <file_id>.meta.json（原始文件名只存在 sidecar 里）。upload_file 返回 {file_id, path, name, size, sha256}，其中 path 是绝对路径。spark_submit 的 description 明确要求 LLM 直接把 upload_file 返回的 path 放进 args，不要自己构造路径。为什么只在描述里约束而不在代码里拒绝非 mint 的绝对路径：集群本地已有路径（如 /opt/spark/examples/pi.py）是合法的 spark-submit 参数，代码不能替 LLM 拒绝。测试锁定： - internal/uploads: Save 往返、AbsPath/Validate 非法路径、Sweep 过期/未过期/ 孤立 sidecar - internal/mcp/tools: upload_file 新响应字段、spark_submit 透传 mint 路径与集群本地路径刻意未做：S3/HDFS 上传、给 spark_submit 新增 file_id 参数、在代码层面拒绝集群本地绝对路径。破坏性变更：upload_file 响应从相对 path 改为绝对 path，并新增 file_id/name/ sha256 字段。该工具尚无外部调用者。 Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-13 19:13:14 +08:00
tao.chenandClaude	7f8960823b	config: GIN_MODE 改为环境变量配置 + Load() 自动加载 .env main.go 硬编码 gin.ReleaseMode 改成读 cfg.GinMode（默认 release），方便生产/调试切换 debug/release/test。Load() 开头先调 loadDotenv (".env"): 缺文件静默跳过，shell env 优先于 .env，跳过注释/空行/ 无 '=' 行并 slog.Warn。仅用标准库，不引新依赖。验证: - go build / go vet / go test 全部通过 - shell env 覆盖 .env (LISTEN_ADDR=:19090 覆盖 .env 的 :18080) - 仅 .env 时正确加载 (监听 18080, GIN_MODE=debug 输出 [GIN-debug]) - 无 .env 且无 shell env 时清晰报错 ADMIN_TOKENS is not set Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-13 13:48:35 +08:00
tao.chenandClaude	d6dd2b846f	Phase 6: 部署文档 + 启动脚本 + 配置样例 - README.md (英文): 项目概览 + 11 Tool 表格 + 12 env 变量全表 + 6 admin 端点 + 安全模型 (3 道防线 + 4 项额外保证) + dev 命令 - .env.example: 12 env 变量 + 默认值 + 必填标注 - scripts/dev.sh: 一键 build + 后台启动 (nohup + PID 文件) + healthz 验证 - scripts/seed.sh: admin POST 一个示例 cluster (从 .env 读 admin token) - ARCHITECTURE.md (中文): 包依赖图 + 数据流 + 11 Tool 分类 + 关键设计决策 - docs/runbook.md (中文): 部署 + 升级 + 故障排查 (401/404/422 等) - docs/systemd/spark-mcp-go.service: systemd unit 模板 README 安全模型小修正: 第 3 道防线从"spark_submit flag 白名单" (实际不存在) 改为 "upload_file 路径白名单", 加 Additional guarantees 小节列 slice form / json:"-" / 跨主机 redirect / per-tool log 权限。 Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-10 17:24:19 +08:00

Author

SHA1

Message

Date

tao.chenandClaude

f374ebfdb4

uploads,tools,config,main: 将 upload_file 返回路径改为服务器端绝对路径并透传给 spark_submit

之前 upload_file 把文件写到 DataDir/uploads/<filename>，返回相对路径
uploads/hello.txt。MCP 服务器与 agent 不在同一台机器，agent 无法构造服务
器本地路径，因此 spark_submit 无法定位脚本。

改为由新的 internal/uploads 包 mint 一个 32 字符十六进制 file_id，文件落盘为
DataDir/uploads/<file_id>，元数据写入 <file_id>.meta.json（原始文件名只存在
sidecar 里）。upload_file 返回 {file_id, path, name, size, sha256}，其中 path
是绝对路径。spark_submit 的 description 明确要求 LLM 直接把 upload_file 返回
的 path 放进 args，不要自己构造路径。

为什么只在描述里约束而不在代码里拒绝非 mint 的绝对路径：集群本地已有路径
（如 /opt/spark/examples/pi.py）是合法的 spark-submit 参数，代码不能替
LLM 拒绝。

测试锁定：
- internal/uploads: Save 往返、AbsPath/Validate 非法路径、Sweep 过期/未过期/
  孤立 sidecar
- internal/mcp/tools: upload_file 新响应字段、spark_submit 透传 mint 路径与
  集群本地路径

刻意未做：S3/HDFS 上传、给 spark_submit 新增 file_id 参数、在代码层面拒绝
集群本地绝对路径。

破坏性变更：upload_file 响应从相对 path 改为绝对 path，并新增 file_id/name/
sha256 字段。该工具尚无外部调用者。

Co-Authored-By: Claude <noreply@anthropic.com>

2026-07-13 19:13:14 +08:00

tao.chenandClaude

7f8960823b

config: GIN_MODE 改为环境变量配置 + Load() 自动加载 .env

main.go 硬编码 gin.ReleaseMode 改成读 cfg.GinMode（默认 release），
方便生产/调试切换 debug/release/test。Load() 开头先调 loadDotenv
(".env"): 缺文件静默跳过，shell env 优先于 .env，跳过注释/空行/
无 '=' 行并 slog.Warn。仅用标准库，不引新依赖。

验证:
  - go build / go vet / go test 全部通过
  - shell env 覆盖 .env (LISTEN_ADDR=:19090 覆盖 .env 的 :18080)
  - 仅 .env 时正确加载 (监听 18080, GIN_MODE=debug 输出 [GIN-debug])
  - 无 .env 且无 shell env 时清晰报错 ADMIN_TOKENS is not set

Co-Authored-By: Claude <noreply@anthropic.com>

2026-07-13 13:48:35 +08:00

tao.chenandClaude

d6dd2b846f

Phase 6: 部署文档 + 启动脚本 + 配置样例

- README.md (英文): 项目概览 + 11 Tool 表格 + 12 env 变量全表
  + 6 admin 端点 + 安全模型 (3 道防线 + 4 项额外保证) + dev 命令
- .env.example: 12 env 变量 + 默认值 + 必填标注
- scripts/dev.sh: 一键 build + 后台启动 (nohup + PID 文件) + healthz 验证
- scripts/seed.sh: admin POST 一个示例 cluster (从 .env 读 admin token)
- ARCHITECTURE.md (中文): 包依赖图 + 数据流 + 11 Tool 分类 + 关键设计决策
- docs/runbook.md (中文): 部署 + 升级 + 故障排查 (401/404/422 等)
- docs/systemd/spark-mcp-go.service: systemd unit 模板

README 安全模型小修正: 第 3 道防线从"spark_submit flag 白名单"
(实际不存在) 改为 "upload_file 路径白名单", 加 Additional guarantees
小节列 slice form / json:"-" / 跨主机 redirect / per-tool log 权限。

Co-Authored-By: Claude <noreply@anthropic.com>

2026-07-10 17:24:19 +08:00