@n24q02m/mcp-core 1.19.0-beta.4 → 1.19.0

package/README.md

@@ -0,0 +1,228 @@
+# mcp-core
+
+**Shared foundation for building MCP servers -- Streamable HTTP transport, OAuth 2.1, browser-based credential setup, and a shared embedding daemon.**
+
+<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO -->
+<details>
+  <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>
+
+| Project | Tagline | Tag |
+|---|---|---|
+| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
+| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
+| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
+| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
+| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
+| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
+| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
+| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
+| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
+| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
+| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
+| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |
+| [tacet](https://github.com/n24q02m/tacet) | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |
+| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
+| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
+
+</details>
+<!-- END: AUTO-GENERATED-CROSS-PROMO -->
+
+## Table of contents
+
+- [Packages](#packages)
+- [What you get](#what-you-get)
+- [Quick start (Python)](#quick-start-python)
+- [Quick start (TypeScript)](#quick-start-typescript)
+- [Documentation](#documentation)
+- [Development](#development)
+- [License](#license)
+
+
+
+mcp-core is the shared foundation for the n24q02m MCP servers: a Streamable
+HTTP transport, an OAuth 2.1 Authorization Server, lifecycle management,
+install automation, and a shared embedding daemon.
+
+`mcp-core` is the **functional successor** to the archived
+[`mcp-relay-core`](https://github.com/n24q02m/mcp-relay-core). All crypto,
+storage, OAuth, relay, and schema modules from `mcp-relay-core` ship under
+the same paths in `mcp-core` (1:1 superset), so downstream MCP servers can
+migrate with a pure import + dependency rename. See the
+[Migration guide](https://mcp.n24q02m.com/servers/mcp-core/migration/)
+for the rename table.
+
+## Packages
+
+| Package | Language | Registry | Install |
+|---------|----------|----------|---------|
+| [`packages/core-py`](packages/core-py) | Python 3.13 | PyPI: [`n24q02m-mcp-core`](https://pypi.org/project/n24q02m-mcp-core/) | `pip install n24q02m-mcp-core` |
+| [`packages/core-ts`](packages/core-ts) | TypeScript / Node 24 | npm: [`@n24q02m/mcp-core`](https://www.npmjs.com/package/@n24q02m/mcp-core) | `bun add @n24q02m/mcp-core` |
+| [`packages/embedding-daemon`](packages/embedding-daemon) | Python 3.13 | PyPI: [`mcp-embedding-daemon`](https://pypi.org/project/mcp-embedding-daemon/) | `pip install mcp-embedding-daemon` |
+
+All three packages share the same version (`semantic-release.toml` bumps both
+Python `pyproject.toml` files plus the npm `package.json` in lockstep).
+
+The Python core ships one optional extra for the LLM passthrough (litellm):
+`pip install 'n24q02m-mcp-core[llm]'`.
+
+## What you get
+
+### `n24q02m-mcp-core` (Python) and `@n24q02m/mcp-core` (TypeScript)
+
+These modules ship in **both** languages with a matching public API
+(cross-language test vectors keep the crypto byte-for-byte identical):
+
+- **`crypto/`** — ECDH P-256, AES-256-GCM, HKDF-SHA256 primitives.
+  Cross-language test vectors guarantee Python and TypeScript produce the
+  same ciphertext for the same input.
+- **`storage/`** — `PerPluginStore`, the per-plugin encrypted credential
+  store. Single-user (stdio / HTTP) writes `~/.<plugin>-mcp/config.json`
+  encrypted with a machine-bound key; HTTP multi-user writes
+  `~/.<plugin>-mcp/subs/<sub>/config.json` encrypted with a key derived from
+  the `CREDENTIAL_SECRET` env var (salt `<plugin>:<sub>`). Pluggable
+  `CredentialBackend`s (`LocalFsBackend`, `CfKvBackend`) decouple the on-disk
+  layout from serverless deployments. Also ships session lock files and
+  config resolver helpers. The legacy shared `config.enc` file
+  (`storage.config_file`) is deprecated.
+- **`auth/`** — the self-hosted OAuth 2.1 Authorization Server that downstream
+  servers actually run: `create_local_oauth_app` (Starlette ASGI app serving
+  `/authorize`, `/token`, the `/.well-known/oauth-*` metadata, and the
+  browser-rendered credential form), `render_credential_form`, the optional
+  shared-password gate at `/login` (`MCP_RELAY_PASSWORD`, empty disables it),
+  and `create_delegated_oauth_app` for upstream-redirect / device-code
+  multi-user flows.
+- **`oauth/`** — OAuth 2.1 primitives consumed by `auth/`: `JWTIssuer`
+  (RS256), `SqliteUserStore` for multi-user mode, and `OAuthProvider`, the
+  legacy `mcp-relay-core` PKCE-over-relay provider retained for migration.
+- **`relay/`** — `RelaySession`, `create_session`, `poll_for_result`,
+  `send_message` plus the EFF Diceware wordlist for passphrase generation.
+  This is the legacy `mcp-relay-core` ECDH relay-client path used by
+  `OAuthProvider`; the live setup UX is the `auth/` browser credential form.
+- **`schema/`** — `RelayConfigSchema` TypedDict that downstream servers use
+  to declare their config form.
+- **`transport/`** — `StreamableHTTPServer` wrapper around FastMCP /
+  `@modelcontextprotocol/sdk` Streamable HTTP transport, plus
+  `OAuthMiddleware` (RFC 6750 + RFC 9728 compliant Bearer validation).
+- **`lifecycle/`** — `LifecycleLock` cross-platform file lock that prevents
+  two server instances from binding the same `(name, port)` pair.
+
+### Python-only modules (`n24q02m-mcp-core`)
+
+These have no TypeScript counterpart yet — they back the Python MCP servers
+(wet, mnemo, code-review-graph, telegram, imagine):
+
+- **`llm/`** — a thin passthrough over [litellm](https://github.com/BerriAI/litellm)
+  so every server talks to cloud providers the same way. Async + sync wrappers
+  for `completion`, `embedding`, `rerank`, `image_generation`,
+  `video_generation` / `video_status` / `video_content`; a graceful capability
+  check against the litellm registry (`check_capability`, `list_models`,
+  `suggest_models`, `supports_vision`); multi-key CSV rotation per provider
+  (`rotate_keys`, `split_keys`); and a direct Vertex AI **Express** adapter
+  (`completion_express`) that bypasses litellm where its `vertex_ai/` route
+  ignores the Express API key. Provider keys follow the litellm convention —
+  `GEMINI_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `ANTHROPIC_API_KEY`,
+  `COHERE_API_KEY`, `JINA_AI_API_KEY`, `GOOGLE_VERTEX_EXPRESS_API_KEY` (see
+  `llm.providers.PROVIDER_KEY_ENV`); any unlisted provider falls back to
+  `<PROVIDER>_API_KEY`. Requires the optional extra:
+  `pip install 'n24q02m-mcp-core[llm]'`.
+- **`chains.py`** — the capability provider-chain primitive every server shares
+  (exported at the top level): `resolve_backend` makes the 3-way
+  cloud / local / unavailable decision, `run_with_fallback` walks an ordered
+  list of providers and returns the first non-empty result, and
+  `local_enabled_from_env` reads the per-capability `DISABLE_LOCAL_<X>` toggle
+  (`DISABLE_LOCAL_SEARCH` / `DISABLE_LOCAL_BROWSER` / `DISABLE_LOCAL_EMBED` /
+  `DISABLE_LOCAL_RERANK`).
+- **`http/`** — SSRF-safe HTTP clients (`get_ssrf_safe_async_client`,
+  `get_ssrf_safe_sync_client`, `vet_api_base`) that block requests to private /
+  loopback / link-local addresses. Used to vet every user-supplied `api_base`
+  before it reaches an outbound provider call.
+- **`install/`** — `AgentInstaller` writes MCP server entries into Claude Code,
+  Cursor, Codex, Windsurf, and OpenCode config files. Ships the
+  `mcp-clean-state` console script for wiping local config / session state.
+
+### `mcp-embedding-daemon`
+
+FastAPI HTTP server scaffold for the upcoming shared ONNX/GGUF embedding
+backend. Currently exposes:
+
+- `GET /health` — returns `{status, version}`
+- `POST /embed` — returns 501 with a roadmap link (backend wiring lands in
+  the next release)
+- `POST /rerank` — returns 501 with a roadmap link
+
+CLI entry point: `mcp-embedding-daemon --host 127.0.0.1 --port 9800`.
+
+## Quick start (Python)
+
+```python
+from mcp_core import RelaySession, create_session, decrypt
+from mcp_core.transport.streamable_http import StreamableHTTPServer
+from mcp_core.oauth import JWTIssuer
+from mcp_core.transport.oauth_middleware import OAuthMiddleware
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+issuer = JWTIssuer("my-server")
+issuer  # Use issuer.issue_access_token(sub) / verify_access_token(token)
+
+middleware = [OAuthMiddleware(issuer=issuer, resource_metadata_url="http://127.0.0.1:9876/.well-known/oauth-protected-resource")]
+server = StreamableHTTPServer(mcp, port=9876, middleware=middleware)
+server.run()
+```
+
+## Quick start (TypeScript)
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { JWTIssuer } from '@n24q02m/mcp-core/oauth'
+import { OAuthMiddleware, StreamableHTTPServer } from '@n24q02m/mcp-core/transport'
+
+const server = new McpServer({ name: 'my-server', version: '0.0.0' })
+const issuer = new JWTIssuer('my-server')
+await issuer.init()
+
+const middleware = new OAuthMiddleware({
+  jwtIssuer: issuer,
+  resourceMetadataUrl: 'http://127.0.0.1:9876/.well-known/oauth-protected-resource'
+})
+
+const http = new StreamableHTTPServer({ server, port: 9876, oauthMiddleware: middleware })
+await http.connect()
+// Then mount http.handleRequest(req, res) on your http.Server / Express / Hono.
+```
+
+## Documentation
+
+Full docs at **[mcp.n24q02m.com/servers/mcp-core/architecture/](https://mcp.n24q02m.com/servers/mcp-core/architecture/)** (Foundation library section in the MCP n24q02m unified docs site):
+
+- [Architecture](https://mcp.n24q02m.com/servers/mcp-core/architecture/) -- transport, OAuth AS, lifecycle, multi-user primitives
+- [Trust model](https://mcp.n24q02m.com/servers/mcp-core/trust-model/) -- threat model + key-handling guarantees
+- [Migration](https://mcp.n24q02m.com/servers/mcp-core/migration/) -- breaking-change history and upgrade paths from `mcp-relay-core`
+- [Shared services](https://mcp.n24q02m.com/servers/mcp-core/shared-services/) -- embedding daemon + ancillary docker-compose stack
+
+Source of truth lives in [`n24q02m/claude-plugins/plugins/mcp-core/`](https://github.com/n24q02m/claude-plugins/tree/main/plugins/mcp-core). Edit there; this repo's `docs/` directory is intentionally minimal post-migration.
+
+## Development
+
+```bash
+mise run setup            # install runtimes + deps + pre-commit hooks
+bun install               # root TypeScript workspace install
+
+# Python (per package)
+cd packages/core-py
+uv sync --group dev
+uv run pytest
+uv run ty check
+uv run ruff check .
+
+# TypeScript
+cd packages/core-ts
+bun run test
+bun run check
+bun run build
+```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -6,7 +6,7 @@ export { InMemoryAuthCache, type IOAuthSessionCache, OAuthProvider, type OAuthPr
 export { type IUserCredentialStore, SqliteUserStore } from './oauth/user-store.js';
 export { tryOpenBrowser } from './relay/browser.js';
 export { createSession, generatePassphrase, notifyComplete, pollForResponses, pollForResult, type RelaySession, sendMessage } from './relay/client.js';
-export { buildOpenRelayHandler, type OpenRelayHandlerOptions, type OpenRelayResult, registerOpenRelayTool, type ToolRegistrar } from './relay/tool-helpers.js';
+export { buildOpenRelayHandler, type ElicitationServer, type OpenRelayHandlerOptions, type OpenRelayResult, registerOpenRelayTool, type ToolRegistrar } from './relay/tool-helpers.js';
 export type * from './schema/types.js';
 export { deleteConfig, exportConfig, importConfig, listConfigs, readConfig, scheduleReloadExit, writeConfig } from './storage/config-file.js';
 export { clearMode, getMode, type ServerMode, setLocalMode } from './storage/mode.js';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,2BAA2B,EAC3B,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAA;AACxB,cAAc,mBAAmB,CAAA;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,KAAK,YAAY,EACjB,WAAW,EACZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAA;AAChC,mBAAmB,mBAAmB,CAAA;AACtC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,WAAW,EACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrF,cAAc,uBAAuB,CAAA;AACrC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,WAAW,EAChB,gBAAgB,EACjB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,aAAa,EACd,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,2BAA2B,EAC3B,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,iBAAiB,CAAA;AACxB,cAAc,mBAAmB,CAAA;AAEjC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,KAAK,YAAY,EACjB,WAAW,EACZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAA;AAChC,mBAAmB,mBAAmB,CAAA;AACtC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,WAAW,EACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrF,cAAc,uBAAuB,CAAA;AACrC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,WAAW,EAChB,gBAAgB,EACjB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,aAAa,EACd,MAAM,6BAA6B,CAAA"}

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,2EAA2E;AAC3E,OAAO,EACL,2BAA2B,EAI3B,uBAAuB,EACvB,mBAAmB,EAQnB,yBAAyB,EAGzB,oBAAoB,EAKrB,MAAM,iBAAiB,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,kDAAkD;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EACL,iBAAiB,EAEjB,aAAa,EAGd,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAA6B,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EAGrB,qBAAqB,EAEtB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,WAAW,EACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAmB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrF,cAAc,uBAAuB,CAAA;AACrC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAElB,gBAAgB,EACjB,MAAM,2BAA2B,CAAA;AAClC,uEAAuE;AACvE,OAAO,EAGL,aAAa,EACd,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,2EAA2E;AAC3E,OAAO,EACL,2BAA2B,EAI3B,uBAAuB,EACvB,mBAAmB,EAQnB,yBAAyB,EAGzB,oBAAoB,EAKrB,MAAM,iBAAiB,CAAA;AACxB,cAAc,mBAAmB,CAAA;AACjC,kDAAkD;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EACL,iBAAiB,EAEjB,aAAa,EAGd,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAA6B,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,aAAa,EAEb,WAAW,EACZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EAIrB,qBAAqB,EAEtB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,WAAW,EACZ,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAmB,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrF,cAAc,uBAAuB,CAAA;AACrC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAElB,gBAAgB,EACjB,MAAM,2BAA2B,CAAA;AAClC,uEAAuE;AACvE,OAAO,EAGL,aAAa,EACd,MAAM,6BAA6B,CAAA"}

package/build/relay/tool-helpers.d.ts

@@ -3,28 +3,52 @@
  *
  * After the stdio-pure + http-multi-user split, the relay config form is
  * served by the HTTP server itself at ``<PUBLIC_URL>/authorize``. The
- * ``config__open_relay`` tool simply returns that URL and best-effort opens
- * the user's default browser. There is no daemon-bridge discovery, no
- * respawn, and no session deduplication — the HTTP server's own session
- * tracking handles concurrent setup attempts.
+ * ``config__open_relay`` tool directs the user to that URL.
+ *
+ * When the connected client declares URL-mode elicitation
+ * (``capabilities.elicitation.url``, SEP-1036), the tool asks the client to
+ * present a consent prompt and open the URL via ``Server.elicitInput`` so the
+ * credential form is opened out-of-band without the LLM in the loop. Clients
+ * that do NOT declare the capability fall back to the legacy behaviour: the
+ * tool returns the URL and best-effort opens the user's default browser
+ * server-side. There is no daemon-bridge discovery, no respawn, and no
+ * session deduplication — the HTTP server's own session tracking handles
+ * concurrent setup attempts.
  *
  * In stdio mode, the relay form does not exist; the tool returns
  * ``stdio_unsupported`` so plugin code can render a "switch to HTTP mode"
  * message instead of misleading the user with an unreachable URL.
  */
+import type { ClientCapabilities, ElicitRequestURLParams, ElicitResult } from '@modelcontextprotocol/sdk/types.js';
 export interface OpenRelayResult {
     url: string;
     browserOpened: boolean;
     status: 'configured' | 'unconfigured' | 'expired' | 'session_active' | 'stdio_unsupported';
+    elicitation?: 'accepted' | 'declined' | 'cancelled';
+}
+/**
+ * Minimal surface required to drive URL-mode elicitation. Satisfied by the
+ * low-level `Server` from `@modelcontextprotocol/sdk` (`mcp.server`), which
+ * exposes both `getClientCapabilities` and `elicitInput`.
+ */
+export interface ElicitationServer {
+    getClientCapabilities: () => ClientCapabilities | undefined;
+    elicitInput: (params: ElicitRequestURLParams) => Promise<ElicitResult>;
 }
 export interface OpenRelayHandlerOptions {
     serverName: string;
     publicUrl: string | null;
+    elicitation?: ElicitationServer;
 }
 /**
  * Build the `open_relay` handler closure. Tests can call
  * ``buildOpenRelayHandler({ serverName, publicUrl })`` directly without
  * needing a real MCP server instance.
+ *
+ * When `elicitation` is supplied AND the client declared URL-mode
+ * elicitation, the handler drives `elicitInput` and returns the accept /
+ * decline / cancel outcome. Otherwise it returns the legacy dict
+ * (`{ url, browserOpened, status }`) unchanged.
  */
 export declare function buildOpenRelayHandler(options: OpenRelayHandlerOptions): () => Promise<OpenRelayResult>;
 /**
@@ -46,12 +70,16 @@ export interface ToolRegistrar {
  *
  * ```ts
  * import { registerOpenRelayTool } from '@n24q02m/mcp-core'
- * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL)
+ * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL, mcp.server)
  * ```
  *
  * Pass ``null`` for ``publicUrl`` when the server is running in stdio mode;
  * the tool will return ``status: 'stdio_unsupported'`` so the caller can
  * surface a clear "switch to HTTP mode" message.
+ *
+ * Pass the low-level `Server` (`mcp.server`) as ``elicitation`` to enable
+ * URL-mode elicitation for capable clients. When omitted, the tool keeps
+ * the legacy browser-open behaviour for every client.
  */
-export declare function registerOpenRelayTool(mcp: ToolRegistrar, serverName: string, publicUrl: string | null): void;
+export declare function registerOpenRelayTool(mcp: ToolRegistrar, serverName: string, publicUrl: string | null, elicitation?: ElicitationServer): void;
 //# sourceMappingURL=tool-helpers.d.ts.map

package/build/relay/tool-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,OAAO,CAAA;IACtB,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,GAAG,gBAAgB,GAAG,mBAAmB,CAAA;CAC3F;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAStG;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;CACxG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAS5G"}
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAGlH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,OAAO,CAAA;IACtB,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,GAAG,gBAAgB,GAAG,mBAAmB,CAAA;IAC1F,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,CAAA;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAA;IAC3D,WAAW,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;CACvE;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,CAAC,EAAE,iBAAiB,CAAA;CAChC;AAaD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAyBtG;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;CACxG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,IAAI,CASN"}

package/build/relay/tool-helpers.js

@@ -3,20 +3,42 @@
  *
  * After the stdio-pure + http-multi-user split, the relay config form is
  * served by the HTTP server itself at ``<PUBLIC_URL>/authorize``. The
- * ``config__open_relay`` tool simply returns that URL and best-effort opens
- * the user's default browser. There is no daemon-bridge discovery, no
- * respawn, and no session deduplication — the HTTP server's own session
- * tracking handles concurrent setup attempts.
+ * ``config__open_relay`` tool directs the user to that URL.
+ *
+ * When the connected client declares URL-mode elicitation
+ * (``capabilities.elicitation.url``, SEP-1036), the tool asks the client to
+ * present a consent prompt and open the URL via ``Server.elicitInput`` so the
+ * credential form is opened out-of-band without the LLM in the loop. Clients
+ * that do NOT declare the capability fall back to the legacy behaviour: the
+ * tool returns the URL and best-effort opens the user's default browser
+ * server-side. There is no daemon-bridge discovery, no respawn, and no
+ * session deduplication — the HTTP server's own session tracking handles
+ * concurrent setup attempts.
  *
  * In stdio mode, the relay form does not exist; the tool returns
  * ``stdio_unsupported`` so plugin code can render a "switch to HTTP mode"
  * message instead of misleading the user with an unreachable URL.
  */
+import { randomUUID } from 'node:crypto';
 import { tryOpenBrowser } from './browser.js';
+// Maps the client's ElicitResult.action to the tool's outcome field.
+const ELICIT_ACTION_MAP = {
+    accept: 'accepted',
+    decline: 'declined',
+    cancel: 'cancelled'
+};
+function clientSupportsUrlElicitation(server) {
+    return server.getClientCapabilities()?.elicitation?.url != null;
+}
 /**
  * Build the `open_relay` handler closure. Tests can call
  * ``buildOpenRelayHandler({ serverName, publicUrl })`` directly without
  * needing a real MCP server instance.
+ *
+ * When `elicitation` is supplied AND the client declared URL-mode
+ * elicitation, the handler drives `elicitInput` and returns the accept /
+ * decline / cancel outcome. Otherwise it returns the legacy dict
+ * (`{ url, browserOpened, status }`) unchanged.
  */
 export function buildOpenRelayHandler(options) {
     return async function openRelay() {
@@ -24,6 +46,22 @@ export function buildOpenRelayHandler(options) {
             return { url: '', browserOpened: false, status: 'stdio_unsupported' };
         }
         const url = `${options.publicUrl.replace(/\/$/, '')}/authorize`;
+        const { elicitation } = options;
+        if (elicitation && clientSupportsUrlElicitation(elicitation)) {
+            const message = `Open the ${options.serverName} configuration page to enter your credentials securely in your browser.`;
+            const result = await elicitation.elicitInput({
+                mode: 'url',
+                message,
+                url,
+                elicitationId: randomUUID()
+            });
+            return {
+                url,
+                browserOpened: false,
+                status: 'unconfigured',
+                elicitation: ELICIT_ACTION_MAP[result.action] ?? 'accepted'
+            };
+        }
         const opened = await tryOpenBrowser(url);
         return { url, browserOpened: !!opened, status: 'unconfigured' };
     };
@@ -36,15 +74,19 @@ export function buildOpenRelayHandler(options) {
  *
  * ```ts
  * import { registerOpenRelayTool } from '@n24q02m/mcp-core'
- * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL)
+ * registerOpenRelayTool(mcp, SERVER_NAME, PUBLIC_URL, mcp.server)
  * ```
  *
  * Pass ``null`` for ``publicUrl`` when the server is running in stdio mode;
  * the tool will return ``status: 'stdio_unsupported'`` so the caller can
  * surface a clear "switch to HTTP mode" message.
+ *
+ * Pass the low-level `Server` (`mcp.server`) as ``elicitation`` to enable
+ * URL-mode elicitation for capable clients. When omitted, the tool keeps
+ * the legacy browser-open behaviour for every client.
  */
-export function registerOpenRelayTool(mcp, serverName, publicUrl) {
-    const handler = buildOpenRelayHandler({ serverName, publicUrl });
+export function registerOpenRelayTool(mcp, serverName, publicUrl, elicitation) {
+    const handler = buildOpenRelayHandler({ serverName, publicUrl, elicitation });
     mcp.tool({
         name: 'config__open_relay',
         description: `Open the relay configuration form for ${serverName} in the user's browser.`

package/build/relay/tool-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAa7C;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,OAAO,KAAK,UAAU,SAAS;QAC7B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAA;QACvE,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAA;QAC/D,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QACxC,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACjE,CAAC,CAAA;AACH,CAAC;AAWD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB,EAAE,UAAkB,EAAE,SAAwB;IACpG,MAAM,OAAO,GAAG,qBAAqB,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAA;IAChE,GAAG,CAAC,IAAI,CACN;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,yCAAyC,UAAU,yBAAyB;KAC1F,EACD,OAAO,CACR,CAAA;AACH,CAAC"}
+{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../src/relay/tool-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAyB7C,qEAAqE;AACrE,MAAM,iBAAiB,GAA0D;IAC/E,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,UAAU;IACnB,MAAM,EAAE,WAAW;CACpB,CAAA;AAED,SAAS,4BAA4B,CAAC,MAAyB;IAC7D,OAAO,MAAM,CAAC,qBAAqB,EAAE,EAAE,WAAW,EAAE,GAAG,IAAI,IAAI,CAAA;AACjE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,OAAO,KAAK,UAAU,SAAS;QAC7B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAA;QACvE,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAA;QAC/D,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAA;QAC/B,IAAI,WAAW,IAAI,4BAA4B,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,YAAY,OAAO,CAAC,UAAU,yEAAyE,CAAA;YACvH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC;gBAC3C,IAAI,EAAE,KAAK;gBACX,OAAO;gBACP,GAAG;gBACH,aAAa,EAAE,UAAU,EAAE;aAC5B,CAAC,CAAA;YACF,OAAO;gBACL,GAAG;gBACH,aAAa,EAAE,KAAK;gBACpB,MAAM,EAAE,cAAc;gBACtB,WAAW,EAAE,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,UAAU;aAC5D,CAAA;QACH,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QACxC,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACjE,CAAC,CAAA;AACH,CAAC;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAkB,EAClB,UAAkB,EAClB,SAAwB,EACxB,WAA+B;IAE/B,MAAM,OAAO,GAAG,qBAAqB,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAA;IAC7E,GAAG,CAAC,IAAI,CACN;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,yCAAyC,UAAU,yBAAyB;KAC1F,EACD,OAAO,CACR,CAAA;AACH,CAAC"}

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@n24q02m/mcp-core",
-  "version": "1.19.0-beta.4",
+  "version": "1.19.0",
   "description": "Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 AS, lifecycle, install",
   "keywords": [
     "mcp",
     "model-context-protocol",
     "streamable-http",
     "oauth21",
-    "transport"
+    "transport",
+    "claude",
+    "cursor",
+    "copilot",
+    "codex",
+    "opencode"
   ],
   "author": {
     "name": "n24q02m",