url elicitation (and AGENTS to be removed)

Author: evalstate

src/everything/AGENTS.md

@@ -1,52 +1,99 @@
-# MCP "Everything" Server - Development Guidelines
-
-## Build, Test & Run Commands
-
-- Build: `npm run build` - Compiles TypeScript to JavaScript
-- Watch mode: `npm run watch` - Watches for changes and rebuilds automatically
-- Run STDIO server: `npm run start:stdio` - Starts the MCP server using stdio transport
-- Run SSE server: `npm run start:sse` - Starts the MCP server with SSE transport
-- Run StreamableHttp server: `npm run start:stremableHttp` - Starts the MCP server with StreamableHttp transport
-- Prepare release: `npm run prepare` - Builds the project for publishing
-
-## Code Style Guidelines
-
-- Use ES modules with `.js` extension in import paths
-- Strictly type all functions and variables with TypeScript
-- Follow zod schema patterns for tool input validation
-- Prefer async/await over callbacks and Promise chains
-- Place all imports at top of file, grouped by external then internal
-- Use descriptive variable names that clearly indicate purpose
-- Implement proper cleanup for timers and resources in server shutdown
-- Handle errors with try/catch blocks and provide clear error messages
-- Use consistent indentation (2 spaces) and trailing commas in multi-line objects
-- Match existing code style, import order, and module layout in the respective folder.
-- Use camelCase for variables/functions,
-- Use PascalCase for types/classes,
-- Use UPPER_CASE for constants
-- Use kebab-case for file names and registered tools, prompts, and resources.
-- Use verbs for tool names, e.g., `get-annotated-message` instead of `annotated-message`
-
-## Extending the Server
-
-The Everything Server is designed to be extended at well-defined points.
-See [Extension Points](docs/extension.md) and [Project Structure](docs/structure.md).
-The server factory is `src/everything/server/index.ts` and registers all features during startup as well as handling post-connection setup.
-
-### High-level
-
-- Tools live under `src/everything/tools/` and are registered via `registerTools(server)`.
-- Resources live under `src/everything/resources/` and are registered via `registerResources(server)`.
-- Prompts live under `src/everything/prompts/` and are registered via `registerPrompts(server)`.
-- Subscriptions and simulated update routines are under `src/everything/resources/subscriptions.ts`.
-- Logging helpers are under `src/everything/server/logging.ts`.
-- Transport managers are under `src/everything/transports/`.
-
-### When adding a new feature
-
-- Follow the existing file/module pattern in its folder (naming, exports, and registration function).
-- Export a `registerX(server)` function that registers new items with the MCP SDK in the same style as existing ones.
-- Wire your new module into the central index (e.g., update `tools/index.ts`, `resources/index.ts`, or `prompts/index.ts`).
-- Ensure schemas (for tools) are accurate JSON Schema and include helpful descriptions and examples.
-  `server/index.ts` and usages in `logging.ts` and `subscriptions.ts`.
-- Keep the docs in `src/everything/docs/` up to date if you add or modify noteworthy features.
+# MCP Everything Server — Agent Memory
+
+_Last oriented: 2026-02-13_
+
+## Workspace + Scope
+
+- Workspace root: `/home/ssmith/source/servers/src/everything`
+- This directory is the package root for this server.
+- Generated output is in `dist/`; **edit source `.ts` files only**.
+
+## Fast Orientation Map
+
+- CLI transport selector: `index.ts`
+- Server factory: `server/index.ts`
+  - Creates `McpServer` with capabilities + instructions
+  - Registers tools/resources/prompts
+  - Installs subscription handlers
+  - Registers capability-gated tools in `oninitialized`
+  - Delays initial roots sync via `setTimeout(..., 350)`
+- Registries:
+  - `tools/index.ts` → `registerTools(server)` + `registerConditionalTools(server)`
+  - `resources/index.ts` → `registerResources(server)` + `readInstructions()`
+  - `prompts/index.ts` → `registerPrompts(server)`
+- Key support files:
+  - `resources/subscriptions.ts` (resource subscribe/unsubscribe + simulated updates)
+  - `server/logging.ts` (simulated logging)
+  - `server/roots.ts` (client roots sync/cache)
+
+## Build / Test / Run
+
+- Build: `npm run build`
+- Watch: `npm run watch`
+- Typecheck: `npx tsc --noEmit --pretty false`
+- Tests: `npm test`
+- STDIO: `npm run start:stdio`
+- SSE: `npm run start:sse`
+- Streamable HTTP: `npm run start:streamableHttp`
+- Prepare release: `npm run prepare`
+
+## Search Setup (ripgrep-first)
+
+Use rg with generated/vendor exclusions:
+
+```bash
+rg -n --glob '!dist/**' --glob '!node_modules/**' '<pattern>'
+```
+
+Useful presets:
+
+```bash
+rg -n --glob '!dist/**' 'registerTools|registerResources|registerPrompts|registerConditionalTools' .
+rg -n --glob '!dist/**' 'createServer|oninitialized|setSubscriptionHandlers|syncRoots|cleanup' server tools resources transports
+rg -n --glob '!dist/**' 'z\.object|inputSchema|outputSchema|zodToJsonSchema' tools
+rg -n --glob '!dist/**' 'setInterval|setTimeout|clearInterval|clearTimeout|onclose|SIGINT' .
+```
+
+## LSP Setup (TypeScript)
+
+- Project config: `tsconfig.json` (extends `../../tsconfig.json`).
+- TS SDK path: `../../node_modules/typescript/lib`.
+- Confirm LSP/type health: `npx tsc --noEmit --pretty false`.
+- High-value symbol navigation targets:
+  - `createServer`
+  - `registerTools` / `registerConditionalTools`
+  - `registerResources`
+  - `registerPrompts`
+
+## Coding Rules to Preserve
+
+- ES modules with `.js` extension in TS imports.
+- Strong typing for functions/variables.
+- Prefer `async/await` over callback chains.
+- Tool input validation via zod schema patterns.
+- Keep imports at top; external imports before internal imports.
+- Use descriptive names.
+- Handle errors with `try/catch` and clear messages.
+- Ensure cleanup for timers/resources during shutdown.
+- Formatting: 2-space indent, trailing commas in multiline objects.
+- Naming:
+  - camelCase: variables/functions
+  - PascalCase: types/classes
+  - UPPER_CASE: constants
+  - kebab-case: filenames + registered tools/prompts/resources
+  - Tool names should be verbs (e.g. `get-annotated-message`)
+
+## Extension Workflow
+
+1. Add module in `tools/`, `resources/`, or `prompts/` following existing pattern.
+2. Export `registerX(server)` from that module.
+3. Wire it in the domain index file.
+4. Keep schemas accurate and descriptive (for tools).
+5. Update `docs/` for notable behavioral changes.
+6. If registrations change, update tests that assert counts/content.
+
+## Practical Gotchas
+
+- Conditional tools are registered **after** client initialization.
+- Server instructions are loaded from `docs/instructions.md`.
+- Session-scoped behavior exists (logging, subscription updates, session resources).

src/everything/__tests__/registrations.test.ts

@@ -54,7 +54,7 @@ describe('Registration Index Files', () => {
         server: {
           getClientCapabilities: vi.fn(() => ({
             roots: {},
-            elicitation: {},
+            elicitation: { url: {} },
             sampling: {},
           })),
         },
@@ -67,14 +67,15 @@ describe('Registration Index Files', () => {
 
       registerConditionalTools(mockServerWithCapabilities);
 
-      // Should register 3 conditional tools + 3 task-based tools when all capabilities present
-      expect(mockServerWithCapabilities.registerTool).toHaveBeenCalledTimes(3);
+      // Should register 4 conditional tools + 3 task-based tools when all capabilities present
+      expect(mockServerWithCapabilities.registerTool).toHaveBeenCalledTimes(4);
 
       const registeredTools = (
         mockServerWithCapabilities.registerTool as any
       ).mock.calls.map((call: any[]) => call[0]);
       expect(registeredTools).toContain('get-roots-list');
       expect(registeredTools).toContain('trigger-elicitation-request');
+      expect(registeredTools).toContain('trigger-url-elicitation-request');
       expect(registeredTools).toContain('trigger-sampling-request');
 
       // Task-based tools are registered via experimental.tasks.registerToolTask

src/everything/__tests__/tools.test.ts

@@ -13,6 +13,7 @@ import { registerToggleSimulatedLoggingTool } from '../tools/toggle-simulated-lo
 import { registerToggleSubscriberUpdatesTool } from '../tools/toggle-subscriber-updates.js';
 import { registerTriggerSamplingRequestTool } from '../tools/trigger-sampling-request.js';
 import { registerTriggerElicitationRequestTool } from '../tools/trigger-elicitation-request.js';
+import { registerTriggerUrlElicitationRequestTool } from '../tools/trigger-url-elicitation-request.js';
 import { registerGetRootsListTool } from '../tools/get-roots-list.js';
 import { registerGZipFileAsResourceTool } from '../tools/gzip-file-as-resource.js';
 
@@ -706,6 +707,101 @@ describe('Tools', () => {
     });
   });
 
+  describe('trigger-url-elicitation-request', () => {
+    it('should not register when client does not support URL elicitation', () => {
+      const handlers: Map<string, Function> = new Map();
+      const mockServer = {
+        registerTool: vi.fn((name: string, config: any, handler: Function) => {
+          handlers.set(name, handler);
+        }),
+        server: {
+          getClientCapabilities: vi.fn(() => ({ elicitation: { form: {} } })),
+        },
+      } as unknown as McpServer;
+
+      registerTriggerUrlElicitationRequestTool(mockServer);
+
+      expect(mockServer.registerTool).not.toHaveBeenCalled();
+    });
+
+    it('should register when client supports URL elicitation', () => {
+      const handlers: Map<string, Function> = new Map();
+      const mockServer = {
+        registerTool: vi.fn((name: string, config: any, handler: Function) => {
+          handlers.set(name, handler);
+        }),
+        server: {
+          getClientCapabilities: vi.fn(() => ({ elicitation: { url: {} } })),
+          createElicitationCompletionNotifier: vi.fn(() => vi.fn()),
+        },
+      } as unknown as McpServer;
+
+      registerTriggerUrlElicitationRequestTool(mockServer);
+
+      expect(mockServer.registerTool).toHaveBeenCalledWith(
+        'trigger-url-elicitation-request',
+        expect.objectContaining({
+          title: 'Trigger URL Elicitation Request Tool',
+          description: expect.stringContaining('URL elicitation'),
+        }),
+        expect.any(Function)
+      );
+    });
+
+    it('should send URL-mode elicitation request and notify completion when requested', async () => {
+      const handlers: Map<string, Function> = new Map();
+      const mockSendRequest = vi.fn().mockResolvedValue({
+        action: 'accept',
+      });
+      const mockNotifyComplete = vi.fn().mockResolvedValue(undefined);
+
+      const mockServer = {
+        registerTool: vi.fn((name: string, config: any, handler: Function) => {
+          handlers.set(name, handler);
+        }),
+        server: {
+          getClientCapabilities: vi.fn(() => ({ elicitation: { url: {} } })),
+          createElicitationCompletionNotifier: vi
+            .fn()
+            .mockReturnValue(mockNotifyComplete),
+        },
+      } as unknown as McpServer;
+
+      registerTriggerUrlElicitationRequestTool(mockServer);
+
+      const handler = handlers.get('trigger-url-elicitation-request')!;
+      const result = await handler(
+        {
+          url: 'https://example.com/verify',
+          message: 'Open this page to verify your identity',
+          elicitationId: 'elicitation-123',
+          sendCompletionNotification: true,
+        },
+        { sendRequest: mockSendRequest }
+      );
+
+      expect(mockSendRequest).toHaveBeenCalledWith(
+        expect.objectContaining({
+          method: 'elicitation/create',
+          params: expect.objectContaining({
+            mode: 'url',
+            url: 'https://example.com/verify',
+            message: 'Open this page to verify your identity',
+            elicitationId: 'elicitation-123',
+          }),
+        }),
+        expect.anything(),
+        expect.anything()
+      );
+
+      expect(mockServer.server.createElicitationCompletionNotifier).toHaveBeenCalledWith(
+        'elicitation-123'
+      );
+      expect(mockNotifyComplete).toHaveBeenCalledTimes(1);
+      expect(result.content[0].text).toContain('URL elicitation action: accept');
+    });
+  });
+
   describe('get-roots-list', () => {
     it('should not register when client does not support roots', () => {
       const { mockServer } = createMockServer();

src/everything/docs/features.md

@@ -22,6 +22,8 @@
 - `trigger-long-running-operation` (tools/trigger-trigger-long-running-operation.ts): Simulates a multi-step operation over a given `duration` and number of `steps`; reports progress via `notifications/progress` when a `progressToken` is provided by the client.
 - `toggle-simulated-logging` (tools/toggle-simulated-logging.ts): Starts or stops simulated, random‑leveled logging for the invoking session. Respects the client’s selected minimum logging level.
 - `toggle-subscriber-updates` (tools/toggle-subscriber-updates.ts): Starts or stops simulated resource update notifications for URIs the invoking session has subscribed to.
+- `trigger-elicitation-request` (tools/trigger-elicitation-request.ts): Issues an `elicitation/create` request using form-mode fields (strings, numbers, booleans, enums, and format validation) and returns the resulting action/content.
+- `trigger-url-elicitation-request` (tools/trigger-url-elicitation-request.ts): Issues an `elicitation/create` request in URL mode (`mode: "url"`) with an `elicitationId`, and can optionally emit `notifications/elicitation/complete` after acceptance. Requires client capability `elicitation.url`.
 - `trigger-sampling-request` (tools/trigger-sampling-request.ts): Issues a `sampling/createMessage` request to the client/LLM using provided `prompt` and optional generation controls; returns the LLM's response payload.
 - `simulate-research-query` (tools/simulate-research-query.ts): Demonstrates MCP Tasks (SEP-1686) with a simulated multi-stage research operation. Accepts `topic` and `ambiguous` parameters. Returns a task that progresses through stages with status updates. If `ambiguous` is true and client supports elicitation, sends an elicitation request directly to gather clarification before completing.
 - `trigger-sampling-request-async` (tools/trigger-sampling-request-async.ts): Demonstrates bidirectional tasks where the server sends a sampling request that the client executes as a background task. Server polls for status and retrieves the LLM result when complete. Requires client to support `tasks.requests.sampling.createMessage`.

src/everything/docs/structure.md

@@ -52,6 +52,7 @@ src/everything
      │   ├── toggle-subscriber-updates.ts
      │   ├── trigger-elicitation-request.ts
      │   ├── trigger-long-running-operation.ts
+     │   ├── trigger-url-elicitation-request.ts
      │   └── trigger-sampling-request.ts
      └── transports
          ├── sse.ts
@@ -149,6 +150,8 @@ src/everything
     - `GZIP_ALLOWED_DOMAINS` (comma-separated allowlist; empty means all domains allowed)
 - `trigger-elicitation-request.ts`
   - Registers a `trigger-elicitation-request` tool that sends an `elicitation/create` request to the client/LLM and returns the elicitation result.
+- `trigger-url-elicitation-request.ts`
+  - Registers a `trigger-url-elicitation-request` tool that sends an out-of-band URL-mode `elicitation/create` request (`mode: "url"`) including an `elicitationId`, and can optionally emit `notifications/elicitation/complete` after acceptance.
 - `trigger-sampling-request.ts`
   - Registers a `trigger-sampling-request` tool that sends a `sampling/createMessage` request to the client/LLM and returns the sampling result.
 - `get-structured-content.ts`

src/everything/tools/index.ts

@@ -17,6 +17,7 @@ import { registerTriggerSamplingRequestTool } from "./trigger-sampling-request.j
 import { registerTriggerSamplingRequestAsyncTool } from "./trigger-sampling-request-async.js";
 import { registerTriggerElicitationRequestAsyncTool } from "./trigger-elicitation-request-async.js";
 import { registerSimulateResearchQueryTool } from "./simulate-research-query.js";
+import { registerTriggerUrlElicitationRequestTool } from "./trigger-url-elicitation-request.js";
 
 /**
  * Register the tools with the MCP server.
@@ -44,6 +45,7 @@ export const registerTools = (server: McpServer) => {
 export const registerConditionalTools = (server: McpServer) => {
   registerGetRootsListTool(server);
   registerTriggerElicitationRequestTool(server);
+  registerTriggerUrlElicitationRequestTool(server);
   registerTriggerSamplingRequestTool(server);
   // Task-based research tool (uses experimental tasks API)
   registerSimulateResearchQueryTool(server);