feat: add external job tools + improve LLM-facing tool descriptions

Add 3 new MCP tools for inspecting YARN applications NOT submitted
through this service: get_external_job_logs, get_external_job_status,
get_external_job_result. Each takes application_id + connection_name
and queries YARN directly, bypassing the local JobStore.

- spark_executor/tools/external_jobs.py: 3 tool functions
- spark_executor/tools/requests.py: 3 new Pydantic body models
  (ExternalJobLogsRequest, ExternalJobStatusRequest,
  ExternalJobResultRequest)
- spark_executor/server.py: 3 new POST routes with explicit operation_id
- tests/unit/test_external_jobs.py: 7 unit tests
- tests/integration/test_mcp_routes.py: assert 20 tool routes
- README.md: list the 3 new tools

To make the LLM pick the right tool and not guess at field values,
also:

- Add Pydantic field descriptions for 22 fields across 8 request models
  (SaveConnectionRequest, UpdatePendingJobRequest, GetJobLogsRequest,
  JobIdRequest, PendingIdRequest, ConnectionNameRequest, plus the new
  ExternalJob*Request models).
- Update 12 route descriptions with cross-references, prerequisite
  context, and 400 behavior notes.
- Refactor _unknown_job_error: an input that looks like a YARN
  application_id (starts with 'application_') now returns HTTP 400
  (ValueError) with a hint message naming the right external tool;
  other not-found cases still return 404 (KeyError). This catches the
  common LLM mistake of passing application_id to the internal
  get_job_* / kill_job tools.
- 4 new unit tests for the 400 behavior.

Tests: 356 passed (up from 242).

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

This commit is contained in:

Claude

2026-07-08 20:03:40 +08:00

co-authored by

Claude Fable 5

parent e285dc0f66

commit 6cf68439a2

14 changed files with 687 additions and 57 deletions

									
										README.md
									
		+3
		
												View File
												
				@@ -117,6 +117,9 @@ MCP 客户端需要先执行 `initialize` 握手，拿到 `mcp-session-id` 后

				| `get_job_result` | 查询终态结果视图 |

				| `get_job_logs` | 拉取 YARN 聚合日志 |

				| `kill_job` | Kill YARN application |

				| `get_external_job_status` | 查询**非本服务提交**的外部 YARN application 状态（按 `application_id` + `connection_name`） |

				| `get_external_job_result` | 查询外部 YARN application 终态结果视图 |

				| `get_external_job_logs` | 拉取外部 YARN application 的聚合日志 |

				### Files MCP 工具