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.

Related MCP server: IIT Roorkee Academics MCP

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.

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.

Authentication

Two layers: MCP bearer for clients, Playwright storageState for BINUS. See 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 or deployment/nginx/nginx.conf.example. Node stays on loopback.

Available Tools

See 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"):

{
  "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. Own account only. No MFA bypass, no endpoint fuzzing, no public bind of Node.

Troubleshooting

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