plures-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plures Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# plures-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server that gives any AI agent a human in the loop: an `ask_humans` tool that sends a decision to ID verified people and returns their consensus before the agent acts. Built on [Plures](https://plures.si).
+
+Works with Claude Desktop, Claude Code, Cursor, VS Code, and agent frameworks that support MCP (OpenAI Agents SDK, LangChain, Vercel AI SDK and more).
+
+## Set up
+
+Get a free test key at [plures.si](https://plures.si/?for=developers#join), then add the server to your client:
+
+```json
+{
+  "mcpServers": {
+    "plures": {
+      "command": "npx",
+      "args": ["-y", "plures-mcp"],
+      "env": { "PLURES_API_KEY": "pk_test_..." }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add plures --env PLURES_API_KEY=pk_test_... -- npx -y plures-mcp`
+
+A `pk_test_` key answers instantly with a simulated result, so you can try the flow for free. A `pk_live_` key sends tasks to real verified people and is billed per answer.
+
+## Tools
+
+**`ask_humans`**: send a judgment call to verified people.
+- `question` (required): what people should decide, answerable from the context alone
+- `options` (required): 2 to 8 possible answers
+- `context`: the material to judge, as plain text
+- `image_url`, `instructions`
+- `verifiers`: 1, 3, 5, 7 or 9 (default 3)
+- `wait_seconds`: how long to wait for the answer, 0 to 240 (default 45). If people haven't answered by then, the tool returns a `task_id` to check later.
+
+**`get_human_answer`**: check a task by `task_id`, optionally waiting.
+
+**`cancel_human_task`**: cancel a task that no longer matters.
+
+Each result tells the agent the answer, how many people agreed and whether it is safe to act on: unanimous answers are, anything less should be escalated.
+
+## When agents should use it
+
+The server tells the agent to ask people before acting on judgment calls where a mistake is costly: a customer's tone or intent, a refund or payment, whether an invoice, listing or document matches, a moderation edge case. Not for anything it can check with code or a lookup.
+
+Tasks are shown to strangers, so the agent is told not to include secrets or more personal data than the decision needs.
+
+## Environment
+
+- `PLURES_API_KEY` (required)
+- `PLURES_BASE_URL` (optional, defaults to https://plures.si)
+
+MIT licensed. Source: [github.com/plureslabs/plures](https://github.com/plureslabs/plures).

package/dist/index.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Plures, PluresError } from "plures";
+var VERSION = "1.0.0";
+var KEY = process.env.PLURES_API_KEY;
+var plures = KEY ? new Plures(KEY, { baseUrl: process.env.PLURES_BASE_URL }) : null;
+var MAX_WAIT = 240;
+var server = new McpServer({ name: "plures", version: VERSION }, {
+  instructions: "Plures sends a decision to ID verified people, who answer independently, and returns their consensus. Use ask_humans before you act on a judgment call you are not sure about, where a wrong call costs money, trust or safety: reading a customer's tone or intent, approving a refund or payment, checking that an invoice, listing or document matches, moderating an edge case, or confirming a fact that needs human eyes. Don't use it for things you can check with code or a lookup. Act on the answer when agreement is 1; below that, treat it as uncertain and escalate or ask for more verifiers."
+});
+var fmt = (t) => {
+  const label = (id) => t.options.find((o) => o.id === id)?.label ?? id;
+  if (t.status === "pending")
+    return `Still waiting for people to answer. Task ${t.id}. Call get_human_answer with this task_id later.`;
+  if (t.status === "canceled") return `Task ${t.id} was canceled.`;
+  const r = t.result;
+  const votes = r ? Object.entries(r.votes).map(([k, v]) => `${label(k)}: ${v}`).join(", ") : "none";
+  if (t.status === "expired") return `Task ${t.id} expired before enough people answered. Votes so far: ${votes}. Treat this as unverified.`;
+  if (!r || r.answer === null) return `People were split${r?.tie ? " (a tie)" : ""}. Votes: ${votes}. Treat this as uncertain and escalate to a person on your team.`;
+  const strength = r.agreement >= 1 ? "Everyone agreed, so it is safe to act on." : `Agreement is ${Math.round(r.agreement * 100)}%, so treat it as uncertain.`;
+  return `Verified people answered: ${label(r.answer)}. ${Math.round(r.agreement * r.answers)} of ${r.answers} agreed. ${strength} Votes: ${votes}.${t.mode === "test" ? " (Test mode: this answer is simulated, no real people saw it.)" : ""}`;
+};
+var out = (t) => ({
+  content: [{ type: "text", text: fmt(t) }],
+  structuredContent: { task_id: t.id, status: t.status, mode: t.mode, answer: t.result?.answer ?? null, label: t.result?.label ?? null, agreement: t.result?.agreement ?? null, answers: t.result?.answers ?? 0, votes: t.result?.votes ?? {} }
+});
+var fail = (e) => ({
+  isError: true,
+  content: [{ type: "text", text: e instanceof PluresError ? `Plures said ${e.status}: ${e.message}` : `Couldn't reach Plures: ${e instanceof Error ? e.message : String(e)}` }]
+});
+var noKey = () => ({
+  isError: true,
+  content: [{ type: "text", text: "PLURES_API_KEY isn't set. Add it to this MCP server's environment. A free test key is at https://plures.si/?for=developers#join" }]
+});
+async function settle(id, seconds, progress) {
+  const end = Date.now() + seconds * 1e3;
+  let t = await plures.tasks.retrieve(id);
+  let n = 0;
+  while (t.status === "pending" && Date.now() < end) {
+    await new Promise((r) => setTimeout(r, Math.min(3e3, Math.max(0, end - Date.now()))));
+    await progress?.(++n);
+    t = await plures.tasks.retrieve(id);
+  }
+  return t;
+}
+var progressFor = (extra, total) => {
+  const token = extra._meta?.progressToken;
+  if (token === void 0) return void 0;
+  return (n) => extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: n, total, message: "Waiting for verified people to answer" } });
+};
+var result = { task_id: z.string(), status: z.string(), mode: z.string(), answer: z.string().nullable(), label: z.string().nullable(), agreement: z.number().nullable(), answers: z.number(), votes: z.record(z.number()) };
+server.registerTool("ask_humans", {
+  title: "Ask verified humans",
+  description: "Send a decision to ID verified people before you act on it. Several people answer independently, each confirmed with Face ID, and you get back the consensus answer and how strongly they agreed. Use it for judgment calls where being wrong is costly: tone and intent, refunds and payments, whether two things match, moderation edge cases. Write the question so a stranger can answer it from the context alone, and never include secrets or more personal data than the decision needs. Live keys are billed per answer; test keys are free and simulated.",
+  inputSchema: {
+    question: z.string().min(3).max(1e3).describe('What people should decide, e.g. "Is this customer upset?"'),
+    options: z.array(z.string().min(1).max(200)).min(2).max(8).describe('2 to 8 possible answers, e.g. ["Yes", "No"]'),
+    context: z.string().max(2e4).optional().describe("The material to judge, as plain text: the message, the invoice lines, the listing"),
+    image_url: z.string().url().optional().describe("An https image shown with the question"),
+    instructions: z.string().max(2e3).optional().describe("Short guidance shown under the question"),
+    verifiers: z.union([z.literal(1), z.literal(3), z.literal(5), z.literal(7), z.literal(9)]).optional().describe("How many people answer. Default 3; use 5 for higher stakes"),
+    wait_seconds: z.number().int().min(0).max(MAX_WAIT).optional().describe(`How long to wait for the answer before returning a task_id to check later. Default 45, up to ${MAX_WAIT}`)
+  },
+  outputSchema: result,
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+}, async ({ wait_seconds, ...params }, extra) => {
+  if (!plures) return noKey();
+  try {
+    const wait = wait_seconds ?? 45;
+    const created = await plures.tasks.create({ ...params, metadata: { source: "mcp" } });
+    const t = created.status === "pending" && wait > 0 ? await settle(created.id, wait, progressFor(extra, Math.ceil(wait / 3))) : created;
+    return out(t);
+  } catch (e) {
+    return fail(e);
+  }
+});
+server.registerTool("get_human_answer", {
+  title: "Get the human answer",
+  description: "Check on a task sent with ask_humans and return the verified people's answer once it's ready.",
+  inputSchema: {
+    task_id: z.string().describe("The task_id ask_humans returned"),
+    wait_seconds: z.number().int().min(0).max(MAX_WAIT).optional().describe("How long to wait if it's still pending. Default 0")
+  },
+  outputSchema: result,
+  annotations: { readOnlyHint: true, openWorldHint: true }
+}, async ({ task_id, wait_seconds }, extra) => {
+  if (!plures) return noKey();
+  try {
+    return out(await settle(task_id, wait_seconds ?? 0, progressFor(extra, Math.ceil((wait_seconds ?? 0) / 3))));
+  } catch (e) {
+    return fail(e);
+  }
+});
+server.registerTool("cancel_human_task", {
+  title: "Cancel a human task",
+  description: "Cancel a task that is still waiting for answers, for example when the decision no longer matters. Answers already given are still billed.",
+  inputSchema: { task_id: z.string().describe("The task_id ask_humans returned") },
+  outputSchema: result,
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
+}, async ({ task_id }) => {
+  if (!plures) return noKey();
+  try {
+    return out(await plures.tasks.cancel(task_id));
+  } catch (e) {
+    return fail(e);
+  }
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "plures-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "mcpName": "io.github.plureslabs/plures",
+  "description": "MCP server for Plures: lets any AI agent ask ID verified people to check a decision before it acts.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "human-in-the-loop",
+    "hitl",
+    "ai-agents",
+    "human-review",
+    "human-approval",
+    "plures"
+  ],
+  "homepage": "https://plures.si/docs#mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plureslabs/plures.git",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "author": "Plures Labs LLC <hello@plures.si>",
+  "type": "module",
+  "bin": {
+    "plures-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "plures": "^1.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}