@joinquest/mcp-integration 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# JoinQuest integration MCP server
+
+stdio MCP server for **game developers** integrating with JoinQuest. Exposes developer dashboard operations to Cursor, Claude, and other agents via the same GraphQL API as the portal.
+
+## Quick setup
+
+1. Sign in at [JoinQuest](https://joinquest.cc) and open your **developer dashboard**.
+2. **Connect an AI assistant** → **Show setup** → **Generate API key** (copy once).
+3. Add MCP config (Node.js 20+, uses `npx` — no install step):
+
+**Cursor** — `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "joinquest-integration": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@joinquest/mcp-integration", "joinquest-integration-mcp-cursor"],
+      "env": {
+        "JOINQUEST_API_KEY": "lq_dev_..."
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add --scope project --transport stdio \
+  --env JOINQUEST_API_KEY=lq_dev_... \
+  joinquest-integration -- npx -y @joinquest/mcp-integration
+```
+
+**Other stdio clients** — use `npx` with args `["-y", "@joinquest/mcp-integration"]` and the same `env`.
+
+4. Fully quit and reopen your agent client. Test: ask the agent to call `joinquest_integration_list_my_games`.
+
+### Why a separate Cursor bin?
+
+Cursor injects `ELECTRON_RUN_AS_NODE` into MCP child processes. Use the second npx arg `joinquest-integration-mcp-cursor` (wrapper that unsets it). Other clients use the default bin.
+
+### Optional global install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/scruffyprodigy/playhub/main/scripts/install-joinquest-mcp.sh | sh
+```
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JOINQUEST_API_KEY` | Yes* | From developer dashboard → Connect AI assistant |
+| `JOINQUEST_ISSUER_URL` | No | Lobby JWT issuer / provision `lobbyId` |
+| `JOINQUEST_PUBLIC_URL` | No | Browser Lobby URL for example provision payloads |
+| `JOINQUEST_SESSION` | Legacy | Session cookie (prefer API key) |
+
+Advanced (lobby contributors): `JOINQUEST_API_URL=http://localhost:8080/graphql` — see [docs/development.md](../../docs/development.md).
+
+## Publishing
+
+Maintainers: `./scripts/publish-joinquest-mcp.sh` (requires npm login + `@joinquest` scope). Roadmap: [docs/developer-ai-setup-roadmap.md](../../docs/developer-ai-setup-roadmap.md).
+
+## Client config paths
+
+| Client | Config file |
+|--------|-------------|
+| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Code | `.mcp.json` at project root |
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `joinquest_integration_get_agent_playbook` | **Start here** — end-to-end agent workflow (phases 1–8) |
+| `joinquest_integration_get_integration_guide` | Full integration guide (markdown) |
+| `joinquest_integration_get_discovery_prompt` | Agent interview script |
+| `joinquest_integration_get_catalog_tag_taxonomy` | Valid tag IDs |
+| `joinquest_integration_list_my_games` | Owner's games + visibility |
+| `joinquest_integration_get_game_checks` | Checklist + metadata |
+| `joinquest_integration_run_game_checks` | Run manifest / provision / JWT suite |
+| `joinquest_integration_update_game_metadata` | Save catalog copy + tags |
+| `joinquest_integration_get_game_credentials` | serviceToken + webhook secret |
+| `joinquest_integration_get_example_provision_payload` | Sample provision JSON |
+| `joinquest_integration_request_public_release` | Submit for catalog review |
+
+## Run from repo
+
+```bash
+cd mcp/joinquest-integration
+npm install
+JOINQUEST_API_KEY=your-key node src/index.js
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+## Publishing (maintainers)
+
+From repo root (requires `@joinquest` scope access + npm 2FA):
+
+```bash
+NPM_OTP=123456 ./scripts/publish-joinquest-mcp.sh
+```
+
+Use a code from your authenticator app when prompted. For GitHub Actions, add a **granular access token** with **Publish** on `@joinquest/*` and **bypass 2FA** enabled as `NPM_TOKEN`.

package/bin/joinquest-integration-mcp-cursor

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Cursor injects ELECTRON_RUN_AS_NODE and a bundled node on PATH, which breaks stdio MCP.
+set -eu
+
+unset ELECTRON_RUN_AS_NODE
+export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:${PATH:-}"
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+NODE="${JOINQUEST_NODE:-$(command -v node)}"
+
+exec "$NODE" "$DIR/../src/index.js"

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@joinquest/mcp-integration",
+  "version": "0.1.0",
+  "description": "JoinQuest integration MCP server for game developer agents",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "keywords": [
+    "joinquest",
+    "mcp",
+    "model-context-protocol",
+    "game-development",
+    "integration"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scruffyprodigy/playhub.git",
+    "directory": "mcp/joinquest-integration"
+  },
+  "bugs": {
+    "url": "https://github.com/scruffyprodigy/playhub/issues"
+  },
+  "homepage": "https://joinquest.cc/developers",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "joinquest-integration-mcp": "src/index.js",
+    "joinquest-integration-mcp-cursor": "bin/joinquest-integration-mcp-cursor"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  }
+}

package/src/config.js

@@ -0,0 +1,21 @@
+export const DEFAULT_JOINQUEST_API_URL = 'https://joinquest.cc/graphql'
+
+export function loadConfig() {
+  const apiUrl = (process.env.JOINQUEST_API_URL || DEFAULT_JOINQUEST_API_URL).trim()
+  const apiKey = (process.env.JOINQUEST_API_KEY || '').trim()
+  const session = (process.env.JOINQUEST_SESSION || process.env.JOINQUEST_SESSION_COOKIE || '').trim()
+  const cookieName = (process.env.JOINQUEST_SESSION_COOKIE_NAME || 'lobby_session').trim()
+
+  if (apiKey) {
+    return { apiUrl, authHeader: `Bearer ${apiKey}` }
+  }
+
+  if (session) {
+    const cookieValue = session.includes('=') ? session : `${cookieName}=${session}`
+    return { apiUrl, cookieValue }
+  }
+
+  throw new Error(
+    'JOINQUEST_API_KEY is required. Generate one on your developer dashboard (Connect AI assistant), then set JOINQUEST_API_KEY in the MCP server env.',
+  )
+}

package/src/example-provision.js

@@ -0,0 +1,36 @@
+const CHECK_USER_ONE = 'a0000000-0000-4000-8000-000000000001'
+const CHECK_USER_TWO = 'a0000000-0000-4000-8000-000000000002'
+
+export function buildExampleProvisionPayload({ game, credentials, lobbyIssuer, lobbyReturnUrl, lobbyGraphqlUrl }) {
+  const mode = game?.modes?.[0]
+  if (!mode) {
+    throw new Error('Game has no synced modes — connect API and sync manifest first.')
+  }
+
+  const seats = mode.seats ?? []
+  const seatCount = Math.min(2, seats.length)
+  if (seatCount === 0) {
+    throw new Error('Game mode has no expanded seats.')
+  }
+
+  const externalMatchId = 'example-match-' + game.id.slice(0, 8)
+  const assignmentSeats = seats.slice(0, seatCount).map((seat, index) => ({
+    seatKey: seat.seatKey,
+    lobbyUserId: index === 0 ? CHECK_USER_ONE : CHECK_USER_TWO,
+    displayName: index === 0 ? 'Player One' : 'Player Two',
+  }))
+
+  return {
+    lobbyId: lobbyIssuer,
+    lobby: {
+      returnUrl: lobbyReturnUrl,
+      graphqlUrl: lobbyGraphqlUrl,
+      serviceToken: credentials.serviceToken,
+    },
+    assignment: {
+      externalMatchId,
+      gameMode: mode.modeKey,
+      seats: assignmentSeats,
+    },
+  }
+}

package/src/graphql.js

@@ -0,0 +1,146 @@
+export async function graphqlRequest(apiUrl, auth, query, variables = {}) {
+  const headers = {
+    'Content-Type': 'application/json',
+  }
+  if (auth.authHeader) {
+    headers.Authorization = auth.authHeader
+  } else if (auth.cookieValue) {
+    headers.Cookie = auth.cookieValue
+  }
+
+  const response = await fetch(apiUrl, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ query, variables }),
+  })
+
+  let payload
+  try {
+    payload = await response.json()
+  } catch {
+    throw new Error(`JoinQuest API returned non-JSON (${response.status})`)
+  }
+
+  if (!response.ok) {
+    const detail = payload.errors?.[0]?.message || payload.error || response.statusText
+    throw new Error(detail || `API request failed (${response.status})`)
+  }
+
+  if (payload.errors?.length) {
+    throw new Error(payload.errors[0]?.message || 'GraphQL request failed')
+  }
+
+  return payload.data
+}
+
+export const QUERIES = {
+  agentPlaybook: `
+    query DeveloperAgentPlaybook {
+      developerAgentPlaybook
+    }
+  `,
+  integrationGuide: `
+    query DeveloperIntegrationGuide {
+      developerIntegrationGuide
+    }
+  `,
+  discoveryPrompt: `
+    query DeveloperDiscoveryPrompt {
+      developerDiscoveryPrompt
+    }
+  `,
+  catalogTagTaxonomy: `
+    query CatalogTagTaxonomy {
+      catalogTagTaxonomy {
+        id
+        label
+        description
+      }
+    }
+  `,
+  myGames: `
+    query MyGames {
+      myGames {
+        id
+        slug
+        name
+        shortDescription
+        visibility
+        apiBaseUrl
+      }
+    }
+  `,
+  myGame: `
+    query MyGame($id: ID!) {
+      myGame(id: $id) {
+        id
+        slug
+        name
+        shortDescription
+        longDescription
+        howToPlay
+        tags
+        visibility
+        apiBaseUrl
+        integrationChecks {
+          checkId
+          status
+          message
+          detail
+          ranAt
+        }
+        modes {
+          modeKey
+          displayName
+          minPlayers
+          maxPlayers
+          seats {
+            seatKey
+            queuePath
+          }
+        }
+      }
+    }
+  `,
+  myGameCredentials: `
+    query MyGameCredentials($id: ID!) {
+      myGameCredentials(id: $id) {
+        serviceToken
+        webhookSecret
+      }
+    }
+  `,
+}
+
+export const MUTATIONS = {
+  runMyGameChecks: `
+    mutation RunMyGameChecks($gameId: ID!) {
+      runMyGameChecks(gameId: $gameId) {
+        checkId
+        status
+        message
+        detail
+        ranAt
+      }
+    }
+  `,
+  updateMyGameMetadata: `
+    mutation UpdateMyGameMetadata($input: UpdateMyGameMetadataInput!) {
+      updateMyGameMetadata(input: $input) {
+        id
+        shortDescription
+        longDescription
+        howToPlay
+        tags
+      }
+    }
+  `,
+  requestPublicRelease: `
+    mutation RequestPublicRelease($gameId: ID!) {
+      requestPublicRelease(gameId: $gameId) {
+        id
+        visibility
+      }
+    }
+  `,
+}

package/src/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { loadConfig } from './config.js'
+import { registerJoinQuestIntegrationTools } from './tools.js'
+
+async function main() {
+  const config = loadConfig()
+  const server = new McpServer({
+    name: 'joinquest-integration',
+    version: '0.1.0',
+  })
+
+  registerJoinQuestIntegrationTools(server, config)
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  console.error('JoinQuest integration MCP server running (stdio)')
+}
+
+main().catch((error) => {
+  console.error('JoinQuest integration MCP fatal error:', error.message)
+  process.exit(1)
+})

package/src/tools.js

@@ -0,0 +1,206 @@
+import { z } from 'zod'
+import {
+  MUTATIONS,
+  QUERIES,
+  graphqlRequest,
+} from './graphql.js'
+import { buildExampleProvisionPayload } from './example-provision.js'
+
+function textResult(value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+  return { content: [{ type: 'text', text }] }
+}
+
+function lobbyUrls(apiUrl) {
+  const origin = apiUrl.replace(/\/graphql\/?$/, '')
+  const issuer = (process.env.JOINQUEST_ISSUER_URL || origin).replace(/\/$/, '')
+  let publicUrl = process.env.JOINQUEST_PUBLIC_URL || origin
+  if (origin.includes('localhost:8080') && !process.env.JOINQUEST_PUBLIC_URL) {
+    publicUrl = 'http://localhost:5173'
+  }
+  publicUrl = publicUrl.replace(/\/$/, '')
+  return {
+    lobbyIssuer: issuer,
+    lobbyReturnUrl: `${publicUrl}/return`,
+    lobbyGraphqlUrl: `${issuer}/graphql`,
+  }
+}
+
+export function registerJoinQuestIntegrationTools(server, config) {
+  const { apiUrl, authHeader, cookieValue } = config
+  const auth = authHeader ? { authHeader } : { cookieValue }
+  const gql = (query, variables) => graphqlRequest(apiUrl, auth, query, variables)
+
+  server.registerTool(
+    'joinquest_integration_get_agent_playbook',
+    {
+      description:
+        'Returns the end-to-end agent workflow for integrating a game with JoinQuest (phases 1–8: discovery, MCP setup, API implementation, registration, checks, metadata, test, release). Start here for vibe-coding integrations.',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const data = await gql(QUERIES.agentPlaybook)
+      return textResult(data.developerAgentPlaybook)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_integration_guide',
+    {
+      description: 'Returns the full JoinQuest developer integration guide (markdown).',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const data = await gql(QUERIES.integrationGuide)
+      return textResult(data.developerIntegrationGuide)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_discovery_prompt',
+    {
+      description: 'Returns the agent discovery interview script for understanding a game before drafting catalog copy or seatTemplate guidance.',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const data = await gql(QUERIES.discoveryPrompt)
+      return textResult(data.developerDiscoveryPrompt)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_catalog_tag_taxonomy',
+    {
+      description: 'Returns valid catalog tag IDs and labels for updateMyGameMetadata.',
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const data = await gql(QUERIES.catalogTagTaxonomy)
+      return textResult(data.catalogTagTaxonomy)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_list_my_games',
+    {
+      description: "List games owned by the signed-in developer, including visibility state.",
+      inputSchema: z.object({}),
+    },
+    async () => {
+      const data = await gql(QUERIES.myGames)
+      return textResult(data.myGames ?? [])
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_game_checks',
+    {
+      description: 'Fetch latest integration checklist results and catalog metadata for one owned game.',
+      inputSchema: z.object({
+        gameId: z.string().describe('JoinQuest game UUID'),
+      }),
+    },
+    async ({ gameId }) => {
+      const data = await gql(QUERIES.myGame, { id: gameId })
+      if (!data.myGame) {
+        throw new Error('Game not found or not owned by this session.')
+      }
+      return textResult(data.myGame)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_run_game_checks',
+    {
+      description: 'Run manifest, provision, and JWT integration checks for an owned game.',
+      inputSchema: z.object({
+        gameId: z.string().describe('JoinQuest game UUID'),
+      }),
+    },
+    async ({ gameId }) => {
+      const data = await gql(MUTATIONS.runMyGameChecks, { gameId })
+      return textResult(data.runMyGameChecks ?? [])
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_update_game_metadata',
+    {
+      description: 'Save catalog listing copy and tags after developer approval. Use catalogTagTaxonomy IDs.',
+      inputSchema: z.object({
+        gameId: z.string(),
+        shortDescription: z.string().optional(),
+        longDescription: z.string().optional(),
+        howToPlay: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+      }),
+    },
+    async ({ gameId, shortDescription, longDescription, howToPlay, tags }) => {
+      const input = { gameId }
+      if (shortDescription !== undefined) input.shortDescription = shortDescription
+      if (longDescription !== undefined) input.longDescription = longDescription
+      if (howToPlay !== undefined) input.howToPlay = howToPlay
+      if (tags !== undefined) input.tags = tags
+
+      const data = await gql(MUTATIONS.updateMyGameMetadata, { input })
+      return textResult(data.updateMyGameMetadata)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_game_credentials',
+    {
+      description: 'Return serviceToken and webhookSecret for an owned game (sensitive).',
+      inputSchema: z.object({
+        gameId: z.string(),
+      }),
+    },
+    async ({ gameId }) => {
+      const data = await gql(QUERIES.myGameCredentials, { id: gameId })
+      if (!data.myGameCredentials) {
+        throw new Error('Credentials not found or game not owned by this session.')
+      }
+      return textResult(data.myGameCredentials)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_get_example_provision_payload',
+    {
+      description: 'Build a sample POST /api/v1/matches body for local testing, using synced modes and credentials.',
+      inputSchema: z.object({
+        gameId: z.string(),
+      }),
+    },
+    async ({ gameId }) => {
+      const [gameData, credData] = await Promise.all([
+        gql(QUERIES.myGame, { id: gameId }),
+        gql(QUERIES.myGameCredentials, { id: gameId }),
+      ])
+      if (!gameData.myGame || !credData.myGameCredentials) {
+        throw new Error('Game or credentials not found.')
+      }
+      const urls = lobbyUrls(apiUrl)
+      const payload = buildExampleProvisionPayload({
+        game: gameData.myGame,
+        credentials: credData.myGameCredentials,
+        ...urls,
+      })
+      return textResult(payload)
+    },
+  )
+
+  server.registerTool(
+    'joinquest_integration_request_public_release',
+    {
+      description: 'Submit an owned game for public catalog review when checklist and metadata gates pass.',
+      inputSchema: z.object({
+        gameId: z.string(),
+      }),
+    },
+    async ({ gameId }) => {
+      const data = await gql(MUTATIONS.requestPublicRelease, { gameId })
+      return textResult(data.requestPublicRelease)
+    },
+  )
+}