Add Prompts support to the MCP Server #825

yasmewad · 2025-07-25T01:24:21Z

NOTE: The main goal with the PR is to get feedback and discuss around ways to ingest the model / prompts appropriately.

This adds prompt support to the MCP server, letting LLMs get helpful context directly from Smithy models.

What's New

Core Features:
• Define prompts in Smithy using @prompts trait as defined in #829
• MCP server automatically exposes them via prompts/list and prompts/get
• Template support with {{placeholder}} syntax for dynamic content.

Key Components:
• PromptLoader - discovers prompts from Smithy models
• PromptProcessor - handles template substitution and validation

Testing

Added unit tests for various cases of PromptLoader, PromptProcessor and the MCP Server itself.
Added example in ProxyMcpServerExample and ran it with Q CLI.
Will add more testing examples in next revision after discussion has settled.

This is what `/prompts` in Q CLI which correctly demonstrates the data from the prompts trait. Will add more calling examples later.

User experience for `prompts/get` or `@prompts` invocation in Q CLI.

mcp/mcp-schemas/model/main.smithy

yasmewad · 2025-07-25T01:26:15Z

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/McpServer.java

+
+                    var prompt = prompts.get(promptName);
+
+                    if (prompt == null) {


Should we respond with PromptMessage too ? Like we do in the file PromptProcessor.java?

I don't think you need model list here.

You should be able to pull this off the schema as long as these traits are retained at runtime. This controlled by runtimeTraits property, example

Thanks for sharing that example it makes sense that we can use the schema. I will try that approach.

Should we make this a default runtime trait?

That's a valid point. Making it a default will save confusion at least for customers.

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptLoader.java

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/McpServerBuilder.java

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptProcessor.java

yasmewad · 2025-07-25T17:21:23Z

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptLoader.java

+     * @return List of PromptArgument objects representing the structure members
+     */
+    public static List<PromptArgument> convertArgumentShapeToPromptArgument(Model model, ShapeId argumentShapeId) {
+        StructureShape argument = model.expectShape(argumentShapeId, StructureShape.class);


Is there a way to get this behavior using the Service class? I looked at the TypeRegistry and Schema but could not find a pattern on how to use it. Maybe that's me being unfamiliar with access patterns of Smithy java.

You will not have access to the StructureShape, but in this method all you are doing is accessing members and traits. Both can be done from the Schema class, using Schema#getMembers and Schema#getTrait.

Yep I can try that out. Thanks.

I tried to extract arguments using only the Schema and TypeRegistry from the Service interface, I hit some blockers:

Schema is too limited
It only knows about the main service shape and its direct pieces. It doesn't include operations or resources (where our @prompts traits actually live) a valid use-case. So we can't even find the prompts, let alone process them

TypeRegistry doesn't help. It only stores error types, nothing else. I tried to look up argument shapes, but they're not there

The main blocker is ShapeId references. Prompts have an arguments field that points to a structure (like SearchArguments). To process this, we need to find that structure in the model and read its fields Schema and TypeRegistry just don't have this information

What We're Doing Instead

We're parsing prompts in ProxyService because it has access to the full Smithy model. The prompts will behave as an operation with a synthetic trait on it. We will filter those in the McpServer from tools, and also serve them as prompts when needed. On a prompts/get call, we will just apply the arguments passed in by the client to the operation and return the template string. This is suggested by @rhernandez35 so that it is easier to pass the information by only passing the Service, and the ProxyService already has model information so we will be able to parse the information as well.

It only knows about the main service shape and its direct pieces. It doesn't include operations or resources (where our @prompts traits actually live) a valid use-case. So we can't even find the prompts, let alone process them

This isn't accurate. We generate Schema for both operations as well as resources.

The main blocker is ShapeId references. Prompts have an arguments field that points to a structure (like SearchArguments). To process this, we need to find that structure in the model and read its fields Schema and TypeRegistry just don't have this information

Should be fixed by #827

This isn't accurate. We generate Schema for both operations as well as resources.

Hmm, interesting from my debugging,maybe again this is my understanding and missing context. I was only able to the see the information related to the service. In my case, what would the PromptLoader method look like in terms of arguments it takes instead of the model we have currently?

Should be fixed by #827

Nice!

We're parsing prompts in ProxyService because it has access to the full Smithy model. The prompts will behave as an operation with a synthetic trait on it. We will filter those in the McpServer from tools, and also serve them as prompts when needed. On a prompts/get call, we will just apply the arguments passed in by the client to the operation and return the template string. This is suggested by @rhernandez35 so that it is easier to pass the information by only passing the Service, and the ProxyService already has model information so we will be able to parse the information as well.

Do you think this will be a good approach? I discussed with Richard and it seemed only fair for now.

In future, we should plan to move artifact generation for the tools and prompts such that the Smithy build system provides that data. The MCP Server can just become consumer using maybe a new McpService class that can take in Mcp specific things.

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptLoader.java

rhernandez35 · 2025-07-28T17:18:15Z

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptProcessor.java

+    }
+
+    /**
+     * Applies template arguments to a template string with maximum efficiency.


"with maximum efficiency" doesn't need to be documented

Ack. Removed in local. Will send a new commit for various nit fixes.

rhernandez35 · 2025-07-28T18:21:30Z

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/McpServer.java

                                        .build())
                                .serverInfo(ServerInfo.builder()
                                        .name(name)
                                        .version("1.0.0")
                                        .build())
                                .build());
+                case "prompts/list" -> writeResponse(req.getId(),
+                        ListPromptsResult.builder().prompts(prompts.values().stream().toList()).build());


We need to prevent the prompt templates from being serialized in this response. We only want the name, title, description, and arguments.

Yes. I can update the response shape.

adwsingh · 2025-07-28T21:38:47Z

...egen/src/main/java/software/amazon/smithy/java/codegen/server/ServiceJavaSymbolProvider.java

+        return getServerJavaClassSymbol(serviceShape);
    }

-    private Symbol getServerJavaClassSymbol() {
+    private Symbol getServerJavaClassSymbol(ServiceShape serviceShape) {


This isn't required. I think you messed something in the rebase.

adwsingh · 2025-07-28T21:39:09Z

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/McpServerBuilder.java

@@ -22,6 +23,7 @@ public final class McpServerBuilder {
    OutputStream os;
    List<Service> serviceList = new ArrayList<>();
    List<McpServerProxy> proxyList = new ArrayList<>();
+    List<Model> modelList = new ArrayList<>();


Ahh yes. 🤦🏽‍♂️

...egen/src/main/java/software/amazon/smithy/java/codegen/server/ServiceJavaSymbolProvider.java

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/McpServerBuilder.java

mcp/mcp-server/src/test/java/software/amazon/smithy/java/mcp/server/PromptProcessorTest.java

yasmewad requested review from adwsingh and rhernandez35 July 25, 2025 01:24

yasmewad commented Jul 25, 2025

View reviewed changes

adwsingh reviewed Jul 25, 2025

View reviewed changes

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptProcessor.java Show resolved Hide resolved

yasmewad commented Jul 25, 2025

View reviewed changes

yasmewad commented Jul 28, 2025

View reviewed changes

mcp/mcp-server/src/main/java/software/amazon/smithy/java/mcp/server/PromptLoader.java Show resolved Hide resolved

adwsingh force-pushed the mcp-prompts-support branch 2 times, most recently from 0e49455 to 3e97b6b Compare July 28, 2025 17:08

rhernandez35 reviewed Jul 28, 2025

View reviewed changes

adwsingh force-pushed the mcp-prompts-support branch from 3e97b6b to d82e620 Compare July 28, 2025 19:08

yasmewad force-pushed the mcp-prompts-support branch 2 times, most recently from 49d5fc8 to aae765c Compare July 28, 2025 21:36

adwsingh reviewed Jul 28, 2025

View reviewed changes

rhernandez35 reviewed Jul 28, 2025

View reviewed changes

mcp/mcp-server/src/test/java/software/amazon/smithy/java/mcp/server/PromptProcessorTest.java Show resolved Hide resolved

rhernandez35 approved these changes Jul 28, 2025

View reviewed changes

Add Prompts support for MCP Server

f42538d

yasmewad force-pushed the mcp-prompts-support branch from 212067c to f42538d Compare July 28, 2025 21:57

adwsingh approved these changes Jul 28, 2025

View reviewed changes

yasmewad merged commit 91eed0b into smithy-lang:main Jul 28, 2025
2 checks passed

Add Prompts support to the MCP Server #825

Add Prompts support to the MCP Server #825

Uh oh!

Conversation

yasmewad commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's New

Testing

This is what /prompts in Q CLI which correctly demonstrates the data from the prompts trait. Will add more calling examples later.

User experience for prompts/get or @prompts invocation in Q CLI.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yasmewad Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yasmewad Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

What We're Doing Instead

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yasmewad Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yasmewad commented Jul 25, 2025 •

edited

Loading

This is what `/prompts` in Q CLI which correctly demonstrates the data from the prompts trait. Will add more calling examples later.

User experience for `prompts/get` or `@prompts` invocation in Q CLI.

yasmewad Jul 25, 2025 •

edited

Loading

yasmewad Jul 26, 2025 •

edited

Loading

yasmewad Jul 28, 2025 •

edited

Loading