This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 346972203f8 Clarify capability discovery guidance (#38756)
346972203f8 is described below
commit 346972203f8a95f66a01f23ee4366e2dd0ab145c
Author: Liang Zhang <[email protected]>
AuthorDate: Fri May 29 22:25:57 2026 +0800
Clarify capability discovery guidance (#38756)
* Clarify capability discovery guidance
Refine MCP runtime instructions and capability payload wording to describe
MCP list methods as the protocol surface discovery source.
Clarify that shardingsphere://capabilities provides ShardingSphere domain
capability guidance, workflow guidance, and side-effect notes, while keeping
the existing capability resource structure unchanged.
Update related tests to match the revised wording.
* Clarify capability discovery guidance
Refine MCP runtime instructions and capability payload wording to describe
MCP list methods as the protocol surface discovery source.
Clarify that shardingsphere://capabilities provides ShardingSphere domain
capability guidance, workflow guidance, and side-effect notes, while keeping
the existing capability resource structure unchanged.
Update related tests to match the revised wording.
---
.../shardingsphere-mcp/instructions/server-instructions.md | 4 ++--
.../handler/capability/ServerCapabilitiesHandlerTest.java | 5 +++--
.../support/descriptor/MCPModelFirstContractPayloadBuilder.java | 7 ++++---
.../descriptor/MCPModelFirstContractPayloadBuilderTest.java | 5 +++--
.../resources/baseline-contract/model-contract/capabilities.yaml | 9 +++++----
5 files changed, 17 insertions(+), 13 deletions(-)
diff --git
a/mcp/bootstrap/src/main/resources/META-INF/shardingsphere-mcp/instructions/server-instructions.md
b/mcp/bootstrap/src/main/resources/META-INF/shardingsphere-mcp/instructions/server-instructions.md
index 8ab80ce97b2..f45fff69eba 100644
---
a/mcp/bootstrap/src/main/resources/META-INF/shardingsphere-mcp/instructions/server-instructions.md
+++
b/mcp/bootstrap/src/main/resources/META-INF/shardingsphere-mcp/instructions/server-instructions.md
@@ -17,9 +17,9 @@
Apache ShardingSphere MCP.
-Use official MCP list discovery methods (`tools/list`, `resources/list`,
`resources/templates/list`, `prompts/list`) for the public surface.
+Use MCP list methods (`tools/list`, `resources/list`,
`resources/templates/list`, `prompts/list`) to discover the protocol surface.
-Use `completion/complete` for supported argument values, and read
`shardingsphere://capabilities` only as optional ShardingSphere domain catalog
guidance.
+Use `completion/complete` for supported argument values. Read
`shardingsphere://capabilities` when ShardingSphere domain capability guidance,
workflow guidance, or side-effect notes are needed.
Use `database_gateway_execute_query` only for classifier-approved `SELECT` or
`EXPLAIN ANALYZE`.
Use `database_gateway_execute_update` with `execution_mode=preview` before
side effects.
diff --git
a/mcp/core/src/test/java/org/apache/shardingsphere/mcp/core/resource/handler/capability/ServerCapabilitiesHandlerTest.java
b/mcp/core/src/test/java/org/apache/shardingsphere/mcp/core/resource/handler/capability/ServerCapabilitiesHandlerTest.java
index eb84a97f46a..be4601db195 100644
---
a/mcp/core/src/test/java/org/apache/shardingsphere/mcp/core/resource/handler/capability/ServerCapabilitiesHandlerTest.java
+++
b/mcp/core/src/test/java/org/apache/shardingsphere/mcp/core/resource/handler/capability/ServerCapabilitiesHandlerTest.java
@@ -99,7 +99,8 @@ class ServerCapabilitiesHandlerTest {
Map<?, ?> actual = (Map<?, ?>) capabilities.get("model_first_summary");
assertThat(actual.get("official_discovery_methods"),
is(createOfficialDiscoveryMethods()));
assertThat(actual.get("argument_completion_method"),
is("completion/complete"));
- assertThat(actual.get("catalog_resource_role"),
is("shardingsphere://capabilities is an optional ShardingSphere domain catalog
resource, not the MCP protocol discovery source."));
+ assertThat(actual.get("catalog_resource_role"),
+ is("shardingsphere://capabilities complements MCP list methods
with ShardingSphere domain capability guidance, workflow guidance, and
side-effect notes."));
assertThat(actual.get("optional_catalog_resource"),
is("shardingsphere://capabilities"));
assertFalse(actual.containsKey("safe_first_resource"));
Map<?, ?> metadataRule = (Map<?, ?>) actual.get("metadata_rule");
@@ -119,7 +120,7 @@ class ServerCapabilitiesHandlerTest {
private void assertModelContract(final Map<String, Object> capabilities) {
Map<?, ?> actual = (Map<?, ?>) capabilities.get("model_contract");
- assertThat(actual.get("public_surface_source"), is("Official MCP list
methods: tools/list, resources/list, resources/templates/list, prompts/list."));
+ assertThat(actual.get("public_surface_source"), is("MCP list methods
expose the protocol surface: tools/list, resources/list,
resources/templates/list, prompts/list."));
assertThat(actual.get("official_discovery_methods"),
is(createOfficialDiscoveryMethods()));
assertThat(actual.get("argument_completion_method"),
is("completion/complete"));
assertThat(actual.get("optional_catalog_resource"),
is("shardingsphere://capabilities"));
diff --git
a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilder.java
b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilder.java
index 03109235fe3..1434d25b520 100644
---
a/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilder.java
+++
b/mcp/support/src/main/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilder.java
@@ -39,7 +39,7 @@ final class MCPModelFirstContractPayloadBuilder {
private static final String ARGUMENT_COMPLETION_METHOD =
"completion/complete";
- private static final String OFFICIAL_DISCOVERY_SOURCE = "Official MCP list
methods: tools/list, resources/list, resources/templates/list, prompts/list.";
+ private static final String MCP_LIST_METHODS_SOURCE = "MCP list methods
expose the protocol surface: tools/list, resources/list,
resources/templates/list, prompts/list.";
private final MCPDescriptorCatalog catalog;
@@ -47,7 +47,8 @@ final class MCPModelFirstContractPayloadBuilder {
Map<String, Object> result = new LinkedHashMap<>(10, 1F);
result.put("official_discovery_methods",
createOfficialDiscoveryMethods());
result.put("argument_completion_method", ARGUMENT_COMPLETION_METHOD);
- result.put("catalog_resource_role", CATALOG_RESOURCE_URI + " is an
optional ShardingSphere domain catalog resource, not the MCP protocol discovery
source.");
+ result.put("catalog_resource_role", CATALOG_RESOURCE_URI
+ + " complements MCP list methods with ShardingSphere domain
capability guidance, workflow guidance, and side-effect notes.");
result.put("optional_catalog_resource", CATALOG_RESOURCE_URI);
result.put("metadata_rule", createMetadataRule());
result.put("sql_tool_selection", createSqlToolSelection());
@@ -60,7 +61,7 @@ final class MCPModelFirstContractPayloadBuilder {
Map<String, Object> createModelContract() {
Map<String, Object> result = new LinkedHashMap<>(11, 1F);
- result.put("public_surface_source", OFFICIAL_DISCOVERY_SOURCE);
+ result.put("public_surface_source", MCP_LIST_METHODS_SOURCE);
result.put("official_discovery_methods",
createOfficialDiscoveryMethods());
result.put("argument_completion_method", ARGUMENT_COMPLETION_METHOD);
result.put("optional_catalog_resource", CATALOG_RESOURCE_URI);
diff --git
a/mcp/support/src/test/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilderTest.java
b/mcp/support/src/test/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilderTest.java
index 450a78cef04..c223f343c10 100644
---
a/mcp/support/src/test/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilderTest.java
+++
b/mcp/support/src/test/java/org/apache/shardingsphere/mcp/support/descriptor/MCPModelFirstContractPayloadBuilderTest.java
@@ -37,7 +37,8 @@ class MCPModelFirstContractPayloadBuilderTest {
Map<String, Object> actual = builder.createModelFirstSummary();
assertThat(castToMap(actual.get("official_discovery_methods")),
is(createOfficialDiscoveryMethods()));
assertThat(actual.get("argument_completion_method"),
is("completion/complete"));
- assertThat(actual.get("catalog_resource_role"),
is("shardingsphere://capabilities is an optional ShardingSphere domain catalog
resource, not the MCP protocol discovery source."));
+ assertThat(actual.get("catalog_resource_role"),
+ is("shardingsphere://capabilities complements MCP list methods
with ShardingSphere domain capability guidance, workflow guidance, and
side-effect notes."));
assertThat(actual.get("optional_catalog_resource"),
is("shardingsphere://capabilities"));
assertFalse(actual.containsKey("safe_first_resource"));
assertThat(castToMap(castToMap(actual.get("sql_tool_selection")).get("side_effecting")).get("execute_requires"),
is("execution_mode=execute"));
@@ -50,7 +51,7 @@ class MCPModelFirstContractPayloadBuilderTest {
@Test
void assertCreateModelContract() {
Map<String, Object> actual = builder.createModelContract();
- assertThat(actual.get("public_surface_source"), is("Official MCP list
methods: tools/list, resources/list, resources/templates/list, prompts/list."));
+ assertThat(actual.get("public_surface_source"), is("MCP list methods
expose the protocol surface: tools/list, resources/list,
resources/templates/list, prompts/list."));
assertThat(castToMap(actual.get("official_discovery_methods")),
is(createOfficialDiscoveryMethods()));
assertThat(actual.get("argument_completion_method"),
is("completion/complete"));
assertThat(actual.get("optional_catalog_resource"),
is("shardingsphere://capabilities"));
diff --git
a/test/e2e/mcp/src/test/resources/baseline-contract/model-contract/capabilities.yaml
b/test/e2e/mcp/src/test/resources/baseline-contract/model-contract/capabilities.yaml
index 9359004a607..cfac7e92c06 100644
---
a/test/e2e/mcp/src/test/resources/baseline-contract/model-contract/capabilities.yaml
+++
b/test/e2e/mcp/src/test/resources/baseline-contract/model-contract/capabilities.yaml
@@ -20,8 +20,9 @@ model_first_summary:
official_discovery_methods: {tools: tools/list, resources: resources/list,
resource_templates: resources/templates/list,
prompts: prompts/list}
argument_completion_method: completion/complete
- catalog_resource_role: shardingsphere://capabilities is an optional
ShardingSphere
- domain catalog resource, not the MCP protocol discovery source.
+ catalog_resource_role: shardingsphere://capabilities complements MCP list
methods
+ with ShardingSphere domain capability guidance, workflow guidance, and
side-effect
+ notes.
optional_catalog_resource: shardingsphere://capabilities
metadata_rule: {first_resource: 'shardingsphere://databases', search_tool:
database_gateway_search_metadata,
detail_rule: Read the returned resource.uri when the list or search
response points
@@ -43,8 +44,8 @@ model_first_summary:
recovery_rule: Follow structured recovery.next_actions before inventing a
replacement
call.
model_contract:
- public_surface_source: 'Official MCP list methods: tools/list,
resources/list, resources/templates/list,
- prompts/list.'
+ public_surface_source: 'MCP list methods expose the protocol surface:
tools/list,
+ resources/list, resources/templates/list, prompts/list.'
official_discovery_methods: {tools: tools/list, resources: resources/list,
resource_templates: resources/templates/list,
prompts: prompts/list}
argument_completion_method: completion/complete
