@getabrain/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @getabrain/mcp-server
+
+MCP server for [GetABrain.ai](https://getabrain.ai) — give your AI agent real human judgment as native tools.
+
+## Use with Claude Desktop / Cursor
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "getabrain": {
+      "command": "npx",
+      "args": ["-y", "@getabrain/mcp-server"],
+      "env": {
+        "GETABRAIN_API_KEY": "gab_k_…",
+        "GETABRAIN_API_SECRET": "gab_s_…"
+      }
+    }
+  }
+}
+```
+
+Get your API key by signing up at https://getabrain.ai.
+
+## Tools
+
+- `get_balance` — check your prepaid balance.
+- `submit_query` — ask real humans a question (13 query types: A/B test, rating, ranking, sentiment, yes/no, image/video/audio review, …). Returns a `query_id`.
+- `get_responses` — fetch the human answers for a query.
+- `wait_for_responses` — poll (bounded) until enough humans answer; call again while it returns `pending`.
+- `list_queries` — your recent queries.
+- `rate_response` — rate a worker's answer 1–5.
+
+## Example agent flow
+
+1. `get_balance` → ensure funds.
+2. `submit_query` → get `query_id`.
+3. `wait_for_responses` (repeat while `pending`) → read the human answers.
+
+Full API docs: https://getabrain.ai/docs/api

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/client.ts
+import { GetABrain } from "@getabrain/sdk";
+function createClient(env = process.env) {
+  const apiKey = env.GETABRAIN_API_KEY;
+  const apiSecret = env.GETABRAIN_API_SECRET;
+  if (!apiKey || !apiSecret) {
+    throw new Error("GETABRAIN_API_KEY and GETABRAIN_API_SECRET environment variables are required.");
+  }
+  return new GetABrain({ apiKey, apiSecret, baseUrl: env.GETABRAIN_BASE_URL });
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+import { QUERY_TYPES, TimeoutError } from "@getabrain/sdk";
+
+// src/result.ts
+import {
+  InsufficientBalanceError,
+  AuthError,
+  ValidationError,
+  RateLimitError,
+  NotFoundError,
+  GetABrainError
+} from "@getabrain/sdk";
+function ok(data) {
+  return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function toToolError(e) {
+  if (e instanceof InsufficientBalanceError)
+    return fail("Insufficient balance. Add funds at https://getabrain.ai before submitting more queries.");
+  if (e instanceof AuthError)
+    return fail("Invalid GetABrain API credentials \u2014 check GETABRAIN_API_KEY / GETABRAIN_API_SECRET.");
+  if (e instanceof RateLimitError)
+    return fail(`Rate limited. Retry in ${Math.ceil((e.retryAfterMs ?? 1e3) / 1e3)}s.`);
+  if (e instanceof ValidationError)
+    return fail(`Invalid request: ${e.message}`);
+  if (e instanceof NotFoundError)
+    return fail("Not found: the query or response does not exist.");
+  if (e instanceof GetABrainError)
+    return fail(`GetABrain request failed (${e.status}): ${e.message}`);
+  return fail(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+}
+
+// src/tools.ts
+var tools = [
+  {
+    name: "get_balance",
+    description: "Get the prepaid balance (in cents) available to fund GetABrain queries.",
+    inputShape: {},
+    run: async (_args, client) => {
+      const b = await client.account.balance();
+      return ok({ balance_cents: b.balance_cents, company_name: b.company_name });
+    }
+  },
+  {
+    name: "submit_query",
+    description: `Submit a human-judgment query to real human workers and get its id back. "type" is one of: ${QUERY_TYPES.join(", ")}. "content_data" is the type-specific payload (e.g. ab_test: {question, variant_a:{description}, variant_b:{description}}; yes_no: {question}; rating_scale: {question, scale_type, scale_min, scale_max}). Cost = (bid_amount_cents + bonus_amount_cents) * required_responses, deducted from your balance.`,
+    inputShape: {
+      type: z.enum(QUERY_TYPES),
+      title: z.string().min(5).max(255),
+      content_data: z.record(z.any()),
+      required_responses: z.number().int().min(1).max(1e3),
+      bid_amount_cents: z.number().int().min(5),
+      description: z.string().optional(),
+      bonus_amount_cents: z.number().int().min(0).optional(),
+      min_worker_quality: z.number().min(0).max(5).optional()
+    },
+    run: async (args, client) => ok(await client.queries.create(args))
+  },
+  {
+    name: "get_responses",
+    description: "Get a query and the human responses submitted so far.",
+    inputShape: { query_id: z.string() },
+    run: async (args, client) => {
+      const q = await client.queries.get(args.query_id);
+      return ok({
+        status: q.status,
+        completed_responses: q.completed_responses,
+        required_responses: q.required_responses,
+        responses: q.responses ?? []
+      });
+    }
+  },
+  {
+    name: "wait_for_responses",
+    description: 'Poll for up to max_wait_seconds (default 50) for human responses to a query. Returns status "ready" with the responses if enough arrived, otherwise status "pending" \u2014 call again to keep waiting.',
+    inputShape: {
+      query_id: z.string(),
+      min_responses: z.number().int().min(1).optional(),
+      max_wait_seconds: z.number().int().min(1).max(50).optional()
+    },
+    run: async (args, client) => {
+      const current = await client.queries.get(args.query_id);
+      const minResponses = args.min_responses ?? current.required_responses;
+      try {
+        const responses = await client.queries.waitForResponses(args.query_id, {
+          minResponses,
+          timeoutMs: (args.max_wait_seconds ?? 50) * 1e3,
+          pollIntervalMs: 5e3
+        });
+        return ok({ status: "ready", responses });
+      } catch (e) {
+        if (!(e instanceof TimeoutError)) throw e;
+        const q = await client.queries.get(args.query_id);
+        if (q.status === "completed" || (q.completed_responses ?? 0) >= minResponses) {
+          return ok({ status: "ready", responses: q.responses ?? [] });
+        }
+        return ok({
+          status: "pending",
+          completed_responses: q.completed_responses ?? 0,
+          required_responses: q.required_responses,
+          hint: "Call wait_for_responses again to keep waiting for more human answers."
+        });
+      }
+    }
+  },
+  {
+    name: "list_queries",
+    description: "List your recent GetABrain queries (most recent first).",
+    inputShape: {
+      status: z.string().optional(),
+      limit: z.number().int().min(1).max(100).optional()
+    },
+    run: async (args, client) => ok(await client.queries.list(args))
+  },
+  {
+    name: "rate_response",
+    description: "Rate a worker's response 1-5 (feeds the quality system). Optionally include feedback_text.",
+    inputShape: {
+      query_id: z.string(),
+      response_id: z.string(),
+      score: z.number().int().min(1).max(5),
+      feedback_text: z.string().optional()
+    },
+    run: async (args, client) => ok(await client.responses.rate(args.query_id, args.response_id, { score: args.score, feedback_text: args.feedback_text }))
+  }
+];
+
+// src/server.ts
+function createServer(client) {
+  const server = new McpServer({ name: "getabrain", version: "0.1.0" });
+  for (const t of tools) {
+    server.tool(t.name, t.description, t.inputShape, async (args) => {
+      try {
+        return await t.run(args, client);
+      } catch (e) {
+        return toToolError(e);
+      }
+    });
+  }
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const client = createClient();
+  const server = createServer(client);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((e) => {
+  console.error(`getabrain-mcp failed to start: ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@getabrain/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for GetABrain.ai — real human judgment as agent tools",
+  "type": "module",
+  "bin": { "getabrain-mcp": "./dist/index.js" },
+  "main": "./dist/index.js",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@getabrain/sdk": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": { "tsup": "^8.0.0" },
+  "license": "MIT"
+}