Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/sta-445-mcp-prompts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@stainless-code/verdict": minor
---

MCP hosts can now load the Procedure straight from the binary. `prompts/list` and `prompts/get` serve five task prompts (`address-reviews`, `fix-ci`, `incremental-review`, `review`, `validate`), and `resources/list` and `resources/read` serve every payload file at `verdict://skill/<path>`, byte-identical to `verdict skill show`. Prompts and resources are read-only and available in every server mode, including `--read-only` and `--operator`. `initialize` advertises both capabilities and points hosts at the `review` prompt or `verdict://skill/PROCEDURE.md`.
11 changes: 11 additions & 0 deletions docs/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -1678,6 +1678,17 @@ context. A malformed call is a JSON-RPC `-32602` error, not a refusal. Human
progress and warnings go to stderr (or MCP notifications), never stdout:
stdout is the protocol channel.

`prompts/list` offers five task prompts (`address-reviews`, `fix-ci`,
`incremental-review`, `review`, `validate`). `prompts/get` takes the
prompt name and no arguments, and returns that task's Procedure assembled by
the binary from its embedded payload. `resources/list` serves every payload
file at `verdict://skill/<path>` —
`resources/read` returns text byte-identical to `verdict skill show`.
Prompts and resources are read-only in every server mode, including
`--read-only` and `--operator`, and `skill` remains a distribution surface,
never a tool. `initialize` advertises both capabilities
and points hosts at the `review` prompt or `verdict://skill/PROCEDURE.md`.

#### Host config

`verdict mcp config --agent <claude|cursor|codex|gemini|qwen|windsurf|opencode|goose|copilot>`
Expand Down
9 changes: 9 additions & 0 deletions internal/archtest/manual_surfaces_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,15 @@ var manualSurfaces = []manualSurface{
"bad-recipe", "unknown-recipe", "--stage <n>", "data.stage",
},
},
{
section: "MCP prompts and resources",
heading: "### MCP server (stdio, experimental until 1.0)",
terms: []string{
"prompts/list", "prompts/get", "resources/list", "resources/read",
"verdict://skill/<path>", "byte-identical to `verdict skill show`",
"every server mode", "verdict://skill/PROCEDURE.md",
},
},
{
section: "serve local HTTP surface",
heading: "## Serve (local HTTP surface)",
Expand Down
26 changes: 24 additions & 2 deletions internal/mcp/contract_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,28 @@ func TestSurfaceSets(t *testing.T) {
}
}

// TestInitializeCapabilitiesSnapshot pins the three advertised surfaces.
func TestInitializeCapabilitiesSnapshot(t *testing.T) {
t.Parallel()
cfg := testConfig()
frames := serve(t, &cfg,
`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`)
var init initializeResult
if err := json.Unmarshal(frames["1"].Result, &init); err != nil {
t.Fatal(err)
}
raw, err := json.Marshal(init.Capabilities)
if err != nil {
t.Fatal(err)
}
const want = `{"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}}`
if string(raw) != want {
t.Fatalf("capabilities = %s, want %s", raw, want)
}
}

const procedureInstruction = "For the Procedure, use the review prompt or read verdict://skill/PROCEDURE.md."

// TestInitializeInstructions proves every client receives the short doctrine
// block, and that the operator boundary matches the surface.
//
Expand All @@ -137,12 +159,12 @@ func TestInitializeInstructions(t *testing.T) {
}{
{
name: "agent",
want: []string{"fetch", "review.json", "post", "triage[]", "hint", "not on this surface"},
want: []string{"fetch", "review.json", "post", "triage[]", "hint", "not on this surface", procedureInstruction},
},
{
name: "operator",
operator: true,
want: []string{"fetch", "post", "triage", "runs with --operator"},
want: []string{"fetch", "post", "triage", "runs with --operator", procedureInstruction},
absent: []string{"not on this surface"},
},
}
Expand Down
175 changes: 175 additions & 0 deletions internal/mcp/modes_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
package mcp

import (
"bytes"
"context"
"encoding/json"
"fmt"
"strconv"
"testing"

skillfs "github.com/stainless-code/verdict"
"github.com/stainless-code/verdict/internal/core/skill"
)

type procedureModeCase struct {
name string
tools int
readOnly bool
operator bool
}

// TestProcedureSurfacesIgnoreModes proves prompts and resources are
// byte-for-byte the same on every tool surface. The tool counts pin that the
// three configs really are different surfaces.
func TestProcedureSurfacesIgnoreModes(t *testing.T) {
t.Parallel()
cases := []procedureModeCase{
{name: "default", tools: 25},
{name: "read-only", tools: 14, readOnly: true},
{name: "operator", tools: 26, operator: true},
}
paths, wantPrompt, wantResource := procedureFixtures(t)

var baseline procedureWire
for i, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
cfg := testConfig()
cfg.ReadOnly = tc.readOnly
cfg.Operator = tc.operator
frames := procedureFrames(t, &cfg)
checkProcedureSurface(t, tc, frames, len(paths), len(skillfs.Tasks()), wantPrompt, wantResource)
wire := procedureWireFrom(frames)
if i == 0 {
baseline = wire
return
}
checkProcedureWire(t, tc.name, &wire, &baseline)
})
}
}

func procedureFixtures(t *testing.T) ([]string, []byte, []byte) {
t.Helper()
paths, err := skillfs.Paths()
if err != nil {
t.Fatal(err)
}
wantResource, ref := skill.ShowFile(context.Background(), &skill.Request{}, "PROCEDURE.md")
if ref != nil {
t.Fatal(ref)
}
wantPrompt, err := skillfs.ReviewProcedure()
if err != nil {
t.Fatal(err)
}
return paths, wantPrompt, wantResource
}

func procedureFrames(t *testing.T, cfg *Config) map[string]frame {
t.Helper()
lines := []string{
`{"jsonrpc":"2.0","id":1,"method":"tools/list"}`,
`{"jsonrpc":"2.0","id":2,"method":"prompts/list"}`,
`{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"review"}}`,
`{"jsonrpc":"2.0","id":4,"method":"resources/list"}`,
fmt.Sprintf(`{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":%q}}`,
resourceURIPrefix+"PROCEDURE.md"),
}
frames := serve(t, cfg, lines...)
for i := range lines {
id := strconv.Itoa(i + 1)
if frame := frames[id]; frame.Error != nil {
t.Fatalf("request %s error = %+v", id, frame.Error)
}
}
return frames
}

func checkProcedureSurface(t *testing.T, tc procedureModeCase, frames map[string]frame,
pathCount, taskCount int, wantPrompt, wantResource []byte,
) {
t.Helper()
checkToolCount(t, tc, frames)
checkPromptSurface(t, tc.name, frames, taskCount, wantPrompt)
checkResourceSurface(t, tc.name, frames, pathCount, wantResource)
}

func checkToolCount(t *testing.T, tc procedureModeCase, frames map[string]frame) {
t.Helper()
var tools toolsListResult
if err := json.Unmarshal(frames["1"].Result, &tools); err != nil {
t.Fatal(err)
}
if len(tools.Tools) != tc.tools {
t.Fatalf("%s tools = %d, want %d", tc.name, len(tools.Tools), tc.tools)
}
}

func checkPromptSurface(t *testing.T, name string, frames map[string]frame, taskCount int, want []byte) {
t.Helper()
var prompts promptsListResult
if err := json.Unmarshal(frames["2"].Result, &prompts); err != nil {
t.Fatal(err)
}
if len(prompts.Prompts) != taskCount {
t.Fatalf("%s prompts = %d, want %d", name, len(prompts.Prompts), taskCount)
}
var prompt promptResult
if err := json.Unmarshal(frames["3"].Result, &prompt); err != nil {
t.Fatal(err)
}
if len(prompt.Messages) != 1 || !bytes.Equal([]byte(prompt.Messages[0].Content.Text), want) {
t.Fatalf("%s review prompt does not carry the binary's Procedure", name)
}
}

func checkResourceSurface(t *testing.T, name string, frames map[string]frame, pathCount int, want []byte) {
t.Helper()
var resources resourceListResult
if err := json.Unmarshal(frames["4"].Result, &resources); err != nil {
t.Fatal(err)
}
if len(resources.Resources) != pathCount {
t.Fatalf("%s resources = %d, want %d", name, len(resources.Resources), pathCount)
}
var content resourceReadResult
if err := json.Unmarshal(frames["5"].Result, &content); err != nil {
t.Fatal(err)
}
if len(content.Contents) != 1 || !bytes.Equal([]byte(content.Contents[0].Text), want) {
t.Fatalf("%s PROCEDURE.md resource is not byte-identical to skill show", name)
}
}

type procedureWire struct {
promptsList json.RawMessage
promptGet json.RawMessage
resourcesList json.RawMessage
resourceRead json.RawMessage
}

func procedureWireFrom(frames map[string]frame) procedureWire {
return procedureWire{
promptsList: frames["2"].Result,
promptGet: frames["3"].Result,
resourcesList: frames["4"].Result,
resourceRead: frames["5"].Result,
}
}

func checkProcedureWire(t *testing.T, name string, got, want *procedureWire) {
t.Helper()
if !bytes.Equal(got.promptsList, want.promptsList) {
t.Errorf("%s prompts/list differs from the default surface", name)
}
if !bytes.Equal(got.promptGet, want.promptGet) {
t.Errorf("%s prompts/get differs from the default surface", name)
}
if !bytes.Equal(got.resourcesList, want.resourcesList) {
t.Errorf("%s resources/list differs from the default surface", name)
}
if !bytes.Equal(got.resourceRead, want.resourceRead) {
t.Errorf("%s resources/read differs from the default surface", name)
}
}
99 changes: 99 additions & 0 deletions internal/mcp/prompts.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
package mcp

import (
"encoding/json"
"errors"
"strconv"
"strings"

skillfs "github.com/stainless-code/verdict"
)

const (
methodPromptsList = "prompts/list"
methodPromptsGet = "prompts/get"
)

// promptDescriptions is the host-facing copy for the tasks in skillfs.Tasks.
var promptDescriptions = map[string]string{
"address-reviews": "Address review threads with verified fixes and one reply per thread.",
"fix-ci": "Diagnose a PR-introduced CI failure, fix it, and push the fix with a summary.",
"incremental-review": "Review only the commits added since a prior review, with a no-review note for trivial deltas.",
"review": "Review a fetched PR or local diff and write one review.json.",
"validate": "Validate candidate findings against the bundle without changing it.",
}

func (s *Server) handlePromptsList(req *rpcRequest) {
if len(req.ID) == 0 {
return
}
prompts := make([]promptDescriptor, 0, len(promptDescriptions))
for _, task := range skillfs.Tasks() {
prompts = append(prompts, promptDescriptor{
Name: task,
Description: promptDescriptions[task],
})
}
s.writeResult(req.ID, promptsListResult{Prompts: prompts})
}

func (s *Server) handlePromptsGet(req *rpcRequest) {
if len(req.ID) == 0 {
return
}
params, ok := decodeParams[promptNameParams](req.Params)
Comment thread
SutuSebastian marked this conversation as resolved.
Resolved
if !ok || params.Name == "" {
s.writeInvalidPrompt(req.ID, "")
return
}
body, err := skillfs.TaskProcedure(params.Name)
if err != nil {
if _, ok := errors.AsType[*skillfs.UnknownTaskError](err); ok {
s.writeInvalidPrompt(req.ID, params.Name)
return
}
s.writeError(req.ID, codeInternalError, "prompt unavailable: "+err.Error())
return
}
s.writeResult(req.ID, getPromptResult{
Description: promptDescriptions[params.Name],
Messages: []promptMessage{{
Role: "user",
Content: contentBlock{Type: contentTypeText, Text: string(body)},
}},
})
}

// MCP 2025-06-18 § server/prompts error handling: an invalid prompt name is
// -32602. The message names the served tasks because this server has no
// prompt arguments.
func (s *Server) writeInvalidPrompt(id json.RawMessage, name string) {
message := "missing prompt name; valid tasks: " + strings.Join(skillfs.Tasks(), ", ")
if name != "" {
message = "unknown prompt " + strconv.Quote(name) + "; valid tasks: " + strings.Join(skillfs.Tasks(), ", ")
}
s.writeError(id, codeInvalidParams, message)
}

type promptNameParams struct {
Name string `json:"name"`
}

type promptDescriptor struct {
Name string `json:"name"`
Description string `json:"description"`
}

type promptsListResult struct {
Prompts []promptDescriptor `json:"prompts"`
}

type promptMessage struct {
Role string `json:"role"`
Content contentBlock `json:"content"`
}

type getPromptResult struct {
Description string `json:"description"`
Messages []promptMessage `json:"messages"`
}
Loading
Loading