Commit graph servers/src/everything/docs/structure.md
Author SHA1 Message Date
Cliff Hall
25e5f3a6e8
fix(everything): prevent URL elicitation error-path infinite loop (#4285)
* url elicitation

* single tool for normal and error path

* Address review feedback on URL elicitation tool

- Remove src/everything/pnpm-lock.yaml (monorepo uses npm workspaces)
- Drop redundant TriggerUrlElicitationSchema.parse(args) in the handler;
  destructure directly from args like the other tools, since the SDK
  validates against the registered schema before invoking the handler
- Add explicit accept/decline/cancel messaging in the request path,
  mirroring trigger-elicitation-request.ts
- Clarify the registerTool count comment in registrations.test.ts
  (task-based tools register via registerToolTask, counted separately)
- Add tests covering the no-url / undefined-capability registration
  guards, the randomUUID() elicitationId fallback, and the
  decline/cancel response paths (100% coverage of the tool)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Add tool annotations to trigger-url-elicitation

Match the annotations block on sibling elicitation tools and the
CLAUDE.md guidance. Uses openWorldHint: true since the tool drives an
external browser flow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(everything): prevent URL elicitation error-path infinite loop

The trigger-url-elicitation tool's error path (errorPath=true) threw
UrlElicitationRequiredError (-32042) carrying the same URL that failed and
re-threw it on every retry, so clients looped (and tripped their own loop
detection).

- Point the prerequisite elicitation at a different URL
  (https://modelcontextprotocol.io) than the failing request.
- Track issued prerequisites by the inputs a client resends on retry
  (session + url + caller-supplied elicitationId); a plain retry is then
  recognized, ignores errorPath, and proceeds via the request path instead
  of re-throwing the prerequisite.
- Update tests and docs accordingly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(everything): address review on URL elicitation error path

- Replace raw NUL byte delimiters in errorPathKey with the \u0000 escape
  sequence so the source stays plain text and the diff is reviewable
  (same collision-proof delimiter at runtime).
- Add a one-shot test reset helper + beforeEach so the suite is robust to
  the module-level marker state regardless of order.
- Use a dedicated prerequisite message instead of reusing the caller's.
- Document the unbounded-growth tradeoff as a demo simplification and note
  the one-shot marker semantics in docs/features.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: evalstate <1936278+evalstate@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-06 18:47:20 -07:00
shaun smith
3a32d1024b
Add URL Elicitation cases (#3334)
* url elicitation

* single tool for normal and error path

* Address review feedback on URL elicitation tool

- Remove src/everything/pnpm-lock.yaml (monorepo uses npm workspaces)
- Drop redundant TriggerUrlElicitationSchema.parse(args) in the handler;
  destructure directly from args like the other tools, since the SDK
  validates against the registered schema before invoking the handler
- Add explicit accept/decline/cancel messaging in the request path,
  mirroring trigger-elicitation-request.ts
- Clarify the registerTool count comment in registrations.test.ts
  (task-based tools register via registerToolTask, counted separately)
- Add tests covering the no-url / undefined-capability registration
  guards, the randomUUID() elicitationId fallback, and the
  decline/cancel response paths (100% coverage of the tool)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Add tool annotations to trigger-url-elicitation

Match the annotations block on sibling elicitation tools and the
CLAUDE.md guidance. Uses openWorldHint: true since the tool drives an
external browser flow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: cliffhall <cliff@futurescale.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-03 18:10:07 -07:00
olaservo
106216491e Update structure.md to reflect all tool annotations and new tools
- Update get-annotated-message description: all tools now have
  tool-level annotations, not just this one
- Add missing tool entries: simulate-research-query,
  trigger-elicitation-request-async, trigger-sampling-request-async
- Add these tools to the file tree listing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 17:32:16 -07:00
olaservo
c743a10da0 feat(everything): add tool-level annotations to get-annotated-message
Add readOnlyHint, destructiveHint, idempotentHint, and openWorldHint
annotations to the tool config. Update docs to reflect that this tool
now demonstrates both tool-level and content annotations.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 07:48:43 -07:00
cliffhall
1b8f376b90 Demonstrate registration of tools conditioned upon client capability support. Also, obviated need for clientConnected callback to pass sessionId because we defer initial fetching of roots happens when you run the get-roots-list tool.
* In how-it-works.md,
  - added a section on conditional tool registration

* In server/index.ts
  - import registerConditionalTools
  - in an oninitialized handler for the server, call registerConditionalTools
  - removed clientConnected from ServerFactoryResponse and all mentions in docs

* In tools/index.ts
  - export a registerConditionalTools function
  - refactor/move calls to registerGetRootsListTool, registerTriggerElicitationRequestTool, and registerTriggerSamplingRequestTool out of registerTools and into registerConditionalTools

* In server/roots.ts
  - only act if client supports roots
  - remove setInterval from call to requestRoots. It isn't happening during the initialze handshake anymore, so it doesn't interfere with that process if called immediaately

* In get-roots-list.ts, trigger-elicitation-request.ts, and trigger-sampling-request.ts,
  - only register tool if client supports capability

* Throughout the rest of the files, removing all references to `clientConnected`
2025-12-15 17:51:30 -05:00
cliffhall
a235ed8016 Updated package.json and ran prettier 2025-12-13 14:33:16 -05:00
cliffhall
2b60822057 Refactor-renamed long-running-operation.ts to trigger-long-running-operation.ts 2025-12-13 14:20:24 -05:00
cliffhall
a008d9fee6 Updated structure.md 2025-12-13 11:42:23 -05:00
cliffhall
f561f70002 [WIP] Refactor everything server to be more modular and use recommended APIs.
* Updated docs

* Refactor/renamed toggle-logging.ts to toggle-simulated-logging.ts
  - refactor/renamed registerToggleLoggingTool to registerToggleSimulatedLoggingTool
2025-12-13 10:59:35 -05:00
cliffhall
19e588bdcb [WIP] Refactor everything server to be more modular and use recommended APIs.
Updated structure.md
2025-12-13 10:20:16 -05:00
cliffhall
9b25a3a41b [WIP] Refactor everything server to be more modular and use recommended APIs.
Finalized Roots list changed handling and initial request. Final fit and finish work.

* Updated architecture.md
  - Added links to other docs
  - Refactor/extracted sections into extension.md, features.md, how-it-works.md, startup.md, and structure.md

* Removed everything.ts
  - all features are ported

* In roots.ts
  - refactor/renaned setRootsListChangedHandler to syncRoots
  - refactor handler logic to requestRoots function
  - Calls for roots list directly to get initial list

* In server/index.ts
  - import setRootsListChangedHandler
  - in clientConnected callback
    - call setRootsListChangedHandler passing server and sessionId

* In sse.ts, stdio.ts, and streamableHttp.ts
  - update inline and function docs

* In index.ts,
  - updated usage output

* In server/index.ts
  - refactor/extracted readInstructions to resources/index.ts
  - defined ServerFactoryResponse response type
2025-12-12 20:12:18 -05:00