Server inventory¶
internal/inventory walks tools/list, prompts/list, resources/list, and resources/templates/list after handshake. The result is one deterministic document: server identity, negotiated era and version, advertised capabilities, and every collected primitive (or an explicit reason the family was skipped, failed, or stopped).
Inspect, snapshot, and diff consume this document. They never treat a stopped walk as an empty catalog.
What is collected¶
| Field | Source |
|---|---|
| Server name, title, version | initialize / server/discover serverInfo |
| Era, protocol version, handshake, discover state | Negotiation recorded on the session |
| Capabilities | Presence of tools, prompts, and resources objects |
| Tools | Name, title, description, input/output schema, annotations, icons, _meta |
| Prompts | Name, title, description, arguments, icons, _meta |
| Resources and templates | URI or URI template, name, title, description, MIME type, size, annotations, icons, _meta |
Annotations are untrusted hints. Snapshots keep them so later diffs can see them; they are not used as authorization or safety checks.
Capability gating¶
A family is listed only when the matching capability object was present. Resource templates use the resources capability.
| Capability object | List RPCs |
|---|---|
tools |
tools/list |
prompts |
prompts/list |
resources |
resources/list and resources/templates/list |
If the object is absent, the section status is unsupported with reason capability_absent. mcpdev does not call the list method. That is different from a completed list that returned zero items (complete, empty, no reasons).
Pagination¶
Cursors are opaque. Each list call sends the previous nextCursor (or omits it on the first page) until:
- the server omits
nextCursor(collection finished), - the same cursor repeats (
cursor_loop), MaxPagesis reached (pagination_stopped),MaxItemsis reached (item_limit),- a page is marked incomplete by the protocol adapter (
page_incomplete), - the list RPC fails (
list_failed), - the context is done (
collection_canceled).
Defaults: 256 pages and 10,000 items per family. Zero limits in code mean those defaults, not unbounded collection. The stopped cursor (when collection did not finish) is stored on the section so operators can see where the walk halted.
Duplicate names (tools/prompts) or URIs/templates keep the first item and record duplicate_item on the section. That is not a dropped page; the inventory stays complete unless another stop reason applies.
Status vs empty¶
| Section status | Meaning | Overall incomplete |
|---|---|---|
complete |
Every page was read (the list may be empty) | no |
unsupported |
Capability object missing; no RPC | no |
failed |
A list RPC returned an error (prior items are kept) | yes |
incomplete |
Loop, limit, canceled context, or adapter-incomplete page | yes |
Overall incomplete is true when any advertised family is failed or incomplete. unsupported does not set it. Exit class 60 applies when inspect/snapshot surfaces an incomplete inventory; see CLI.
Stable reason tokens:
capability_absentlist_failedpagination_stoppedcursor_loopitem_limitpage_incompleteduplicate_itemcollection_canceled
Determinism¶
Repeated collection against a stable server produces deeply equal inventories: items are sorted by name (tools/prompts) or URI / URI template (resources/templates), and reason lists are sorted. There are no timestamps on the document.
Packages¶
| Package | Role |
|---|---|
internal/inventory |
Cursor walking, limits, gating, ordering |
internal/protocol |
One-page List and SDK conversion |
internal/model |
Inventory, CatalogSection, descriptors |
internal/snapshot |
Versioned on-disk contract; see Snapshot format |