Skip to content

Commit 7adf096

Browse files
codeboyzhoucodeboyzhou
committed
refactor(Prompts, Resources, Tools): Enhance prompt and tool descriptions with titles and improve error messages for clarity
1 parent 8ac9835 commit 7adf096

9 files changed

Lines changed: 156 additions & 71 deletions

File tree

‎mcp-server-filesystem/mcp-server-filesystem-declarative-sdk-implementation/src/main/java/com/github/mcp/server/filesystem/declarative/Prompts.java‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,16 +25,20 @@ public final class Prompts {
2525
* @return The prompt message
2626
* @see Tools#find(String, String)
2727
*/
28-
@McpPrompt(description = "description_for_find")
28+
@McpPrompt(
29+
title = "mcp.server.filesystem.prompt.find.title",
30+
description = "mcp.server.filesystem.prompt.find.description")
2931
public static String find(
3032
@McpPromptParam(
3133
name = "start",
32-
description = "description_for_find_param_start",
34+
title = "mcp.server.filesystem.prompt.find.param.start.title",
35+
description = "mcp.server.filesystem.prompt.find.param.start.description",
3336
required = true)
3437
String start,
3538
@McpPromptParam(
3639
name = "name",
37-
description = "description_for_find_param_name",
40+
title = "mcp.server.filesystem.prompt.find.param.name.title",
41+
description = "mcp.server.filesystem.prompt.find.param.name.description",
3842
required = true)
3943
String name) {
4044

@@ -43,7 +47,7 @@ public static String find(
4347
}
4448

4549
if (name == null || name.isBlank()) {
46-
return "Please provide a valid file/directory name to find.";
50+
return "Please provide a valid file/dir name to find.";
4751
}
4852

4953
return String.format(
@@ -58,18 +62,21 @@ public static String find(
5862
* @return The prompt message
5963
* @see Tools#read(String)
6064
*/
61-
@McpPrompt(description = "description_for_read")
65+
@McpPrompt(
66+
title = "mcp.server.filesystem.prompt.read.title",
67+
description = "mcp.server.filesystem.prompt.read.description")
6268
public static String read(
6369
@McpPromptParam(
6470
name = "path",
65-
description = "description_for_read_param_path",
71+
title = "mcp.server.filesystem.prompt.read.param.path.title",
72+
description = "mcp.server.filesystem.prompt.read.param.path.description",
6673
required = true)
6774
String path) {
6875

6976
if (path == null || path.isBlank()) {
7077
return "Please provide a valid path to read.";
7178
}
72-
return "Call the MCP tool 'read' to read the file or directory: " + path;
79+
return "Call the MCP tool 'read' to read the file or dir: " + path;
7380
}
7481

7582
/**
@@ -79,17 +86,20 @@ public static String read(
7986
* @return The prompt message
8087
* @see Tools#delete(String)
8188
*/
82-
@McpPrompt(description = "description_for_delete")
89+
@McpPrompt(
90+
title = "mcp.server.filesystem.prompt.delete.title",
91+
description = "mcp.server.filesystem.prompt.delete.description")
8392
public static String delete(
8493
@McpPromptParam(
8594
name = "path",
86-
description = "description_for_delete_param_path",
95+
title = "mcp.server.filesystem.prompt.delete.param.path.title",
96+
description = "mcp.server.filesystem.prompt.delete.param.path.description",
8797
required = true)
8898
String path) {
8999

90100
if (path == null || path.isBlank()) {
91101
return "Please provide a valid path to delete.";
92102
}
93-
return "Call the MCP tool 'delete' to delete the file or directory: " + path;
103+
return "Call the MCP tool 'delete' to delete the file or dir: " + path;
94104
}
95105
}

‎mcp-server-filesystem/mcp-server-filesystem-declarative-sdk-implementation/src/main/java/com/github/mcp/server/filesystem/declarative/Resources.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ public final class Resources {
1515
@McpResource(
1616
uri = "file://system",
1717
name = "filesystem",
18-
description = "filesystem_resource_description")
18+
title = "mcp.server.filesystem.resource.filesystem.title",
19+
description = "mcp.server.filesystem.resource.filesystem.description")
1920
public String filesystem() {
2021
return "No real contents, just an example";
2122
}

‎mcp-server-filesystem/mcp-server-filesystem-declarative-sdk-implementation/src/main/java/com/github/mcp/server/filesystem/declarative/Tools.java‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,19 @@ public final class Tools {
3333
*
3434
* @return A list of absolute path strings for all matching entries found during the search.
3535
*/
36-
@McpTool(description = "description_for_find")
36+
@McpTool(
37+
title = "mcp.server.filesystem.tool.find.title",
38+
description = "mcp.server.filesystem.tool.find.description")
3739
public String find(
3840
@McpToolParam(
3941
name = "start",
40-
description = "description_for_find_param_start",
42+
description = "mcp.server.filesystem.tool.find.param.start.description",
4143
required = true)
4244
String start,
43-
@McpToolParam(name = "name", description = "description_for_find_param_name", required = true)
45+
@McpToolParam(
46+
name = "name",
47+
description = "mcp.server.filesystem.tool.find.param.name.description",
48+
required = true)
4449
String name) {
4550

4651
if (start == null || start.isBlank()) {
@@ -52,19 +57,18 @@ public String find(
5257
}
5358

5459
if (name == null || name.isBlank()) {
55-
return "Please provide a valid file/directory name to find.";
60+
return "Please provide a valid file/dir name to find.";
5661
}
5762

5863
try {
5964
List<String> paths = FileHelper.fuzzySearch(start, name);
6065
if (paths.isEmpty()) {
61-
return String.format("No file (or directory) found with name '%s'", name);
62-
} else {
63-
return String.format("The following are the search results of name '%s': %s", name, paths);
66+
return String.format("No file/dir found with name '%s'", name);
6467
}
68+
return String.format("Found files/dirs with name '%s': %s", name, paths);
6569
} catch (IOException e) {
6670
final String result =
67-
String.format("Error searching file: %s, %s: %s", name, e, e.getMessage());
71+
String.format("Error finding file/dir: %s, %s: %s", name, e, e.getMessage());
6872
log.error(result, e);
6973
return result;
7074
}
@@ -84,9 +88,14 @@ public String find(
8488
* (immediate subdirectories and files) directly under the specified directory
8589
* (non-recursive).
8690
*/
87-
@McpTool(description = "description_for_read")
91+
@McpTool(
92+
title = "mcp.server.filesystem.tool.read.title",
93+
description = "mcp.server.filesystem.tool.read.description")
8894
public String read(
89-
@McpToolParam(name = "path", description = "description_for_read_param_path", required = true)
95+
@McpToolParam(
96+
name = "path",
97+
description = "mcp.server.filesystem.tool.read.param.path.description",
98+
required = true)
9099
String path) {
91100

92101
if (path == null || path.isBlank()) {
@@ -101,10 +110,10 @@ public String read(
101110
if (Files.isDirectory(filepath)) {
102111
try {
103112
List<String> paths = FileHelper.listDirectory(path);
104-
return String.format("The directory '%s' contains: %s", path, paths);
113+
return String.format("The dir '%s' contains: %s", path, paths);
105114
} catch (IOException e) {
106115
final String result =
107-
String.format("Error reading directory: %s, %s: %s", path, e, e.getMessage());
116+
String.format("Error reading dir: %s, %s: %s", path, e, e.getMessage());
108117
log.error(result, e);
109118
return result;
110119
}
@@ -126,11 +135,13 @@ public String read(
126135
* @param path The path to delete, can be a file or directory, required.
127136
* @return A message indicating whether the path was successfully deleted or not.
128137
*/
129-
@McpTool(description = "description_for_delete")
138+
@McpTool(
139+
title = "mcp.server.filesystem.tool.delete.title",
140+
description = "mcp.server.filesystem.tool.delete.description")
130141
public String delete(
131142
@McpToolParam(
132143
name = "path",
133-
description = "description_for_delete_param_path",
144+
description = "mcp.server.filesystem.tool.delete.param.path.description",
134145
required = true)
135146
String path) {
136147

@@ -140,10 +151,12 @@ public String delete(
140151

141152
try {
142153
final boolean deleted = Files.deleteIfExists(Path.of(path));
143-
return (deleted ? "Successfully deleted path: " : "Failed to delete path: ") + path;
154+
if (deleted) {
155+
return String.format("Successfully deleted: %s", path);
156+
}
157+
return String.format("Failed to delete: %s", path);
144158
} catch (IOException e) {
145-
final String result =
146-
String.format("Error deleting path: %s, %s: %s", path, e, e.getMessage());
159+
final String result = String.format("Error deleting: %s, %s: %s", path, e, e.getMessage());
147160
log.error(result, e);
148161
return result;
149162
}

‎mcp-server-filesystem/mcp-server-filesystem-declarative-sdk-implementation/src/main/resources/i18n/mcp_server_component_descriptions.properties‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,35 @@
1-
# Resource descriptions
2-
filesystem_resource_description=File system operations interface
1+
# Resource information
2+
mcp.server.filesystem.resource.filesystem.title=Filesystem
3+
mcp.server.filesystem.resource.filesystem.description=File system operations interface
34

4-
# Prompt/Tool descriptions
5-
description_for_find=Start from the specified path and recursively search subitems.
6-
description_for_find_param_start=The starting path to search, required.
7-
description_for_find_param_name=The name of the target file or directory to search, supports fuzzy matching, required.
5+
# Prompt information
6+
mcp.server.filesystem.prompt.find.title=file/dir search
7+
mcp.server.filesystem.prompt.find.description=Start from the specified path and recursively search subitems.
8+
mcp.server.filesystem.prompt.find.param.start.title=starting path
9+
mcp.server.filesystem.prompt.find.param.start.description=The starting path to search, required.
10+
mcp.server.filesystem.prompt.find.param.name.title=target file/dir name
11+
mcp.server.filesystem.prompt.find.param.name.description=The name of the target file or dir to search, fuzzy matching supported, required.
812

9-
description_for_read=Read a file or list directory contents non-recursively.
10-
description_for_read_param_path=The path to read, can be a file or directory, required.
13+
mcp.server.filesystem.prompt.read.title=file/dir read
14+
mcp.server.filesystem.prompt.read.description=Read a file or list dir contents non-recursively.
15+
mcp.server.filesystem.prompt.read.param.path.title=target file/dir path
16+
mcp.server.filesystem.prompt.read.param.path.description=The path to read, can be a file or dir, required.
1117

12-
description_for_delete=Delete a file or directory from the filesystem.
13-
description_for_delete_param_path=The path to delete, can be a file or directory, required.
18+
mcp.server.filesystem.prompt.delete.title=file/dir delete
19+
mcp.server.filesystem.prompt.delete.description=Delete a file or dir from the filesystem.
20+
mcp.server.filesystem.prompt.delete.param.path.title=target file/dir path
21+
mcp.server.filesystem.prompt.delete.param.path.description=The path to delete, can be a file or dir, required.
22+
23+
# Tool information
24+
mcp.server.filesystem.tool.find.title=file/dir search
25+
mcp.server.filesystem.tool.find.description=Start from the specified path and recursively search subitems.
26+
mcp.server.filesystem.tool.find.param.start.description=The starting path to search, required.
27+
mcp.server.filesystem.tool.find.param.name.description=The name of the target file or dir to search, fuzzy matching supported, required.
28+
29+
mcp.server.filesystem.tool.read.title=file/dir read
30+
mcp.server.filesystem.tool.read.description=Read a file or list dir contents non-recursively.
31+
mcp.server.filesystem.tool.read.param.path.description=The path to read, can be a file or dir, required.
32+
33+
mcp.server.filesystem.tool.delete.title=file/dir delete
34+
mcp.server.filesystem.tool.delete.description=Delete a file or dir from the filesystem.
35+
mcp.server.filesystem.tool.delete.param.path.description=The path to delete, can be a file or dir, required.

‎mcp-server-filesystem/mcp-server-filesystem-declarative-sdk-implementation/src/main/resources/i18n/mcp_server_component_descriptions_zh_CN.properties‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,35 @@
1-
# Resource descriptions
2-
filesystem_resource_description=\u6587\u4EF6\u7CFB\u7EDF\u64CD\u4F5C\u63A5\u53E3
1+
# Resource information
2+
mcp.server.filesystem.resource.filesystem.title=Filesystem
3+
mcp.server.filesystem.resource.filesystem.description=File system operations interface
34

4-
# Prompt/Tool descriptions
5-
description_for_find=\u4ECE\u6307\u5B9A\u7684\u8DEF\u5F84\u5F00\u59CB\u9012\u5F52\u641C\u7D22\u5B50\u9879
6-
description_for_find_param_start=\u5F85\u641C\u7D22\u7684\u8D77\u59CB\u8DEF\u5F84\uFF0C\u5FC5\u586B
7-
description_for_find_param_name=\u9700\u8981\u641C\u7D22\u7684\u76EE\u6807\u6587\u4EF6\u6216\u76EE\u5F55\u540D\uFF0C\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u5FC5\u586B
5+
# Prompt information
6+
mcp.server.filesystem.prompt.find.title=\u6587\u4EF6/\u76EE\u5F55\u641C\u7D22
7+
mcp.server.filesystem.prompt.find.description=\u4ECE\u6307\u5B9A\u8DEF\u5F84\u5F00\u59CB\u9012\u5F52\u641C\u7D22\u5B50\u9879
8+
mcp.server.filesystem.prompt.find.param.start.title=\u8D77\u59CB\u8DEF\u5F84
9+
mcp.server.filesystem.prompt.find.param.start.description=\u641C\u7D22\u7684\u8D77\u59CB\u8DEF\u5F84\uFF0C\u5FC5\u586B\u9879
10+
mcp.server.filesystem.prompt.find.param.name.title=\u76EE\u6807\u6587\u4EF6/\u76EE\u5F55\u540D\u79F0
11+
mcp.server.filesystem.prompt.find.param.name.description=\u76EE\u6807\u6587\u4EF6\u6216\u76EE\u5F55\u7684\u540D\u79F0\uFF0C\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u5FC5\u586B\u9879
812

9-
description_for_read=\u975E\u9012\u5F52\u8BFB\u53D6\u6587\u4EF6\u6216\u5217\u51FA\u76EE\u5F55\u5185\u5BB9
10-
description_for_read_param_path=\u5F85\u8BFB\u53D6\u7684\u8DEF\u5F84\uFF0C\u53EF\u4EE5\u662F\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B
13+
mcp.server.filesystem.prompt.read.title=\u6587\u4EF6/\u76EE\u5F55\u8BFB\u53D6
14+
mcp.server.filesystem.prompt.read.description=\u8BFB\u53D6\u6587\u4EF6\u6216\u975E\u9012\u5F52\u5217\u51FA\u76EE\u5F55\u5185\u5BB9
15+
mcp.server.filesystem.prompt.read.param.path.title=\u76EE\u6807\u6587\u4EF6/\u76EE\u5F55\u8DEF\u5F84
16+
mcp.server.filesystem.prompt.read.param.path.description=\u8981\u8BFB\u53D6\u7684\u8DEF\u5F84\uFF0C\u53EF\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B\u9879
1117

12-
description_for_delete=\u4ECE\u6587\u4EF6\u7CFB\u7EDF\u4E2D\u5220\u9664\u6587\u4EF6\u6216\u76EE\u5F55
13-
description_for_delete_param_path=\u5F85\u5220\u9664\u7684\u8DEF\u5F84\uFF0C\u53EF\u4EE5\u662F\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B
18+
mcp.server.filesystem.prompt.delete.title=\u6587\u4EF6/\u76EE\u5F55\u5220\u9664
19+
mcp.server.filesystem.prompt.delete.description=\u5220\u9664\u6587\u4EF6\u7CFB\u7EDF\u4E2D\u7684\u6587\u4EF6\u6216\u76EE\u5F55
20+
mcp.server.filesystem.prompt.delete.param.path.title=\u76EE\u6807\u6587\u4EF6/\u76EE\u5F55\u8DEF\u5F84
21+
mcp.server.filesystem.prompt.delete.param.path.description=\u8981\u5220\u9664\u7684\u8DEF\u5F84\uFF0C\u53EF\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B\u9879
22+
23+
# Tool information
24+
mcp.server.filesystem.tool.find.title=\u6587\u4EF6/\u76EE\u5F55\u641C\u7D22
25+
mcp.server.filesystem.tool.find.description=\u4ECE\u6307\u5B9A\u8DEF\u5F84\u5F00\u59CB\u9012\u5F52\u641C\u7D22\u5B50\u9879
26+
mcp.server.filesystem.tool.find.param.start.description=\u641C\u7D22\u7684\u8D77\u59CB\u8DEF\u5F84\uFF0C\u5FC5\u586B\u9879
27+
mcp.server.filesystem.tool.find.param.name.description=\u76EE\u6807\u6587\u4EF6\u6216\u76EE\u5F55\u7684\u540D\u79F0\uFF0C\u652F\u6301\u6A21\u7CCA\u5339\u914D\uFF0C\u5FC5\u586B\u9879
28+
29+
mcp.server.filesystem.tool.read.title=\u6587\u4EF6/\u76EE\u5F55\u8BFB\u53D6
30+
mcp.server.filesystem.tool.read.description=\u8BFB\u53D6\u6587\u4EF6\u6216\u975E\u9012\u5F52\u5217\u51FA\u76EE\u5F55\u5185\u5BB9
31+
mcp.server.filesystem.tool.read.param.path.description=\u8981\u8BFB\u53D6\u7684\u8DEF\u5F84\uFF0C\u53EF\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B\u9879
32+
33+
mcp.server.filesystem.tool.delete.title=\u6587\u4EF6/\u76EE\u5F55\u5220\u9664
34+
mcp.server.filesystem.tool.delete.description=\u5220\u9664\u6587\u4EF6\u7CFB\u7EDF\u4E2D\u7684\u6587\u4EF6\u6216\u76EE\u5F55
35+
mcp.server.filesystem.tool.delete.param.path.description=\u8981\u5220\u9664\u7684\u8DEF\u5F84\uFF0C\u53EF\u6587\u4EF6\u6216\u76EE\u5F55\uFF0C\u5FC5\u586B\u9879

‎mcp-server-filesystem/mcp-server-filesystem-official-sdk-implementation/src/main/java/com/github/mcp/server/filesystem/official/Prompts.java‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,23 @@ public final class Prompts {
2929
public static McpServerFeatures.SyncPromptSpecification find() {
3030
// Step 1: Create a prompt argument with name, description, and required flag.
3131
McpSchema.PromptArgument argumentStart =
32-
new McpSchema.PromptArgument("start", "The starting path to search, required.", true);
32+
new McpSchema.PromptArgument(
33+
"start", "starting path", "The starting path to search, required.", true);
3334
McpSchema.PromptArgument argumentName =
3435
new McpSchema.PromptArgument(
3536
"name",
37+
"target file/dir name",
3638
"The name of the target file or dir to search, supports fuzzy matching, required.",
3739
true);
3840

3941
// Step 2: Create a prompt with name, description, and arguments.
4042
List<McpSchema.PromptArgument> args = List.of(argumentStart, argumentName);
4143
McpSchema.Prompt prompt =
4244
new McpSchema.Prompt(
43-
"find", "Start from the specified path and recursively search subitems.", args);
45+
"find",
46+
"file/dir search",
47+
"Start from the specified path and recursively search subitems.",
48+
args);
4449

4550
// Step 3: Create a prompt specification with the prompt and the prompt handler.
4651
return new McpServerFeatures.SyncPromptSpecification(
@@ -78,12 +83,16 @@ public static McpServerFeatures.SyncPromptSpecification read() {
7883
// Step 1: Create a prompt argument with name, description, and required flag.
7984
McpSchema.PromptArgument argumentPath =
8085
new McpSchema.PromptArgument(
81-
"path", "The path to read, can be a file or dir, required.", true);
86+
"path",
87+
"target file/dir path",
88+
"The path to read, can be a file or dir, required.",
89+
true);
8290

8391
// Step 2: Create a prompt with name, description, and arguments.
8492
List<McpSchema.PromptArgument> args = List.of(argumentPath);
8593
McpSchema.Prompt prompt =
86-
new McpSchema.Prompt("read", "Read a file or list dir contents non-recursively.", args);
94+
new McpSchema.Prompt(
95+
"read", "file/dir read", "Read a file or list dir contents non-recursively.", args);
8796

8897
// Step 3: Create a prompt specification with the prompt and the prompt handler.
8998
return new McpServerFeatures.SyncPromptSpecification(
@@ -112,12 +121,16 @@ public static McpServerFeatures.SyncPromptSpecification delete() {
112121
// Step 1: Create a prompt argument with name, description, and required flag.
113122
McpSchema.PromptArgument argumentPath =
114123
new McpSchema.PromptArgument(
115-
"path", "The path to delete, can be a file or dir, required.", true);
124+
"path",
125+
"target file/dir path",
126+
"The path to delete, can be a file or dir, required.",
127+
true);
116128

117129
// Step 2: Create a prompt with name, description, and arguments.
118130
List<McpSchema.PromptArgument> args = List.of(argumentPath);
119131
McpSchema.Prompt prompt =
120-
new McpSchema.Prompt("delete", "Delete a file or dir from the filesystem.", args);
132+
new McpSchema.Prompt(
133+
"delete", "file/dir delete", "Delete a file or dir from the filesystem.", args);
121134

122135
// Step 3: Create a prompt specification with the prompt and the prompt handler.
123136
return new McpServerFeatures.SyncPromptSpecification(

‎mcp-server-filesystem/mcp-server-filesystem-official-sdk-implementation/src/main/java/com/github/mcp/server/filesystem/official/Resources.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,10 @@ public static McpServerFeatures.SyncResourceSpecification filesystem() {
3636
McpSchema.Resource.builder()
3737
.uri("file://system")
3838
.name("filesystem")
39+
.title("Filesystem")
3940
.description("File system operations interface")
4041
.mimeType("text/plain")
42+
.size(1024L)
4143
.annotations(new McpSchema.Annotations(List.of(McpSchema.Role.ASSISTANT), 1.0))
4244
.build();
4345

0 commit comments

Comments
 (0)