Add sortable tool contents with claimed hint summaries

Author: kaihendry

README.md

@@ -33,7 +33,9 @@ reports use the same hierarchy. Long URLs and description text wrap within
 the page. **Sort by** orders tools by name or any hint, and **Reverse** flips
 the order. Hints sort false first using the displayed defaults when missing;
 read-only “n/a” values stay last. Sorting reuses the snapshot, and publishing
-preserves the displayed order.
+preserves the displayed order. The **Tools** contents list links to each tool,
+summarizes its applicable claimed hints, and follows the same sort order.
+Published reports include the contents too.
 Inspector diagnostics, including the authorization URL, appear immediately in
 the terminal if you need to open the URL yourself.
 

form.html

@@ -11,6 +11,9 @@
   button { font: inherit; padding: .4rem 1.2rem; margin: .5rem .5rem 0 0; }
   button:disabled { opacity: .6; cursor: wait; }
   h2 { font-size: 1.2rem; }
+  h2, h3 { scroll-margin-top: 1rem; }
+  .contents { padding-left: 1.5rem; }
+  .contents li { margin: .5rem 0; }
   .tool { border-top: 1px solid #ddd; padding: 1rem 0; }
   .tool h3 { font: 600 1.1rem/1.5 ui-monospace, monospace; margin: 0 0 .5rem; }
   .tool h4 { font-size: 1rem; margin: 1rem 0 .3rem; }
@@ -64,6 +67,7 @@ <h1>MCP tool annotation hints</h1>
 <form method="post" action="/" hx-post="/" hx-target="#result" hx-select="#result" hx-swap="outerHTML" hx-disabled-elt="button, #result select, #result input[type=checkbox]">
   <input type="hidden" name="payload" value="{{.Snapshot}}">
 {{if .Rows}}
+<h2 id="tools">Tools</h2>
 <div class="sort-controls">
   <label>Sort by <select name="sort" onchange="this.form.requestSubmit()">
     <option value="">Server order</option>
@@ -73,10 +77,19 @@ <h1>MCP tool annotation hints</h1>
   <label><input type="checkbox" name="reverse" value="1" {{if .Reverse}}checked{{end}} onchange="this.form.requestSubmit()"> Reverse</label>
 </div>
 <p class="hint">Hints sort false first (true first when reversed). Missing hints use their displayed defaults; n/a stays last.</p>
-<h2>Tools</h2>
+<nav aria-label="Tool contents">
+  <ul class="contents">
+  {{range .Rows}}
+    <li><a href="#{{.ID}}"><code>{{.Name}}</code></a>
+      {{range .Claims}}<span class="b {{if .Risky}}risk{{else}}safe{{end}}">{{.Name}}: claimed {{.Value}}</span>
+      {{else}}<span class="hint">No hints declared.</span>{{end}}
+    </li>
+  {{end}}
+  </ul>
+</nav>
   {{range .Rows}}
   <section class="tool">
-    <h3>{{.Name}}</h3>
+    <h3 id="{{.ID}}">{{.Name}}</h3>
     {{if .Description}}<h4>Description</h4><p class="description">{{.Description}}</p>{{end}}
     <h4>Annotations</h4>
     {{if .None}}<p class="hint">No annotations declared.</p>{{end}}
@@ -91,6 +104,7 @@ <h4>Annotations</h4>
     </li>
     {{end}}
     </ul>
+    <a class="hint" href="#tools">Back to tools</a>
   </section>
   {{end}}
 

main.go

@@ -48,12 +48,23 @@ type Hint struct {
 }
 
 type Row struct {
+	ID          string
 	Name        string
 	Description string
 	None        bool    // no annotations declared at all
 	Hints       [4]Hint // readOnly, destructive, idempotent, openWorld
 }
 
+func (r Row) Claims() []Hint {
+	var claims []Hint
+	for _, h := range r.Hints {
+		if h.Declared && !h.Moot {
+			claims = append(claims, h)
+		}
+	}
+	return claims
+}
+
 // The spec's defaults are deliberately the worst case.
 var defaults = [4]Hint{
 	{Name: "readOnlyHint", Value: false},
@@ -62,8 +73,8 @@ var defaults = [4]Hint{
 	{Name: "openWorldHint", Value: true},
 }
 
-func buildRow(t Tool) Row {
-	r := Row{Name: t.Name, Description: t.Description, None: t.Annotations == nil}
+func buildRow(t Tool, index int) Row {
+	r := Row{ID: fmt.Sprintf("tool-%d", index), Name: t.Name, Description: t.Description, None: t.Annotations == nil}
 	var ptrs [4]*bool
 	if t.Annotations != nil {
 		a := t.Annotations
@@ -174,7 +185,21 @@ func markdown(server, fetched string, rows []Row) string {
 		b.WriteString("No tools returned.\n\n")
 	}
 	for _, r := range rows {
-		fmt.Fprintf(&b, "### `%s`\n\n", r.Name)
+		fmt.Fprintf(&b, "- <a href=\"#%s\"><code>%s</code></a> — ", r.ID, template.HTMLEscapeString(r.Name))
+		var claims []string
+		for _, h := range r.Claims() {
+			claims = append(claims, fmt.Sprintf("`%s`: %s", h.Name, cell(h)))
+		}
+		if len(claims) == 0 {
+			b.WriteString("No hints declared.")
+		} else {
+			b.WriteString(strings.Join(claims, "; "))
+		}
+		b.WriteString("\n")
+	}
+	b.WriteString("\n")
+	for _, r := range rows {
+		fmt.Fprintf(&b, "<a name=\"%s\"></a>\n\n### `%s`\n\n", r.ID, r.Name)
 		if r.Description != "" {
 			fmt.Fprintf(&b, "#### Description\n\n<p>%s</p>\n\n",
 				strings.ReplaceAll(template.HTMLEscapeString(r.Description), "\n", "<br>\n"))
@@ -300,8 +325,8 @@ func newHandler() http.Handler {
 					data.Payload = data.Snapshot
 				}
 				data.Server, data.Fetched = p.Server, p.Fetched
-				for _, t := range p.Tools {
-					data.Rows = append(data.Rows, buildRow(t))
+				for i, t := range p.Tools {
+					data.Rows = append(data.Rows, buildRow(t, i))
 				}
 				sortRows(data.Rows, data.Sort, data.Reverse)
 				data.Done = true

main_test.go

@@ -99,7 +99,7 @@ printf '%s\n' '{"tools":[
 				t.Errorf("invalid fetched timestamp: %v", err)
 			}
 
-			sections := regexp.MustCompile(`(?s)<section class="tool">\s*<h3>(.*?)</h3>(.*?)</section>`).FindAllStringSubmatch(body, -1)
+			sections := regexp.MustCompile(`(?s)<section class="tool">\s*<h3 id="[^"]+">(.*?)</h3>(.*?)</section>`).FindAllStringSubmatch(body, -1)
 			cases := []struct {
 				name  string
 				hints []string
@@ -210,6 +210,12 @@ printf 'https://gist.github.com/example/snapshot\n'`,
 	if p.Tools[0].Description != description || !strings.Contains(w.Body.String(), `<p class="description">`+html.EscapeString(description)+"</p>") || strings.Contains(w.Body.String(), "<script>alert(1)</script>") {
 		t.Fatal("description was lost or rendered as HTML")
 	}
+	contents := regexp.MustCompile(`(?s)<nav aria-label="Tool contents">(.*?)</nav>`).FindStringSubmatch(w.Body.String())
+	if len(contents) != 2 || !strings.Contains(contents[1], "readOnlyHint: claimed true") ||
+		!strings.Contains(contents[1], "No hints declared.") || strings.Contains(contents[1], "destructiveHint") ||
+		strings.Contains(contents[1], "idempotentHint") || strings.Contains(contents[1], "openWorldHint") {
+		t.Fatalf("contents must summarize applicable claims only: %v", contents)
+	}
 	for _, fail := range []string{"true", "false"} {
 		t.Run("gist_failure="+fail, func(t *testing.T) {
 			t.Setenv("MCPHINTS_SMOKE_FAIL", fail)
@@ -226,7 +232,8 @@ printf 'https://gist.github.com/example/snapshot\n'`,
 			}
 			for _, want := range []string{
 				"- **Server:** `" + server + "`", "- **Fetched:** " + fetched,
-				"## Tools\n\n### `another`", "### `read_only`", "#### Description\n\n<p>" + strings.ReplaceAll(html.EscapeString(description), "\n", "<br>\n") + "</p>",
+				"## Tools\n\n- <a href=\"#tool-1\"><code>another</code></a> — No hints declared.\n- <a href=\"#tool-0\"><code>read_only</code></a> — `readOnlyHint`: 🟢 claimed true\n\n",
+				"<a name=\"tool-1\"></a>\n\n### `another`", "<a name=\"tool-0\"></a>\n\n### `read_only`", "#### Description\n\n<p>" + strings.ReplaceAll(html.EscapeString(description), "\n", "<br>\n") + "</p>",
 				"#### Annotations\n\n- `readOnlyHint`: 🟢 claimed true\n- `destructiveHint`: n/a — read-only\n- `idempotentHint`: n/a — read-only\n- `openWorldHint`: ⚠️ assumed true",
 			} {
 				if !strings.Contains(string(md), want) {
@@ -253,7 +260,7 @@ func TestSortSnapshot(t *testing.T) {
 	// No executables: sorting must never fetch or publish.
 	t.Setenv("PATH", t.TempDir())
 	const source = `{"server":"https://example.test/mcp","fetched":"2020-01-02T03:04:05Z","tools":[
-		{"name":"z_missing"},
+		{"name":"z_missing","annotations":{}},
 		{"name":"b_safe","annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},
 		{"name":"c_risky","annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true}},
 		{"name":"a_readonly","annotations":{"readOnlyHint":true}}
@@ -282,10 +289,20 @@ func TestSortSnapshot(t *testing.T) {
 			form.Set("reverse", "1")
 		}
 		w := postForm(t, handler, form)
-		var names []string
-		for _, heading := range regexp.MustCompile(`<h3>([^<]+)</h3>`).FindAllStringSubmatch(w.Body.String(), -1) {
+		var names, linkedNames []string
+		for _, heading := range regexp.MustCompile(`<h3 id="[^"]+">([^<]+)</h3>`).FindAllStringSubmatch(w.Body.String(), -1) {
 			names = append(names, heading[1])
 		}
+		ids := map[string]string{"z_missing": "tool-0", "b_safe": "tool-1", "c_risky": "tool-2", "a_readonly": "tool-3"}
+		for _, link := range regexp.MustCompile(`<a href="#(tool-[^"]+)"><code>([^<]+)</code></a>`).FindAllStringSubmatch(w.Body.String(), -1) {
+			linkedNames = append(linkedNames, link[2])
+			if link[1] != ids[link[2]] || !strings.Contains(w.Body.String(), `<h3 id="`+link[1]+`">`+link[2]+`</h3>`) {
+				t.Errorf("contents link changed or has no matching heading: %s", link[0])
+			}
+		}
+		if !slices.Equal(linkedNames, names) {
+			t.Errorf("contents order = %v, want %v", linkedNames, names)
+		}
 		if strings.Join(names, " ") != tc.want {
 			t.Errorf("sort %q, reverse %v: got %v, want %s", tc.key, tc.reverse, names, tc.want)
 		}