docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -49,27 +49,71 @@ Use cases:
|
||||
|
||||
## Usage
|
||||
|
||||
Declare a tool in a plugin (the `pact` types only; no SDK import):
|
||||
Declare tools and prompts in a plugin (the `pact` types only; no SDK import). The plugin's `MCP` method returns this declaration:
|
||||
|
||||
```go
|
||||
type createPostInput struct {
|
||||
Title string `json:"title" jsonschema:"the post title"`
|
||||
Body string `json:"body" jsonschema:"the Markdown body"`
|
||||
Published bool `json:"published,omitempty" jsonschema:"publish at once"`
|
||||
}
|
||||
|
||||
type showPostInput struct {
|
||||
ID int `json:"id" path:"id" jsonschema:"the post id"`
|
||||
}
|
||||
|
||||
func (p Plugin) MCP() pact.MCP {
|
||||
return pact.MCP{Tools: []pact.MCPTool{
|
||||
{Name: "create_post", Title: "Create post", Description: "Creates a draft post.",
|
||||
Guard: "backend", Method: "POST", Path: "/_blog/api/v1/posts", Input: createPostInput{},
|
||||
Permissions: []string{"acme.blog.access_posts"}},
|
||||
{Name: "show_post", Title: "Show post", Description: "Shows one post.",
|
||||
Method: "GET", Path: "/_blog/api/v1/posts/{id}", Input: showPostInput{}},
|
||||
}}
|
||||
```go src=modules/pier/example_mcp_test.go#blogTools
|
||||
// blogTools is the MCP declaration of the acme.blog plugin. A field of an
|
||||
// input struct is a body field unless its path or query tag says
|
||||
// otherwise; fields without omitempty are required in the schema.
|
||||
func blogTools() pact.MCP {
|
||||
type createPostInput struct {
|
||||
Title string `json:"title" jsonschema:"the post title"`
|
||||
Body string `json:"body" jsonschema:"the Markdown body"`
|
||||
Published bool `json:"published,omitempty" jsonschema:"publish at once instead of saving a draft"`
|
||||
}
|
||||
type showPostInput struct {
|
||||
ID int `json:"id" path:"id" jsonschema:"the post id"`
|
||||
}
|
||||
type listPostsInput struct {
|
||||
Query string `json:"q,omitempty" query:"q" jsonschema:"a phrase the title or body contains"`
|
||||
}
|
||||
return pact.MCP{
|
||||
Tools: []pact.MCPTool{
|
||||
{
|
||||
// Exposed as blog_create_post; the backend guard runs it as
|
||||
// the linked administrator, listed only with access_posts.
|
||||
Name: "create_post",
|
||||
Title: "Create post",
|
||||
Description: "Creates a post; a draft unless published is true.",
|
||||
Guard: "backend",
|
||||
Method: "POST",
|
||||
Path: "/_blog/api/v1/posts",
|
||||
Input: createPostInput{},
|
||||
Permissions: []string{"acme.blog.access_posts"},
|
||||
},
|
||||
{
|
||||
// Exposed as blog_show_post; the route's user.api_token
|
||||
// middleware names the guard, GET makes it read-only.
|
||||
Name: "show_post",
|
||||
Title: "Show post",
|
||||
Description: "Shows one post by id.",
|
||||
Method: "GET",
|
||||
Path: "/_blog/api/v1/posts/{id}",
|
||||
Input: showPostInput{},
|
||||
},
|
||||
{
|
||||
Name: "list_posts",
|
||||
Title: "List posts",
|
||||
Description: "Lists posts, optionally those matching a phrase.",
|
||||
Method: "GET",
|
||||
Path: "/_blog/api/v1/posts",
|
||||
Input: listPostsInput{},
|
||||
},
|
||||
},
|
||||
Prompts: []pact.MCPPrompt{
|
||||
{
|
||||
// Exposed as blog_summarize; prompts name their guard.
|
||||
Name: "summarize",
|
||||
Title: "Summarize a post",
|
||||
Description: "Asks for a three-sentence summary of a post.",
|
||||
Guard: "user",
|
||||
Arguments: []pact.MCPPromptArgument{{Name: "slug", Description: "the post slug", Required: true}},
|
||||
Render: func(_ context.Context, args map[string]string) ([]pact.MCPPromptMessage, error) {
|
||||
return []pact.MCPPromptMessage{{Role: "user", Text: "Summarize the post " + args["slug"] + " in three sentences."}}, nil
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user