# binusmaya-mcp

Remote Streamable HTTP MCP server for the operator's own BINUSMAYA account. It runs on a Linux VPS so tools stay up when the laptop is off.

## Overview

MCP clients call `https://<host>/mcp` with `Authorization: Bearer <MCP_ACCESS_TOKEN>`. Node listens on `127.0.0.1:3000`. Tailscale Serve (default) or Caddy/nginx terminates TLS. BINUS session files live on the VPS disk, not in env.

## Features

- Streamable HTTP MCP (`@modelcontextprotocol/server` v2) plus optional stdio for Inspector
- Static MCP bearer (SHA-256 + `timingSafeEqual`)
- Playwright `storageState` login via loopback noVNC (you complete Microsoft/MFA)
- Read-only tools; unverified BINUS endpoints return `NOT_IMPLEMENTED`
- systemd unit `binusmaya-mcp` with restart on crash and reboot

## Architecture

See [docs/architecture.md](docs/architecture.md).

## Requirements

- Node.js >= 20
- pnpm 10.x (`corepack prepare pnpm@10.17.1 --activate`)
- TypeScript build: `pnpm build`

## Server Requirements

- Debian/Ubuntu (portable to other Linux)
- 2 GB RAM minimum (4 GB recommended), 2 vCPU, 20 GB disk
- Packages for login UI: `xvfb`, `x11vnc`, `novnc`
- Playwright Chromium: `pnpm exec playwright install --with-deps chromium`
- Tailscale (OPTION A) or a DNS name + Caddy/nginx (OPTION B)

## Installation

Laptop (dev):

```
corepack enable
corepack prepare pnpm@10.17.1 --activate
pnpm install
cp .env.example .env
pnpm token:generate
# put the hex into MCP_ACCESS_TOKEN for HTTP
pnpm typecheck
pnpm test
pnpm build
```

VPS: see [docs/deployment.md](docs/deployment.md).

## Authentication

Two layers: MCP bearer for clients, Playwright storageState for BINUS. See [docs/authentication.md](docs/authentication.md). Never put `BINUS_PASSWORD` in env.

## Remote MCP

```
MCP_ACCESS_TOKEN=$(pnpm token:generate) HOST=127.0.0.1 PORT=3456 node dist/http.js
```

Stderr banner: `binusmaya-mcp http 127.0.0.1:3456`

```
curl -s localhost:3456/health
# {"status":"ok","service":"binusmaya-mcp"}
```

## Tailscale Setup

```
sudo tailscale serve --bg http://127.0.0.1:3000
```

Set `MCP_ALLOWED_HOSTS` to the MagicDNS hostname plus localhost. Do not use `tailscale funnel`.

## HTTPS Setup

OPTION B: [deployment/caddy/Caddyfile.example](deployment/caddy/Caddyfile.example) or [deployment/nginx/nginx.conf.example](deployment/nginx/nginx.conf.example). Node stays on loopback.

## Available Tools

See [docs/tools.md](docs/tools.md). Twelve read-only `binus_*` tools.

## MCP Client Configuration

Claude Code:

```
claude mcp add --transport http binusmaya https://<host>/mcp \
  --header "Authorization: Bearer <MCP_ACCESS_TOKEN>"
```

JSON (must include `"type": "http"`):

```json
{
  "mcpServers": {
    "binusmaya": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_ACCESS_TOKEN>"
      }
    }
  }
}
```

## Updating

```
git pull
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
sudo systemctl restart binusmaya-mcp
```

Do not delete `.runtime/auth`.

## Testing

```
pnpm typecheck
pnpm test
pnpm build
```

No live BINUS. No production token in git.

## Security

[docs/security.md](docs/security.md). Own account only. No MFA bypass, no endpoint fuzzing, no public bind of Node.

## Troubleshooting

[docs/troubleshooting.md](docs/troubleshooting.md). `pnpm doctor` on the server.

## Reauthentication

When tools return `BINUS_SESSION_EXPIRED` or `BINUS_AUTH_REQUIRED`:

```
pnpm auth
```

SSH tunnel port 6080, log in yourself, press Enter, then `pnpm doctor`.

## Limitations

- Production is Streamable HTTP on the VPS. stdio-only clients cannot use it without a local HTTP-capable host; v1 has no stdio proxy.
- BINUS URLs are not shipped. Until `pnpm inspect-session` fills the catalog, tools return `NOT_IMPLEMENTED`.
- No write tools (submit assignment, forum reply).
- Operator must complete Microsoft/BINUS login on the VPS noVNC session.
# binus-mcp