form.html

<!doctype html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>MCP tool annotation hints</title>
<script src="https://unpkg.com/htmx.org@4.0.0/dist/htmx.min.js"></script>
<style>
  body { font: 16px/1.5 system-ui, sans-serif; max-width: 60rem; margin: 2rem auto; padding: 0 1rem; color: #1a1a1a; }
  h1 { font-size: 1.4rem; }
  input[name=server] { width: 100%; font: 13px/1.4 ui-monospace, monospace; padding: .5rem; box-sizing: border-box; }
  textarea { width: 100%; height: 10rem; font: 13px/1.4 ui-monospace, monospace; padding: .5rem; box-sizing: border-box; }
  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-wrap { overflow-x: auto; }
  .contents { border-collapse: collapse; width: 100%; }
  .contents th, .contents td { padding: .5rem .6rem; text-align: left; vertical-align: top; }
  .contents thead th { font-size: .85rem; color: #666; font-weight: 600; border-bottom: 1px solid #ddd; white-space: nowrap; }
  .contents tbody th { font-weight: 400; }
  .contents tbody tr { border-top: 1px solid #eee; }
  .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; }
  .tool-title { margin: .3rem 0; color: #444; }
  .description { margin: .3rem 0; overflow-x: auto; }
  .description > :first-child { margin-top: 0; }
  .description h5, .description h6 { font-size: 1rem; margin: .8rem 0 .3rem; }
  .description table { border-collapse: collapse; }
  .description th, .description td { border: 1px solid #ddd; padding: .3rem .5rem; }
  pre { white-space: pre-wrap; overflow-wrap: anywhere; padding: .7rem; background: #f5f5f5; border-radius: .3rem; }
  details { margin: .7rem 0; }
  summary { cursor: pointer; }
  .parameters > li { margin: .7rem 0; }
  .annotations { padding-left: 1.5rem; }
  .annotations li { margin: .3rem 0; }
  .sort-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; margin-top: 1rem; }
  select { font: inherit; padding: .25rem; }
  .b { display: inline-block; padding: .1rem .5rem; border-radius: .8rem; font-size: .8rem; white-space: nowrap; }
  .safe  { background: #dcf5dc; color: #145214; }        /* declared, safe value */
  .risk  { background: #fadcdc; color: #7a1212; }        /* declared, risky value */
  .assumed { background: #fdf3d7; color: #7a5b00; border: 1px dashed #c9a227; } /* not declared: worst case assumed */
  .moot  { background: #eee; color: #666; }
  .err { color: #a00; }
  .note { background: #f0f4fa; border-left: 3px solid #4a7ab5; padding: .6rem .9rem; font-size: .9rem; }
  .legend { font-size: .85rem; color: #444; }
  .hint { font-size: .85rem; color: #666; margin: .3rem 0; }
  #result { overflow-wrap: anywhere; }
  #trifecta { margin: 1rem 0; }
  #trifecta svg { display: block; width: 100%; height: auto; }
  .spinner { display: none; color: #4a7ab5; }
  .htmx-request .spinner { display: inline; }
</style>

<h1>MCP tool annotation hints</h1>
<p class="hint"><a href="https://github.com/kaihendry/mcphints">Source on GitHub</a></p>
<p>Per the <a href="https://modelcontextprotocol.io/specification/2026-07-28/schema#toolannotations">MCP spec</a>,
every hint a server does <em>not</em> declare must be assumed at its conservative default &mdash;
i.e. the worst case: not read-only, destructive, not idempotent, open-world.</p>

<button type="button" aria-expanded="false" aria-controls="trifecta"
        onclick="const panel = document.getElementById('trifecta'); panel.hidden = !panel.hidden;
                 this.setAttribute('aria-expanded', String(!panel.hidden));
                 this.textContent = panel.hidden ? 'Show lethal trifecta' : 'Hide lethal trifecta';">Show lethal trifecta</button>
<figure id="trifecta" hidden>
  {{template "trifecta.svg"}}
  <figcaption class="hint">Review the capabilities available across the agent's tools: access to private data,
  exposure to untrusted content, and a way to communicate externally. MCP hints alone cannot establish
  whether this combination is present.
  <a href="https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/">The lethal trifecta, by Simon Willison</a>.</figcaption>
</figure>

<form method="post" action="/" hx-post="/" hx-target="#result" hx-select="#result" hx-swap="outerHTML" hx-disable="button, #result select, #result input[type=checkbox]">
  <p class="hint">Fetch straight from a server &mdash; an <code>http(s)://</code> URL (OAuth handled by the
  inspector; first use may open a browser to authorise) or a stdio command:</p>
  <input name="server" value="{{.ServerInput}}" list="known-servers"
         placeholder="https://api.fastmail.com/mcp   or   uvx awslabs.aws-documentation-mcp-server@latest">
  <datalist id="known-servers">
    <option value="https://api.fastmail.com/mcp">Fastmail</option>
    <option value="https://gmailmcp.googleapis.com/mcp/v1">Gmail</option>
    <option value="uvx awslabs.aws-documentation-mcp-server@latest">AWS documentation (stdio)</option>
  </datalist>
  <p class="hint"><label><input type="checkbox" name="skip_issuer_check" value="1" {{if .SkipIssuerCheck}}checked{{end}}>
  Skip OAuth issuer check</label> &mdash; only for servers that fail with &ldquo;Issuer mismatch&rdquo;
  (<a href="https://www.rfc-editor.org/rfc/rfc8414#section-3.3">RFC 8414 §3.3</a>). Disables mix-up attack protection.</p>
  <p class="hint">&hellip;or paste <code>tools/list</code> JSON here (a <code>tools</code> object, a JSON-RPC response, or a bare array):</p>
  <textarea name="payload" placeholder='{"tools":[{"name":"…","annotations":{"readOnlyHint":true}}]}'>{{.Payload}}</textarea><br>
  <button>Analyse</button>
  <span class="spinner">working&hellip; (a fetch can take ~30s; OAuth may open a browser tab)</span>
</form>

<div id="result" data-server="{{if .Fetched}}{{.Server}}{{end}}">
{{if .Err}}<p class="err">{{.Err}}</p>{{end}}

{{if .Done}}
{{if .Server}}<p><strong>Server:</strong> <code>{{.Server}}</code>{{if .Fetched}} &middot; fetched {{.Fetched}}{{end}}</p>{{end}}
{{if .Report.NextCursor}}<p class="note"><strong>Partial tool list:</strong> the server supplied a next cursor; more tools may be available.</p>{{end}}
{{if .Report.TTLMS}}<p class="hint">Cache TTL: {{.Report.TTLMS}} ms (server-provided freshness hint).</p>{{end}}
{{if .Report.CacheScope}}<p class="hint">Cache scope: <code>{{.Report.CacheScope}}</code>{{if eq .Report.CacheScope "private"}} — reuse only within the same authorization context{{end}}.</p>{{end}}
{{if .Report.ReportMetadata}}<details><summary>Report metadata</summary><pre>{{json .Report.ReportMetadata}}</pre></details>{{end}}
<form method="post" action="/" hx-post="/" hx-target="#result" hx-select="#result" hx-swap="outerHTML" hx-disable="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>
    <option value="name" {{if eq .Sort "name"}}selected{{end}}>Tool name</option>
    {{range .HintTypes}}<option value="{{.Name}}" {{if eq $.Sort .Name}}selected{{end}}>{{.Name}}</option>{{end}}
  </select></label>
  <label><input type="checkbox" name="reverse" value="1" {{if .Reverse}}checked{{end}} onchange="this.form.requestSubmit()"> Reverse</label>
</div>
<p class="hint">Hints sort higher-risk values first: destructive/open-world true, read-only/idempotent false.
Reverse puts lower-risk values first. Missing hints use their displayed defaults; n/a stays last.</p>
<nav aria-label="Tool contents">
  <div class="contents-wrap">
  <table class="contents">
    <thead>
      <tr><th scope="col">Tool</th>{{range .HintTypes}}<th scope="col"><code>{{.Name}}</code></th>{{end}}</tr>
    </thead>
    <tbody>
    {{range .Rows}}
      <tr>
        <th scope="row"><a href="#{{.ID}}"><code>{{.Name}}</code></a></th>
        {{range .Hints}}
        <td>
          {{if .Moot}}<span class="b moot">n/a</span>
          {{else if not .Declared}}<span class="hint">not declared</span>
          {{else}}<span class="b {{if .Risky}}risk{{else}}safe{{end}}">claimed {{.Value}}</span>{{end}}
        </td>
        {{end}}
      </tr>
    {{end}}
    </tbody>
  </table>
  </div>
</nav>
  {{range .Rows}}
  <section class="tool">
    <h3 id="{{.ID}}">{{.Name}}</h3>
    {{if ne .DisplayTitle .Name}}<p class="tool-title">{{.DisplayTitle}}</p>{{end}}
    {{if .Description}}<h4>Description</h4><div class="description">{{description .Description}}</div>{{end}}
    {{if .InputSchema}}
    <h4>Parameters</h4>
    {{if .Parameters}}<ul class="parameters">
      {{range .Parameters}}<li><code>{{.Name}}</code> <span class="hint">({{.Type}}; {{.Presence}})</span>
        {{if .Description}}<div class="description">{{description .Description}}</div>{{end}}
        {{if .Enum}}<div>Allowed values: <code>{{json .Enum}}</code></div>{{end}}
        {{if .Default}}<div>Default: <code>{{json .Default}}</code></div>{{end}}
      </li>{{end}}
    </ul>{{end}}
    <p class="hint">See the full input schema for all parameter constraints, alternatives, and references.</p>
    <details><summary>Input schema</summary><pre>{{json .InputSchema}}</pre></details>
    {{end}}
    {{if .OutputSchema}}<details><summary>Output schema</summary><pre>{{json .OutputSchema}}</pre></details>{{end}}
    {{if .Meta}}<details><summary>Tool metadata</summary><pre>{{json .Meta}}</pre></details>{{end}}
    <details><summary>Raw tool JSON</summary><pre>{{json .Tool}}</pre></details>
    <h4>Annotations</h4>
    {{if .None}}<p class="hint">No annotations declared.</p>{{end}}
    <ul class="annotations">
    {{range .Hints}}
    <li><code>{{.Name}}</code>:
      {{if .Moot}}<span class="b moot">n/a &mdash; read-only</span>
      {{else if not .Declared}}<span class="b assumed">assumed {{.Value}}</span>
      {{else if .Risky}}<span class="b risk">claimed {{.Value}}</span>
      {{else}}<span class="b safe">claimed {{.Value}}</span>
      {{end}}
    </li>
    {{end}}
    </ul>
    <a class="hint" href="#tools">Back to tools</a>
  </section>
  {{end}}

<p class="legend">
  <span class="b safe">claimed</span> server claims the safer value (unverified) &nbsp;
  <span class="b risk">claimed</span> server claims the riskier value (unverified) &nbsp;
  <span class="b assumed">assumed</span> server said nothing &mdash; spec default (worst case) applies
</p>

<p class="note"><strong>Caveat for risk assessments:</strong> annotations are self-declared
<em>hints</em> from the server and are not verified or enforced by the protocol. The spec says
clients must not make security-critical decisions based on them. Treat a declared
<code>readOnlyHint:&nbsp;true</code> as a vendor claim to record, not a control.</p>
{{else}}
<p>No tools returned.</p>
{{end}}

{{if .GistURL}}<p class="note">Published as an unlisted gist (visible to anyone with the URL): <a href="{{.GistURL}}">{{.GistURL}}</a></p>
{{else}}
  {{if .GistErr}}<p class="err">{{.GistErr}}</p>{{end}}
  <button name="action" value="gist">Publish this report</button>
  <p class="hint">Creates an unlisted GitHub gist, visible to anyone with the link.</p>
{{end}}
  <span class="spinner">working&hellip;</span>
</form>
{{end}}
</div>

<script>
  // Remember servers that fetched successfully, in this browser only.
  htmx.onLoad(() => {
    let servers = [];
    try { servers = JSON.parse(localStorage.getItem('servers')) || []; } catch {}
    const fetched = document.getElementById('result').dataset.server;
    if (fetched) {
      servers = [fetched, ...servers.filter(s => s !== fetched)].slice(0, 20);
      try { localStorage.setItem('servers', JSON.stringify(servers)); } catch {}
    }
    const list = document.getElementById('known-servers');
    list.querySelectorAll('[data-tested]').forEach(o => o.remove());
    const presets = new Set([...list.options].map(o => o.value));
    for (const s of servers.filter(s => !presets.has(s)).reverse()) {
      const o = new Option('Previously tested', s);
      o.dataset.tested = '';
      list.prepend(o);
    }
  });
</script>