# MySkillDB Job Categories MCP

MCP server so Claude (Desktop / Code) or Cursor can **push job categories** into a college org through the MySkillDB API.

## Source layout

```
src/
  index.ts                 # stdio entry (Cursor / Claude Desktop)
  http.ts                  # HTTP entry (Claude Connect)
  types/                   # interfaces (config, API, OAuth)
  schemas/                 # Zod schemas for tool inputs
  helpers/                 # env, jwt, string, http, mcp-result
  services/                # MySkillDB API + auth clients
  oauth/                   # login page + in-memory OAuth store
  tools/                   # MCP tool registration
  server/                  # HTTP connector routing
```

Two ways to run it:

| Mode | File | Auth | Best for |
|------|------|------|----------|
| **HTTP connector (recommended)** | `src/http.ts` | Click **Connect** → login page | Claude custom connectors |
| Stdio | `src/index.ts` | JWT + org id in env | Cursor / Claude Desktop |

## Prerequisites

```bash
cd MySkillDb-mcp
npm install
```

MySkillDB API must be running (default `http://localhost:3001`).

## Tools

| Tool | Purpose |
|------|---------|
| `list_job_categories` | List categories for the org |
| `get_job_category` | Fetch one by slug or id |
| `upsert_job_category` | Create or update one category (match by `categoryKey` / `slug`) |
| `push_job_categories` | Batch upsert (up to 50) — best for Claude-authored catalogs |
| `ensure_other_category` | Ensure the catch-all **Other** category exists |
| `delete_job_category` | Delete by id (Other is protected server-side) |

---

## HTTP connector — "Connect" with login

```bash
npm run start:http
# MCP endpoint: http://localhost:3737/mcp
```

In **Claude → Settings → Connectors → Add custom connector**, enter:

```
http://localhost:3737/mcp
```

Click **Connect** — a MySkillDB login page opens. Sign in as **org admin**; tokens refresh automatically. Org is taken from the logged-in user.

> If Claude requires HTTPS, tunnel it:
>
> ```bash
> npx cloudflared tunnel --url http://localhost:3737
> ```
>
> Then restart with `MCP_PUBLIC_URL=https://your-tunnel-domain.trycloudflare.com npm run start:http`.

| Env | Default |
|-----|---------|
| `MYSKILLDB_API_BASE_URL` | `http://localhost:3001/api` |
| `MCP_PORT` | `3737` |
| `MCP_PUBLIC_URL` | `http://localhost:3737` (set when tunneling) |

---

## Stdio mode (Cursor / Claude Desktop)

### 1. Get an access token

```bash
curl -s -X POST http://localhost:3001/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@college.edu","password":"your-password"}'
```

Use `accessToken` and `organizationId` from the response. Role must be `org_admin`, `acc_manager`, or `master_admin`.

### 2. Export secrets in your shell (recommended)

```bash
export MYSKILLDB_ACCESS_TOKEN='...'
export MYSKILLDB_ORGANIZATION_ID='...'
```

Do **not** commit real JWTs.

### 3. Cursor (dynamic paths)

Copy [`mcp.config.example.json`](./mcp.config.example.json) into the **monorepo root** at `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "myskilldb-job-categories": {
      "command": "npm",
      "args": ["start"],
      "cwd": "${workspaceFolder}/MySkillDb-mcp",
      "env": {
        "MYSKILLDB_API_BASE_URL": "http://localhost:3001/api",
        "MYSKILLDB_ACCESS_TOKEN": "${env:MYSKILLDB_ACCESS_TOKEN}",
        "MYSKILLDB_ORGANIZATION_ID": "${env:MYSKILLDB_ORGANIZATION_ID}"
      }
    }
  }
}
```

`${workspaceFolder}` resolves to the project root — no absolute path to edit per machine.

If you open **only** `MySkillDb-mcp` as the workspace, set `"cwd": "${workspaceFolder}"` instead.

### 4. Claude Desktop (absolute path)

Claude Desktop does not support `${workspaceFolder}`. Copy [`mcp.config.claude-desktop.example.json`](./mcp.config.claude-desktop.example.json) into:

`~/Library/Application Support/Claude/claude_desktop_config.json`

Replace `/ABSOLUTE/PATH/TO/SkillDB-og/MySkillDb-mcp` with your real path (and paste JWT/org id, or export them and reference if your host supports it). Restart Claude Desktop.

---

## Example prompt

> Using the MySkillDB job categories MCP, push a Tech category for "Backend Engineering" with slug `backend-engineering`, categoryKey `backend`, about/day-in-life/skills/tools/growth plan suitable for Indian campus placement students. Then list categories to confirm.

## Local smoke test

```bash
export MYSKILLDB_API_BASE_URL=http://localhost:3001/api
export MYSKILLDB_ACCESS_TOKEN=...
export MYSKILLDB_ORGANIZATION_ID=...
npm run inspect
```

## Notes

- MySkillDB server must be running.
- Token must belong to an admin role that can write `/api/job-categories`.
- Never commit real JWTs — use `${env:...}` in Cursor or local-only config.
- stdout is reserved for MCP JSON-RPC; logs go to stderr.