# AetherDesk MCP

AetherDesk exposes the local ecosystem library as a Model Context Protocol server.

For the full local MCP list, including the SCBE verification MCP, see `C:\Users\issda\AetherDesk\docs\MCP_REGISTRY.md`.

For ChatGPT/custom connector or hosted HTTP usage, see `C:\Users\issda\AetherDesk\docs\AETHERDESK_CONNECTOR.md`.

## Launch

For AetherDesk as an AI-PC tool/plugin surface, use:

```powershell
cd C:\Users\issda\AetherDesk
npm run mcp:aetherdesk
```

MCP clients should launch:

```json
{
  "mcpServers": {
    "aetherdesk-plugin-plus": {
      "command": "node",
      "args": ["C:\\Users\\issda\\AetherDesk\\scripts\\aetherdesk-tool-mcp.js"],
      "cwd": "C:\\Users\\issda\\AetherDesk",
      "env": {
        "AETHERDESK_CONNECTOR_BASE_URL": "http://127.0.0.1:5717",
        "AETHERDESK_PORT": "5717"
      }
    }
  }
}
```

Build the ready-to-copy plugin pack with:

```powershell
npm run aetherdesk:package:plugin
```

The generated pack lives at:

```text
C:\Users\issda\AetherDesk\dist\aetherdesk-plugin-plus
```

For the older ecosystem-library-only stdio server, use:

```powershell
cd C:\Users\issda\AetherDesk
npm run mcp:ecosystem
```

MCP clients should launch:

```json
{
  "mcpServers": {
    "aetherdesk-ecosystem": {
      "command": "node",
      "args": ["C:\\Users\\issda\\AetherDesk\\scripts\\aetherdesk-mcp.js"]
    }
  }
}
```

## HTTP Connector

The React/desktop server also exposes an HTTP JSON-RPC MCP endpoint:

```text
http://127.0.0.1:5717/mcp
```

Smoke-test it with:

```powershell
npm run connector:smoke
```

For ChatGPT or other cloud LLM services, expose `/mcp` over HTTPS through a
deliberate tunnel or deployment. Local `127.0.0.1` is only reachable from the
same machine.

For hosted usage, enable token auth (lightweight) by setting:

```powershell
$env:AETHERDESK_CONNECTOR_AUTH_MODE = "token"
$env:AETHERDESK_CONNECTOR_AUTH_TOKEN = "<token>"
```

Then configure your client/request path with `Authorization: Bearer <token>`.

To verify onboarding before you hand this to a model client, run:

```powershell
npm run connector:onboard -- --base https://<your-host> --json
```

Required pre-flight checklist:

- Run `npm run connector:onboard -- --base <endpoint> --json` and confirm:
  - `checks.mcp_ok` is `true`
  - `checks.connector_ok` is `true`
  - (public endpoint) `mode` is `token` and `bearer_header` is shown
- If the report is not green, keep the endpoint local/disconnected until checks pass.

## Tools

- `aetherdesk_local_status` - check whether the local AetherDesk server and connector are reachable.
- `aetherdesk_start_local` - start the local AetherDesk server for agents that only have the plugin attached.
- `aetherdesk_open_desktop_url` - open the local desktop URL in the default browser.
- `aetherdesk_ai_desktop` - read the dense robotext fast face before visual inspection.
- `aetherdesk_tool_view_plane` - read every registered desktop tool/app, including closed virtual views.
- `aetherdesk_control_surfaces` - read the shared visual/programmatic control contract.
- `aetherdesk_control_snapshot` - read the current desktop/control snapshot.
- `aetherdesk_open_app` - open or focus one registered AetherDesk app through the desktop action gate.
- `aetherdesk_shell_profiles` - list bounded shell profiles without exposing raw command text.
- `ecosystem_search` - search `AETHER_ECOSYSTEM_INDEX.csv` by tag, name, purpose, path, category, or authority.
- `ecosystem_get_entry` - return one exact entry by name or path.
- `ecosystem_list_categories` - list library categories and counts.
- `ecosystem_library_excerpt` - return a bounded excerpt from `AETHER_ECOSYSTEM_LIBRARY.md`.
- `ecosystem_path_status` - check whether a mapped path exists.
- `prime_grid_generate` - generate bounded prime-family tables with Fermat-65537 coordinates and optical transition telemetry.
- `prime_grid_classify` - classify one integer into prime-family tags plus optical depth/mode/score.
- `proton_status` - check which Proton CLIs are available and return the secret-safe Proton boundary.
- `proton_pass_reference` - return Proton Pass CLI URI/template/SSH-agent patterns without resolving secret values.
- `proton_drive_reference` - return Proton Drive CLI automation patterns.
- `proton_vpn_reference` - return Proton VPN CLI capability and network-mutation boundary notes.
- `aetherdesk_web_audit` - inspect a public web page for title, headings, controls, console/request errors, and mobile overflow.
- `aetherdesk_revenue_meter` - summarize terminal/API receipts into billable usage, API-cost reserve, estimated net, and offer tier.

## Source Files

- `C:\Users\issda\AETHER_ECOSYSTEM_INDEX.csv`
- `C:\Users\issda\AETHER_ECOSYSTEM_LIBRARY.md`

Override with:

```powershell
$env:AETHERDESK_ECOSYSTEM_INDEX = "C:\path\to\index.csv"
$env:AETHERDESK_ECOSYSTEM_LIBRARY = "C:\path\to\library.md"
```
