1package mcp
2
3/* Prompts */
4
5// ListPromptsRequest is sent from the client to request a list of prompts and
6// prompt templates the server has.
7type ListPromptsRequest struct {
8 PaginatedRequest
9}
10
11// ListPromptsResult is the server's response to a prompts/list request from
12// the client.
13type ListPromptsResult struct {
14 PaginatedResult
15 Prompts []Prompt `json:"prompts"`
16}
17
18// GetPromptRequest is used by the client to get a prompt provided by the
19// server.
20type GetPromptRequest struct {
21 Request
22 Params GetPromptParams `json:"params"`
23}
24
25type GetPromptParams struct {
26 // The name of the prompt or prompt template.
27 Name string `json:"name"`
28 // Arguments to use for templating the prompt.
29 Arguments map[string]string `json:"arguments,omitempty"`
30}
31
32// GetPromptResult is the server's response to a prompts/get request from the
33// client.
34type GetPromptResult struct {
35 Result
36 // An optional description for the prompt.
37 Description string `json:"description,omitempty"`
38 Messages []PromptMessage `json:"messages"`
39}
40
41// Prompt represents a prompt or prompt template that the server offers.
42// If Arguments is non-nil and non-empty, this indicates the prompt is a template
43// that requires argument values to be provided when calling prompts/get.
44// If Arguments is nil or empty, this is a static prompt that takes no arguments.
45type Prompt struct {
46 // The name of the prompt or prompt template.
47 Name string `json:"name"`
48 // An optional description of what this prompt provides
49 Description string `json:"description,omitempty"`
50 // A list of arguments to use for templating the prompt.
51 // The presence of arguments indicates this is a template prompt.
52 Arguments []PromptArgument `json:"arguments,omitempty"`
53}
54
55// GetName returns the name of the prompt.
56func (p Prompt) GetName() string {
57 return p.Name
58}
59
60// PromptArgument describes an argument that a prompt template can accept.
61// When a prompt includes arguments, clients must provide values for all
62// required arguments when making a prompts/get request.
63type PromptArgument struct {
64 // The name of the argument.
65 Name string `json:"name"`
66 // A human-readable description of the argument.
67 Description string `json:"description,omitempty"`
68 // Whether this argument must be provided.
69 // If true, clients must include this argument when calling prompts/get.
70 Required bool `json:"required,omitempty"`
71}
72
73// Role represents the sender or recipient of messages and data in a
74// conversation.
75type Role string
76
77const (
78 RoleUser Role = "user"
79 RoleAssistant Role = "assistant"
80)
81
82// PromptMessage describes a message returned as part of a prompt.
83//
84// This is similar to `SamplingMessage`, but also supports the embedding of
85// resources from the MCP server.
86type PromptMessage struct {
87 Role Role `json:"role"`
88 Content Content `json:"content"` // Can be TextContent, ImageContent, AudioContent or EmbeddedResource
89}
90
91// PromptListChangedNotification is an optional notification from the server
92// to the client, informing it that the list of prompts it offers has changed. This
93// may be issued by servers without any previous subscription from the client.
94type PromptListChangedNotification struct {
95 Notification
96}
97
98// PromptOption is a function that configures a Prompt.
99// It provides a flexible way to set various properties of a Prompt using the functional options pattern.
100type PromptOption func(*Prompt)
101
102// ArgumentOption is a function that configures a PromptArgument.
103// It allows for flexible configuration of prompt arguments using the functional options pattern.
104type ArgumentOption func(*PromptArgument)
105
106//
107// Core Prompt Functions
108//
109
110// NewPrompt creates a new Prompt with the given name and options.
111// The prompt will be configured based on the provided options.
112// Options are applied in order, allowing for flexible prompt configuration.
113func NewPrompt(name string, opts ...PromptOption) Prompt {
114 prompt := Prompt{
115 Name: name,
116 }
117
118 for _, opt := range opts {
119 opt(&prompt)
120 }
121
122 return prompt
123}
124
125// WithPromptDescription adds a description to the Prompt.
126// The description should provide a clear, human-readable explanation of what the prompt does.
127func WithPromptDescription(description string) PromptOption {
128 return func(p *Prompt) {
129 p.Description = description
130 }
131}
132
133// WithArgument adds an argument to the prompt's argument list.
134// The argument will be configured based on the provided options.
135func WithArgument(name string, opts ...ArgumentOption) PromptOption {
136 return func(p *Prompt) {
137 arg := PromptArgument{
138 Name: name,
139 }
140
141 for _, opt := range opts {
142 opt(&arg)
143 }
144
145 if p.Arguments == nil {
146 p.Arguments = make([]PromptArgument, 0)
147 }
148 p.Arguments = append(p.Arguments, arg)
149 }
150}
151
152//
153// Argument Options
154//
155
156// ArgumentDescription adds a description to a prompt argument.
157// The description should explain the purpose and expected values of the argument.
158func ArgumentDescription(desc string) ArgumentOption {
159 return func(arg *PromptArgument) {
160 arg.Description = desc
161 }
162}
163
164// RequiredArgument marks an argument as required in the prompt.
165// Required arguments must be provided when getting the prompt.
166func RequiredArgument() ArgumentOption {
167 return func(arg *PromptArgument) {
168 arg.Required = true
169 }
170}