plures-mcp 1.3.1 → 1.5.1

package/README.md

@@ -2,6 +2,8 @@
 
 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).
 
+[![Plures MCP server](https://mcprush.com/badge/plures-mcp/card.svg)](https://mcprush.com/to/plures-mcp?ref=badge)
+
 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
@@ -27,6 +29,8 @@ A `pk_test_` key answers instantly with a simulated result (always the first opt
 ## Tools
 
 **`ask_humans`**: send a judgment call to verified people.
+
+Set `route: "team"` to send a decision straight to your own team instead of verified people (for money and account decisions, and confidential or policy calls), `team` to pick one of your named teams, `team_votes` to have several of them vote, and `category` to let your routing rules decide. Live, each internal vote is $0.05.
 - `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
@@ -40,11 +44,15 @@ A `pk_test_` key answers instantly with a simulated result (always the first opt
 
 **`cancel_human_task`**: cancel a task that no longer matters.
 
+**`get_mapping_guide`**, **`submit_agent_map`**, **`get_agent_map`**: ask your coding agent to "map this app for Plures". It reads the guide, reads your code where it runs, and sends Plures only the map: the steps, the actions with consequences, and a drafted check for each place a person should look. Open the map in your dashboard to try each check and add it.
+
 Each result tells the agent the answer, how many people agreed and whether it is safe to act on. If you've added your team at plures.si/dashboard/team, decisions verified people don't all agree on go to your team, and the agent gets their decision as the final answer.
 
 ## 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.
+The server tells the agent to ask verified people before acting on judgment calls where a mistake is costly: whether an AI answer is correct and on policy, which of two model responses is better, a customer's tone or intent, whether a listing, document or screenshot matches, a moderation edge case. Not for anything it can check with code or a lookup.
+
+Money and account decisions (refunds, payments, invoices, payouts, account access) go to your own team: the agent sends them with `route: "team"`, or your routing rules can match them by `category`.
 
 Tasks are shown to strangers, so the agent is told not to include secrets or more personal data than the decision needs.
 
@@ -52,5 +60,6 @@ Tasks are shown to strangers, so the agent is told not to include secrets or mor
 
 - `PLURES_API_KEY` (required)
 - `PLURES_BASE_URL` (optional, defaults to https://plures.si)
+- `PLURES_APP` (optional): the app tasks and maps belong to, like `support-agent`
 
 MIT licensed. Source: [github.com/plureslabs/plures](https://github.com/plureslabs/plures).

package/dist/index.js

@@ -5,21 +5,26 @@ 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.3.1";
+var VERSION = "1.5.1";
 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."
+  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 trust or safety: grading whether an AI answer is correct, safe and on policy, picking the better of two model responses, reading a customer's tone or intent, checking that a listing, document or screenshot matches what it claims, 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. Money and account decisions (refunds, payments, invoices, payouts, account access) belong to the company's own people: set route to team for those, and for anything confidential, a policy call or regulated, so it goes straight to the developer's team instead of verified people. When the user asks to map their app or agent for Plures, call get_mapping_guide, read the code the way it says, then call submit_agent_map. Never put source code, secrets or customer data in a map."
 });
 var TEST_NOTE = "TEST MODE: this answer is simulated; no person saw the question. It always picks the first option, so don't act on it. Use a live key for real answers.";
 var fmt = (t) => {
   const text = describe(t);
+  if (t.mode === "test" && t.route === "team") return `TEST TASK, sent to your own team (marked as a test in their email).
+${text}`;
   return t.mode === "test" ? `${TEST_NOTE}
 ${text}` : text;
 };
-var describe = (t) => {
+var describe = (task) => {
+  const t = task;
   const label = (id) => t.options.find((o) => o.id === id)?.label ?? id;
+  if (t.status === "pending" && t.escalation?.reason === "team_only")
+    return `Sent straight to ${t.team ? `your ${t.team} team` : "your team"}${(t.team_consensus?.votes ?? 1) > 1 ? `, where ${t.team_consensus.votes} people vote` : ""}. Task ${t.id}. Call get_human_answer with this task_id later; don't act until it's decided.`;
   if (t.status === "pending" && t.escalation)
     return `Verified people didn't all agree, so the decision went to your team, who decide within a day. Task ${t.id}. Call get_human_answer with this task_id later; don't act until it's decided.`;
   if (t.status === "pending")
@@ -28,6 +33,12 @@ var describe = (t) => {
   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.`;
+  const tv = r?.team;
+  const teamVotes = tv && tv.voters.length > 1 ? ` ${tv.voters.filter((v) => !v.lead).length} people voted, ${Math.round(tv.agreement * 100)}% agreed${tv.decided_by_lead ? ", and the lead made the final call" : ""}.` : "";
+  if (r?.decided_by === "team" && r.answer !== null && t.route === "team")
+    return `Your team decided: ${label(r.answer)}${r.reviewer && !teamVotes ? ` (${r.reviewer})` : ""}.${teamVotes} This is the final answer; act on it.${r.note && !teamVotes ? ` Their note: "${r.note}"` : ""}`;
+  if (r?.decided_by === "team" && r.answer === null && tv)
+    return `Your team didn't agree (${Object.entries(tv.votes).filter(([, n]) => n > 0).map(([k, n]) => `${label(k)}: ${n}`).join(", ")}), so there's no answer. Don't act on it; ask a person on your team directly.`;
   if (r?.decided_by === "team" && r.answer !== null)
     return `Your team decided: ${label(r.answer)}${r.reviewer ? ` (${r.reviewer})` : ""}, after verified people didn't all agree (${votes}). This is the final answer; act on it.${r.note ? ` Their note: "${r.note}"` : ""}`;
   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.`;
@@ -36,7 +47,7 @@ var describe = (t) => {
 };
 var out = (t) => ({
   content: [{ type: "text", text: fmt(t) }],
-  structuredContent: { task_id: t.id, status: t.status, mode: t.mode, decided_by: t.result?.decided_by ?? null, with_team: !!t.escalation && t.status === "pending", answer: t.result?.answer ?? null, label: t.result?.label ?? null, agreement: t.result?.agreement ?? null, answers: t.result?.answers ?? 0, votes: t.result?.votes ?? {} }
+  structuredContent: { task_id: t.id, status: t.status, mode: t.mode, decided_by: t.result?.decided_by ?? null, with_team: !!t.escalation && t.status === "pending", route: t.route ?? "verifiers", 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,
@@ -62,14 +73,14 @@ var progressFor = (extra, total) => {
   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(), decided_by: z.string().nullable(), with_team: z.boolean(), answer: z.string().nullable(), label: z.string().nullable(), agreement: z.number().nullable(), answers: z.number(), votes: z.record(z.number()) };
+var result = { task_id: z.string(), status: z.string(), mode: z.string(), route: z.string(), decided_by: z.string().nullable(), with_team: z.boolean(), 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 use prepaid credit at $0.20 per answer (clips cost more by length); test keys are free and simulated.",
+  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: evals of AI output, tone and intent, whether two things match, moderation edge cases. Send refunds, payments and other money calls with route team. 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 use prepaid credit at $0.20 per answer (clips cost more by length), or $0.05 per internal vote with route team; 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"),
+    context: z.string().max(2e4).optional().describe("The material to judge, as plain text: the AI answer and the policy it should follow, the message, the listing"),
     image_url: z.string().url().optional().describe("An https image shown with the question"),
     audio_url: z.string().url().optional().describe("An https recording people listen to in full before answering, such as a call your voice agent handled. Up to 3 minutes; needs media_seconds"),
     video_url: z.string().url().optional().describe("An https video (MP4) people watch in full before answering. Up to 3 minutes; needs media_seconds. Not with audio_url"),
@@ -77,6 +88,11 @@ server.registerTool("ask_humans", {
     sensitive: z.boolean().optional().describe("Set true for violent, graphic or disturbing content, so only people who opted in see it, behind a warning"),
     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"),
+    route: z.enum(["verifiers", "team"]).optional().describe("verifiers (default) asks ID verified people first. team sends it straight to the developer's own people, for money and account decisions and confidential or policy calls; $0.05 per internal vote live"),
+    category: z.string().max(64).optional().describe(`A label the developer's routing rules match on, like "refunds"; the rule may choose the route and team`),
+    team: z.string().max(40).optional().describe(`The name of one of the developer's teams, like "Finance", to decide instead of the main team`),
+    team_votes: z.number().int().min(1).max(10).optional().describe("With route team: how many people on the team vote; the majority decides"),
+    app: z.string().max(40).optional().describe(`Which of the developer's apps this is for, like "support-agent". Default: PLURES_APP, then the default app`),
     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,
@@ -85,7 +101,8 @@ server.registerTool("ask_humans", {
   if (!plures) return noKey();
   try {
     const wait = wait_seconds ?? 45;
-    const created = await plures.tasks.create({ ...params, metadata: { source: "mcp" } });
+    const app = params.app ?? process.env.PLURES_APP;
+    const created = await plures.tasks.create({ ...params, ...app ? { app } : {}, 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) {
@@ -123,4 +140,77 @@ server.registerTool("cancel_human_task", {
     return fail(e);
   }
 });
+var BASE = (process.env.PLURES_BASE_URL ?? "https://plures.si").replace(/\/$/, "");
+async function api(method, path, body) {
+  const r = await fetch(BASE + path, { method, headers: { authorization: `Bearer ${KEY}`, "user-agent": `plures-mcp/${VERSION}`, ...body ? { "content-type": "application/json" } : {} }, body: body ? JSON.stringify(body) : void 0 });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+  return data;
+}
+var describeMap = (m) => {
+  const label = (id) => m.nodes.find((n) => n.id === id)?.label ?? id;
+  const actions = m.nodes.filter((n) => n.kind === "action");
+  const checked = new Set(m.checkpoints.filter((c) => c.status !== "dismissed").map((c) => c.at));
+  const lines = m.checkpoints.map((c) => `- ${label(c.at)} (${c.category}): ${c.status}${c.stats?.tasks ? `, ${c.stats.tasks} checks in 30 days${c.stats.agreement != null ? `, ${Math.round(c.stats.agreement * 100)}% agreement` : ""}` : ""}. ${c.why}`);
+  const open = actions.filter((a) => a.risk === "high" && !checked.has(a.id)).map((a) => `- ${a.label}: high risk, no check`);
+  return [
+    `${m.name ?? m.app}, version ${m.version}: ${m.nodes.length} steps, ${actions.length} actions with consequences.`,
+    ...lines,
+    ...open,
+    m.url ? `The developer can see it and try each check at ${m.url}` : ""
+  ].filter(Boolean).join("\n");
+};
+server.registerTool("get_mapping_guide", {
+  title: "Get the Plures mapping guide",
+  description: "Returns the steps for mapping the developer's AI agent for Plures: how to find its steps and actions, where to suggest a person checks, and how to draft each check. Call this first when asked to map an app for Plures.",
+  inputSchema: {},
+  annotations: { readOnlyHint: true, openWorldHint: true }
+}, async () => {
+  try {
+    const r = await fetch(`${BASE}/api/v1/map_guide`);
+    return { content: [{ type: "text", text: await r.text() }] };
+  } catch (e) {
+    return fail(e);
+  }
+});
+server.registerTool("submit_agent_map", {
+  title: "Send an agent map to Plures",
+  description: "Uploads the map you made with get_mapping_guide: nodes, edges and checkpoints with drafted checks. Never include source code, secrets or customer data. If Plures names a problem, fix it and send again.",
+  inputSchema: {
+    map: z.object({
+      name: z.string().optional(),
+      summary: z.string().optional(),
+      source: z.object({ repo: z.string().optional(), commit: z.string().optional(), tool: z.string().optional() }).optional(),
+      nodes: z.array(z.record(z.any())),
+      edges: z.array(z.record(z.any())),
+      checkpoints: z.array(z.record(z.any()))
+    }).describe("The agent map, as the guide describes"),
+    app: z.string().optional().describe("The app id, like support-agent. Default: the PLURES_APP environment variable, then the account's default app")
+  },
+  annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
+}, async ({ map, app }) => {
+  if (!KEY) return noKey();
+  const id = app ?? process.env.PLURES_APP ?? "default";
+  try {
+    return { content: [{ type: "text", text: describeMap(await api("PUT", `/api/v1/apps/${encodeURIComponent(id)}/map`, map)) }] };
+  } catch (e) {
+    return fail(e);
+  }
+});
+server.registerTool("get_agent_map", {
+  title: "Get an agent map",
+  description: "Returns an app's agent map from Plures: its checkpoints, which are added, and live numbers for each (checks in 30 days, agreement, how many went to the team).",
+  inputSchema: { app: z.string().optional().describe("The app id. Default: PLURES_APP, then the default app") },
+  annotations: { readOnlyHint: true, openWorldHint: true }
+}, async ({ app }) => {
+  if (!KEY) return noKey();
+  const id = app ?? process.env.PLURES_APP ?? "default";
+  try {
+    const m = await api("GET", `/api/v1/apps/${encodeURIComponent(id)}/map`);
+    if (!m.version) return { content: [{ type: "text", text: `${id} has no map yet. Call get_mapping_guide and follow it.` }] };
+    return { content: [{ type: "text", text: describeMap(m) }] };
+  } catch (e) {
+    return fail(e);
+  }
+});
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures-mcp",
-  "version": "1.3.1",
+  "version": "1.5.1",
   "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": [