eemario opened a new pull request, #1303: URL: https://github.com/apache/flink-agents/pull/1303
<!-- * Thank you very much for contributing to Flink Agents. * Please add the relevant components in the PR title. E.g., [api], [runtime], [java], [python], [hotfix], etc. --> <!-- Please link the PR to the relevant issue(s). Hotfix doesn't need this. --> Linked issue: #1296 ### Purpose of change <!-- What is the purpose of this change? --> YAML users can now load the documented `mcp_servers` declaration with `clazz: mcp`. Both loaders resolve the alias to the built-in Python MCP server, and Java-loaded YAML can carry that Python descriptor through plan construction to the existing runtime MCP discovery path. #### Runtime flow The YAML loader resolves `mcp` to `flink_agents.integrations.mcp.mcp.MCPServer`. The Python loader builds its normal Python descriptor. The Java loader now admits `MCP_SERVER` as a Python resource and builds a `PythonResourceDescriptor`; `AgentPlan` converts descriptor-based Python MCP entries into `PythonResourceProvider`s, and operator initialization uses the existing `PythonMCPResourceDiscovery` path to register the remote tools and prompts. #### Key decisions - Keep `clazz` required and add the missing alias instead of introducing an MCP-only YAML spec. This preserves the common `DescriptorSpec` and checked-in JSON Schema. - Accept only Python MCP descriptors from the Java Agent resource map. Native Java MCP declarations still use `@MCPServer`, whose compile-time discovery registers tools and prompts before execution. ### Behavioral Semantics <!-- For a non-trivial code change whose implementation is largely AI-assisted: interaction decisions, behavioral contracts, and failure behavior. See `contribution-guides/ai-assisted-pr.md`. Remove this heading and this comment otherwise. --> #### Interaction decisions | YAML loader | MCP implementation | Result | |---|---|---| | Python | `type: python` or omitted | `mcp` resolves to the built-in Python MCP server. | | Python | `type: java` | Rejected as before because Python-loaded YAML has no Java MCP wrapper. | | Java | `type: python` or omitted | Builds a Python provider and discovers tools/prompts during operator initialization. | | Java | `type: java` | Descriptor-based registration remains unsupported; use `@MCPServer`. | #### Behavioral contracts 1. `clazz: mcp` resolves to `flink_agents.integrations.mcp.mcp.MCPServer` in both YAML loaders. 2. Agent-level and shared MCP declarations preserve their endpoint arguments and produce Python descriptors. 3. Java-loaded Python MCP declarations survive `AgentPlan` construction as `PythonResourceProvider`s and reach the existing runtime discovery path. 4. Descriptor-based Java MCP registration still fails with guidance to use `@MCPServer`. #### Failure behavior - Unsupported `type: java` declarations in the Python loader continue to raise during YAML loading. - Java MCP descriptors added through the Agent resource map continue to raise during plan construction rather than creating a provider without discovered tools or prompts. - Remote MCP connection and discovery failures are unchanged and propagate from the existing MCP discovery paths. ### Tests <!-- How is this change verified? --> | Contract | Tests | |---|---| | Both loaders resolve `mcp` | `test_resolve_clazz_replaces_mcp_alias`, `clazzAliasCoversPythonMCPServer`, `descriptorPythonMCPServerResolvesAlias` | | Agent/shared declarations produce Python descriptors | `test_build_agents_resolves_mcp_alias_at_both_scopes`, `mcpServersSupportAgentAndSharedPythonResources` | | Java YAML reaches a Python provider | `testYamlPythonMCPServerUsesPythonResourceProvider` | | Java descriptor registration remains rejected | `testAddResourceMCPServerRejectedWithGuidance` | | Existing runtime discovery consumes the provider | `PythonMCPResourceDiscoveryTest` | Verification: - `PYTHONPATH="$PWD:<venv-purelib>" uv run --no-sync python -m pytest flink_agents/api/yaml/tests/test_aliases.py flink_agents/api/yaml/tests/test_loader.py -q` — 73 passed. - `mvn -pl runtime -am -Dtest=AliasesTest,YamlLoaderBuildersTest,YamlLoaderBuildAgentsTest,AgentPlanTest,PythonMCPResourceDiscoveryTest -Dsurefire.failIfNoSpecifiedTests=false -Dspotless.skip=true test` — 75 passed across API, Plan, and Runtime. - `./tools/lint.sh --check` — passed. Not verified: a live external MCP server end-to-end run; the existing discovery unit test uses a mocked Python adapter. ### API <!-- Does this change touches any public APIs? --> This is an additive YAML behavior change. Existing fully qualified class declarations and the requirement to provide `clazz` remain unchanged. Existing native Java `@MCPServer` declarations are unchanged. Java-loaded YAML newly supports the documented Python MCP declaration. ### Documentation <!-- Do not remove this section. Check the proper box only. --> - [ ] `doc-needed` <!-- Your PR changes impact docs --> - [ ] `doc-not-needed` <!-- Your PR changes do not impact docs --> - [x] `doc-included` <!-- Your PR already contains the necessary documentation updates --> ### Was this patch authored or co-authored using generative AI tooling? <!-- Do not remove this section. Check the proper box only. --> - [x] Yes - [ ] No Generated-by: Codex CLI 0.158.0-alpha.2.1 (mode-ed9921cee0ec46e59a12b1b9e2d913b5) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
