feat: derive MCP server evidence from declarations and package registries

[daviddanialy]

Stacked on #5036, which is stacked on #5035. Review those first; the diff
here is only the final commit.

Note that stacked PRs get no CI in this repo — hygiene.yaml and pr.yaml
are both gated on branches: [main] — so this needs a manual
workflow_dispatch until its base merges.

First slice of AIS-468. Answers the approver's most concrete question — "what
permissions is it requesting, just read-only or taking action on behalf?" —
from the two sources available without contacting anything: the MCP annotations
a server publishes, and the shape of each tool's input schema.

Everything here is a declaration, never an observation

The MCP specification is explicit about this:

For trust & safety and security, clients MUST consider tool annotations to
be untrusted unless they come from trusted servers.

A server is free to declare readOnlyHint: true and write anyway. So an
assessment is not evidence of what a server does — its value is that it shows
what authority a server is asking for, which is what lets an admin grant
narrowly. That distinction is load-bearing enough that it is stated in the
package doc, not just here.

Undeclared is its own state

Hint is tri-state: declared true, declared false, or undeclared.

The specification assigns defaults for omitted annotations, and I deliberately
did not encode them. Reading an absent annotation as a positive claim would
manufacture reassurance the server never offered, and this surface has to show
undeclared as undeclared — the same rule the approval page applies to an
unidentified server. Unannotated is surfaced explicitly so a tool that
declared nothing cannot be mistaken for one that declared itself harmless.

For the same reason destructiveHint: false does not add
CapabilityDestructive: it is a claim of non-destructiveness, not a declaration
of destructive capability.

Schema-implied capabilities are heuristics, and labelled as such

Declared and SchemaImplied are separate fields because the two carry
different confidence. Parameter-name and format matching flags a tool
accepting a command, a path, a URL, or a credential — but a server can accept
the same input under any name it likes, so a miss is expected and a hit is a
prompt to look closer rather than a finding. The signal list is deliberately
short and legible instead of exhaustive.

The walk descends through nested objects, array items, and
allOf/anyOf/oneOf so a dangerous parameter cannot hide one level down. It
is depth-bounded: schemas come from the server under review, so a
self-referential one must terminate rather than exhaust the stack.

An unparseable or absent schema yields nothing, which is explicitly not a
statement that the tool takes no dangerous input.

Scope

This is the capability half of AIS-468. Registry provenance and maturity
parsing, the OAuth-scope surfacing, and the ClickHouse "are we already exposed?"
signals land separately. Nothing calls this yet — its consumer is the
mcpapproval API in AIS-470.

Not yet done, and tracked on the ticket: factoring the shared annotation reading
out of scanners/destructivetool, which reads the same destructiveHint but is
call-driven rather than definition-driven.

---

Summary by cubic

Builds evidence for AIS-468 by deriving MCP server capability, requested authority, registry provenance/popularity, and npm/PyPI package metadata for uncatalogued servers. Unifies destructiveHint handling and fixes correctness and lookup edge cases; no user-facing changes.

• New Features

  • Evidence packages: Capability (tri-state hints, ActsOnBehalf, safe-depth schema signals for arbitrary_command|filesystem_path|arbitrary_url|credential_input), Authority (mode undeclared|none|api_key|oauth, scope normalization, DCR from registration_endpoint, demanded/optional secrets, unauthenticated tools), Provenance (official/status/isLatest, publish/update times, visitor estimates), Package metadata (npm/PyPI license, publish window, version/maintainer counts, deprecated/yanked; base URLs overridable; responses size-bounded; nil on unknown).
  • Refactor: share destructiveHint interpretation via capability.DeclaresDestructive(...) with scanners/destructivetool.

• Bug Fixes

  • Deterministic schema capability detection across depths; all same-named parameters examined.
  • OAuth/DCR: a registration_endpoint implies OAuth; DCR derived from the endpoint; fix undeclared vs none.
  • Package lookups: npm recency uses newest per-version release; tolerate time.unpublished; strip only well-formed PyPI extras (treat empty [] as malformed too; malformed specs surface as unknown); reject 200 responses that carry no package name as unrecognized; oversized responses fail with a clear size error.
  • Provenance: empty/unrecognized _meta reads as “not catalogued,” not empty facts.
  • Tests: mutex-guarded registry test helper to remove a race.

^{Written for commit f3249fe. Summary will update on new commits.}

[linear-code]

AIS-468

[changeset-bot]

🦋 Changeset detected

Latest commit: f3249fe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="server/internal/mcpapproval/capability/capability.go">

<violation number="1" location="server/internal/mcpapproval/capability/capability.go:202">
P2: `folderId` inputs are now reported as `filesystem_path` even when they are remote resource IDs; constrain the new marker to path-like fields or require an explicit path format before exposing it as a capability. This creates a false approval signal for common cloud-storage schemas.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: folderId inputs are now reported as filesystem_path even when they are remote resource IDs; constrain the new marker to path-like fields or require an explicit path format before exposing it as a capability. This creates a false approval signal for common cloud-storage schemas.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At server/internal/mcpapproval/capability/capability.go, line 202:

<comment>`folderId` inputs are now reported as `filesystem_path` even when they are remote resource IDs; constrain the new marker to path-like fields or require an explicit path format before exposing it as a capability. This creates a false approval signal for common cloud-storage schemas.</comment>

<file context>
@@ -183,7 +199,7 @@ var parameterSignals = []struct {
 	{
 		capability: CapabilityFilesystemPath,
-		substrings: []string{"path", "filename", "filepath", "directory", "dirname"},
+		substrings: []string{"path", "filename", "filepath", "directory", "dirname", "folder"},
 		formats:    []string{"path"},
 	},
</file context>

[daviddanialy]

Keeping this one as-is. The signal table's own contract (comment at the top of parameterSignals) is deliberately loose: a hit is "a prompt to look closer", never an adjudication — and a folder id on a cloud-storage tool is a resource-location parameter an approver should glance at. Constraining to an explicit path format would drop most honest filesystem servers, which declare no format at all.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>