docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:04:47 +01:00
parent 6409837b0c
commit cd55a3980d
9 changed files with 449 additions and 69 deletions

View File

@@ -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
},
},
},
}
}
```