SpecHub

This repo is the implementation of the product described in SPEC.md.

What’s here (so far)

• apps/gateway: MCP-ish HTTP gateway with in-memory or Appwrite storage
• scripts/appwrite-bootstrap.js: creates Appwrite DB + collections used by the gateway
• scripts/pat-create.js / scripts/pat-revoke.js: manage Personal Access Tokens (PATs)
• apps/gateway/test/*: smoke tests (in-memory + real Appwrite)

Run the gateway locally

npm run dev:gateway

MCP server details

• Endpoint: POST /mcp (JSON-RPC 2.0)
• Auth:
  • AUTH_MODE=dev: requires Authorization: Bearer <DEV_PAT> (default dev-token)
  • AUTH_MODE=appwrite: either Authorization: Bearer <PAT> or a dashboard session cookie (spechub_session)
• Optional SSE response mode: send Accept: text/event-stream (or add ?sse=1) to get a single-event SSE response (non-streaming JSON-RPC result payload).

Env vars (optional):

• PORT (default: 8787)
• DEV_PAT (default: dev-token) – bearer token accepted by the gateway
• DEV_ADMIN_USER_IDS (default: empty) – comma-separated user IDs that can force-unlock
• ALLOWED_ORIGINS (optional) – allowlist for browser Origins (same-origin is allowed automatically; CORS supports credentialed requests for allowed origins)
• Cookie auth (for cross-origin dashboards):
  • COOKIE_SAMESITE=none and COOKIE_SECURE=1 (required if your dashboard is on a different “site”)
  • Optional: COOKIE_DOMAIN=.example.com (only works for shared parent domains)

Quick smoke test

$headers = @{
  Authorization = "Bearer dev-token"
  "Content-Type" = "application/json"
}

$body = @{
  jsonrpc = "2.0"
  id = 1
  method = "tools/list"
  params = @{}
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Method Post -Uri http://localhost:8787/mcp -Headers $headers -Body $body

Minimal CLI wrapper (/sh-* style)

This repo includes a minimal Node wrapper that can drive the MCP gateway:

npm run sh -- init --url http://localhost:8787 --pat dev-token --project demo
npm run sh -- plan mvp "Ship MVP"
npm run sh -- exec 1 --auto-complete

No-clone usage (installable binaries)

If you want to use /sh-* style commands in other repos without cloning this repo, install from Git and use the spechub binary:

npm i -g @pamudji/spechub
spechub-gateway   # runs the MCP gateway
spechub install-claude   # writes `.claude/commands/sh-*.md` into the current repo
spechub install-mcp      # writes `.mcp.json` that registers `spechub-mcp` (stdio→HTTP bridge)

Claude Code MCP setup (Option B: tools/resources directly)

Claude Code typically expects MCP servers over stdio. SpecHub’s gateway is HTTP, so use the included bridge:

• Install the package: npm i -g @pamudji/spechub
• In your repo: spechub install-mcp --url https://<your-gateway>
  • Defaults to an npx-based .mcp.json so collaborators don’t need a global install.
  • If you don’t want a PAT checked into the repo, omit --pat and set SPECHUB_PAT in your environment instead.
• Restart Claude Code so it reloads .mcp.json.

Use a remote Appwrite backend

1. Create .env from .env.example and set:

• STORAGE_BACKEND=appwrite
• AUTH_MODE=appwrite
• APPWRITE_ENDPOINT, APPWRITE_PROJECT_ID, APPWRITE_API_KEY, APPWRITE_DATABASE_ID

2. (Optional) Usage metering:

• ENABLE_APPWRITE_USAGE=1 records daily counters + append-only usage_events (shadow mode; never blocks core)

3. Bootstrap the Appwrite database + collections:

npm run appwrite:bootstrap

4. Start the gateway:

npm run dev:gateway

5. Sign up / log in via the dashboard (session cookie auth):

• Open http://localhost:8787/dashboard
• Use the “Signup / Login” section (this sets an HttpOnly spechub_session cookie)
• Click “Connect” with an empty PAT field (the dashboard will use the session cookie)

6. Create a PAT (for CLI or cross-site use), or use the dashboard PAT tools:

npm run pat:create -- --userId YOUR_USER_ID --accountId YOUR_ACCOUNT_ID --roles owner

Notes:

• If you don’t use Appwrite Teams, the gateway treats your “account” as user:<YOUR_USER_ID> (this is what dashboard/auth/whoami returns in accountIds).
• If your dashboard is hosted on a different site/origin, use a PAT (simplest) or configure cookie auth with COOKIE_SAMESITE=none + COOKIE_SECURE=1 and make your fetch() calls with credentials: "include".

7. Open the UIs:

• Dev UI: http://localhost:8787/
• Dashboard: http://localhost:8787/dashboard (docs editor, usage, PAT management)