# MEGA MCP Server

Independent Model Context Protocol server for MEGA Hub. It exposes one stable
surface across Cloudflare Worker, local Streamable HTTP, and stdio transports:

- `docs` searches current official MEGA guidance.
- `search` resolves live OpenAPI operations.
- `execute` calls one documented Hub operation within the caller's OAuth scopes.

Domain workflows live in Codex Skills. Large transfers, repository sync, Git,
streaming logs, interactive shells, and reproducible automation belong in the
`mega` CLI. MCP and CLI are parallel clients of the same Hub API; neither wraps
or depends on the other.

## Hosted MCP

The official OAuth endpoint is:

```text
https://mega.tensorplay.cn/mcp
```

It supports Streamable HTTP, OAuth 2.1 discovery, Dynamic Client Registration,
PKCE, and direct bearer tokens for clients that manage their own credentials.

## Related public projects

- [MEGA Codex plugin](https://github.com/ohtensorplay/mega-codex-plugin): the
  public Codex marketplace and OpenAI submission materials.
- [MEGA Agent Skills](https://github.com/ohtensorplay/mega-skills): eight
  standalone Skills installable with the npm-hosted `skills` CLI.

The MCP server, plugin, and Skills use independent repositories and release
versions. The plugin pins a tested snapshot of the standalone Skills.

## Authorization model

MEGA Hub remains the policy and data owner. Every `execute` request forwards the
caller's token to Hub, which enforces scopes, resource ownership, organization
policy, budgets, and billing.

The protected-resource document advertises these optional scopes:

- `repo:read`
- `repo:write`
- `repo:delete`
- `community:write`
- `jobs:run`
- `inference:run`
- `account:keys`
- `webhooks:manage`

The initial OAuth challenge requests only `repo:read`. MEGA settings and the
actual authorization page share server-backed Read, Write, Full, and Custom
preferences. Inference remains available but is never enabled by default.

Tool availability is not authorization: all three tools are always visible,
and the granted token scopes determine which API operations can succeed.

Legacy `tools`, `bouquet`, `mix`, and `spaces` URL parameters are rejected.
There are no compatibility aliases for the removed domain-specific tools.

## Execute safety boundary

`execute` accepts a structured method, `/api/` path, query object, and optional
JSON body. It:

- fixes the destination to the configured MEGA Hub origin;
- rejects unsafe paths, embedded query strings, and encoded separators;
- permits only operations present in the live OpenAPI document;
- limits request and response bodies to 1 MB;
- returns status, request ID, location, content type, and parsed response data.

Use the CLI for larger payloads or streaming output.

## Deployment modes

| Mode | Entry point | Intended use |
| --- | --- | --- |
| Cloudflare Worker | `src/worker.ts` | Hosted Streamable HTTP service |
| Local stdio | `mega-mcp-server` | Local agents and development |
| Local HTTP | `mega-mcp-server-http` | Self-hosting and integration tests |
| Container | `Dockerfile` | Portable stateless HTTP deployment |

No Durable Object is required. Streamable HTTP uses stateless JSON responses
and creates one MCP server per request.

## Local stdio

Requires Node.js 22 or newer.

```bash
DEFAULT_MEGA_TOKEN=mega_xxx \
npx -y @tensorplay/mega-mcp-server
```

```json
{
  "mcpServers": {
    "mega": {
      "command": "npx",
      "args": ["-y", "@tensorplay/mega-mcp-server"],
      "env": {
        "DEFAULT_MEGA_TOKEN": "${MEGA_TOKEN}"
      }
    }
  }
}
```

## Local HTTP

```bash
npm exec --yes --package=@tensorplay/mega-mcp-server -- mega-mcp-server-http
```

The endpoint is `http://127.0.0.1:3000/mcp`; health checks use `/healthz`, and
protected-resource metadata is available at
`/.well-known/oauth-protected-resource/mcp`.

```bash
codex mcp add mega-local \
  --url http://127.0.0.1:3000/mcp \
  --bearer-token-env-var MEGA_TOKEN
```

`DEFAULT_MEGA_TOKEN` is a local-development fallback and must not be configured
on a shared server.

## Docker

```bash
docker build -t mega-mcp-server .
docker run --rm -p 3000:3000 mega-mcp-server
```

The runtime image is unprivileged and includes a `/healthz` health check.

## OAuth discovery

1. An unauthenticated MCP request returns `401` with `resource_metadata` and a
   read-only default scope request.
2. Protected-resource metadata identifies MEGA Hub and every supported scope.
3. Hub publishes OAuth/OIDC discovery metadata.
4. The authorization screen initializes from the saved permission preference
   and lets the user narrow the current grant before approval.

Direct bearer tokens remain supported for local clients and automation.

## Configuration

| Variable | Default | Applies to | Purpose |
| --- | --- | --- | --- |
| `MEGA_API_BASE_URL` | `https://mega.tensorplay.cn` | All | Optional MEGA Hub API override |
| `MEGA_API_TIMEOUT_MS` | `12500` | All | Per-request Hub timeout |
| `MCP_PUBLIC_URL` | Request origin | Worker | Canonical protected-resource URL |
| `DEFAULT_MEGA_TOKEN` | unset | Local only | stdio token or local HTTP fallback |
| `HOST` | `0.0.0.0` | Local HTTP | Listen address |
| `PORT` | `3000` | Local HTTP | Listen port |

Only HTTPS Hub overrides are accepted outside localhost development.

## Worker deployment

`wrangler.jsonc` is a provider-neutral public template. For a real deployment,
copy it to an untracked environment-specific configuration and supply routes
and optional Hub overrides or service bindings there.

```bash
npm ci
npm run check
npx wrangler deploy --config /path/to/private-wrangler.jsonc
```

The optional `HUB` service binding avoids a public network hop. The optional
`METRICS` binding records method, tool, status, duration, and count only; it
never records tokens, arguments, file contents, or results.

## Development

```bash
npm ci
npm run typecheck
npm test
npm run deploy:dry-run
```

Security reports follow [SECURITY.md](SECURITY.md). Contribution and release
expectations are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT