# 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.

## Local setup

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

```powershell
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:

```powershell
.\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.

```powershell
.\.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.

```powershell
.\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:

```powershell
.\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:

```powershell
.\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.