EverOS MCP

everos-mcp is a local, Streamable HTTP MCP adapter for the existing EverOS v2 memory client. It is deliberately a thin adapter: it reuses the workstation's existing everos_v2.bat and its private %USERPROFILE%\\.everos credentials, instead of copying tokens, Cloudflare Access secrets, or transport code into this repository.

This project does not deploy anything, change Cloudflare/DNS, or write to EverOS during its test suite.

Endpoint and tools

The default local endpoint is http://127.0.0.1:8766/mcp.

• memory_status, memory_list_sources, memory_search, and memory_get are published with MCP readOnlyHint: true.

• memory_remember is explicitly a write (readOnlyHint: false). The server write gate is off by default. Even an exact CONFIRM_MEMORY_WRITE is refused with SERVER_WRITE_DISABLED and cannot reach the EverOS client or CLI until EVEROS_MCP_ENABLE_WRITES=true is set in the server process. When that technical gate is explicitly enabled, exact confirmation remains a second defence; it is not evidence that the user just authorized a write. The adapter never exposes the CLI's echoed note body.

• All adapter responses are structured, page/size bounded, text-limited, and passed through the existing EverOS scrubber plus an adapter-level scrubber. Search results preserve status, partial, errors, routing/cache provenance, and session IDs while returning only truncated derived-memory fields.

memory_get uses the same validated EverOS Python client used by its retrieval evaluator for /api/v1/memory/get; the public CLI does not currently expose a get subcommand.

Related MCP server: mnemo

Local setup

From E:\AGENT\Workspace\everos-mcp:

uv sync --extra dev
$env:EVEROS_MCP_APPROVAL_CODE = "choose-a-long-local-code"
.\scripts\run.ps1

run.ps1 binds only to 127.0.0.1 by default and starts OAuth mode. The approval code stays in the process environment; it is never written by this project. OAuth mode starts without an approval code but refuses consent until one is supplied, which is safer for a local unattended start.

For a strictly loopback development smoke test without OAuth, use:

.\scripts\run.ps1 -AuthMode disabled

Writes remain disabled in every normal start. For a deliberately isolated write exercise only, the process owner must set EVEROS_MCP_ENABLE_WRITES=true or pass -EnableWrites; this task does not use either option against production memory. A future ChatGPT remote connection must also register memory_remember as always ask. The fixed confirmation word is only a technical condition, never a proof of the user's current intent.

Authentication may be disabled only on a loopback bind. Non-loopback binds need an explicit EVEROS_MCP_ALLOW_NON_LOOPBACK=1, and a non-loopback public URL must be HTTPS. Those safeguards do not perform any deployment.

OAuth compatibility layer

When OAuth mode is enabled, the MCP Python SDK supplies protected-resource metadata and Streamable HTTP bearer enforcement. The local provider adds:

• OAuth 2.1 authorization-code + S256 PKCE flow;

• Dynamic Client Registration defaults an omitted authentication method to none, matching ChatGPT's public PKCE flow rather than the MCP SDK's current client_secret_post default. The current ChatGPT Business connector is also normalized to none when it explicitly requests client_secret_post or client_secret_basic but then performs a public PKCE exchange. Explicit confidential PKCE metadata from other clients remains supported, with client secrets persisted only inside the DPAPI-encrypted state store;

• mcp and offline_access scopes;

• one-time authorization codes and rotated, replay-protected refresh tokens;

• an owner approval page protected by the local approval code. Successful consent is retryable for the short pending-request lifetime: duplicate clicks return the same PKCE-protected callback using HTTP 303, and revisiting the page shows an explicit Continue to ChatGPT link instead of invalidating the request;

• RFC 8707 resource normalization (case/default-port/trailing-slash handling);

• both the current resource-specific metadata path /.well-known/oauth-protected-resource/mcp and a root metadata alias for older ChatGPT-compatible discovery clients;

• DNS-rebinding protection that explicitly allows the configured public MCP hostname plus the loopback listener, so authenticated requests forwarded by the Cloudflare tunnel are not rejected with HTTP 421.

The SDK publishes standard fallback routes at /authorize, /token, and /register, advertised in authorization-server metadata. /.well-known metadata advertises the resource as the exact /mcp URL.

Verification

The test suite uses a substitute EverOS client only. It covers read-only tool annotations, default write refusal, redaction/length bounds, DCR, PKCE, offline_access, refresh-token rotation/replay rejection, resource normalization, metadata discovery, and initialize / tools/list / tools/call over Streamable HTTP.

.\.venv\Scripts\ruff.exe check src tests
.\.venv\Scripts\pytest.exe

For a real, read-only local smoke test, start the server in loopback development mode and call only memory_status, memory_list_sources, and memory_search. Do not call memory_remember; its write path is intentionally not part of the smoke test.

Remote deployment candidate (not deployed by this project)

OAuth registrations, pending approvals, authorization codes, and access/refresh tokens persist in %LOCALAPPDATA%\EverOS-MCP\oauth-state.sqlite3. Each payload is protected with the Windows user's DPAPI profile before SQLite writes it; database keys are SHA-256 digests. SQLite WAL plus immediate transactions makes authorization-code consumption and refresh rotation atomic across restarts. A damaged or unreadable encrypted record fails closed; do not copy it between Windows user profiles.

Bounded fixed-window limits are DCR 20/minute, authorize/consent 30/minute, token 60/minute, and MCP 120/minute per hashed source address. Rejections use RATE_LIMITED (MCP is HTTP 429 with Retry-After). Audit records only time, event, result, hashed client/address, and error code: never query text, memory, Authorization, Cookie, tokens, approval codes, or Cloudflare secrets.

.\scripts\manage.ps1 -Action start -PublicBaseUrl https://everos-mcp.biaobiao.store
.\scripts\manage.ps1 -Action status
.\scripts\manage.ps1 -Action stop

This candidate always binds loopback and starts with writes disabled; it neither registers a service nor startup task. A future Cloudflare Tunnel may provide public HTTPS and Access policy, but MCP clients must still complete OAuth: do not assume ChatGPT can carry Cloudflare service-token headers. Compatible layers are public HTTPS Tunnel -> optional Access policy permitting OAuth -> this OAuth/PKCE provider -> loopback MCP process. No Tunnel, DNS, Access app, or credentials are created here.

Minimal current-user scheduled runner

The managed runner uses a local approval-code file, never a task argument:

.\scripts\user-task.ps1 -Action install
.\scripts\user-task.ps1 -Action status
.\scripts\user-task.ps1 -Action rotate   # restart task afterwards
.\scripts\user-task.ps1 -Action copy-approval  # Windows clipboard only
.\scripts\user-task.ps1 -Action restart
.\scripts\user-task.ps1 -Action uninstall

install creates at least 32 cryptographically random bytes, Base64-encodes them, and atomically writes %LOCALAPPDATA%\EverOS-MCP\approval-code.txt with ACL access limited to the current user and SYSTEM only when that file is missing. A valid existing file is retained, so a task update does not invalidate an already-connected client; use the explicit rotate action when invalidation is intentional. The scheduled action calls only run-managed.ps1 with no secret arguments. The runner reads the file into its child process environment only, forces EVEROS_MCP_ENABLE_WRITES=false, 127.0.0.1:8766, OAuth, and the fixed HTTPS public base URL, then runs in the foreground. It does not print the code. Registration uses the standard current-user Task Scheduler API with no elevation; if that cannot be done safely it fails without trying to broaden permissions. uninstall leaves the approval file in place for deliberate operator cleanup.

The task is explicitly bound to the current Windows identity for both its limited-run-level principal and logon trigger. It retries only three times with a one-minute interval, has no execution-time cutoff for the long-lived runner, and ignores overlapping starts; it never uses highest privileges or a rapid, unbounded restart loop. It starts wscript.exe //B //NoLogo, which uses the reviewed run-managed-hidden.vbs wrapper to launch PowerShell with window style 0, so the normal logon runner does not leave a terminal window on the desktop.

The start, stop, and restart actions manage only the exact loopback listener chain ending at this project's everos-mcp.exe, with an expected run-managed.ps1 parent. They revalidate creation time and command line before terminating any PID, never terminate the PowerShell parent, and refuse unknown or multiple listeners rather than broadening ownership.

copy-approval first verifies that the existing approval-code file is present and still has the private current-user/SYSTEM ACL contract. It then writes only to the Windows clipboard and never prints the code, creates another file, rotates the approval code, or restarts the task. An absent or unsafe file fails before any clipboard write.

For a non-persistent validation of the script paths:

.\scripts\test-user-task.ps1

Known limits before any remote rollout

Before a future remote rollout, decide Cloudflare Access/owner identity, state retention and consent-code rotation, then complete an independent security review. The suggested hostname is everos-mcp.biaobiao.store; no public listener, Tunnel, Access application, DNS record, or production EverOS write has been created by this task.

Project layout

• src/everos_mcp/everos_client.py — safe CLI/client adapter and response bounds.

• src/everos_mcp/oauth.py — local DCR/PKCE/consent/token compatibility provider.

• src/everos_mcp/server.py — MCP tools, Streamable HTTP app, and metadata aliases.

• tests/ — isolated unit and HTTP contract tests.

• DESIGN.md — durable visual/security contract for the small consent page.

• scripts/run-managed.ps1 — foreground fixed-configuration runner; reads the approval code only from the restricted local file.

• scripts/user-task.ps1 — optional current-user scheduled-task lifecycle.