handsforagents-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 your engineering s.r.o.
+
+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

@@ -0,0 +1,100 @@
+# Hands for Agents — MCP server
+
+**A person in the Czech Republic (EU) makes, assembles, measures, verifies and ships physical things for your agent, and sends the operator an invoice.**
+
+Your agent can call an API for almost anything except the physical world. This is the physical world: FDM 3D printing in-house, CNC / sheet metal / laser / welding through Czech subcontractors, assembly and commissioning of hardware, dimensional inspection, human testing of a device, on-site verification anywhere in the Czech Republic, and receive-repack-ship with customs paperwork. Every task ends with an evidence package — timestamped photos, a measurement report with the instrument and its resolution, a test log, a tracking number, and the name of the person who did the work.
+
+- **MCP endpoint:** `https://handsforagents.com/mcp` (Streamable HTTP)
+- **REST:** `https://handsforagents.com/v1/services`
+- **Everything machine-readable:** [llms.txt](https://handsforagents.com/llms.txt) · [services.json](https://handsforagents.com/services.json) · [openapi.yaml](https://handsforagents.com/openapi.yaml)
+
+## Install
+
+Point any client that supports remote MCP servers straight at the endpoint:
+
+```json
+{
+  "mcpServers": {
+    "handsforagents": {
+      "type": "http",
+      "url": "https://handsforagents.com/mcp"
+    }
+  }
+}
+```
+
+For a client that only speaks stdio, this package bridges to the same endpoint and adds nothing of its own:
+
+```json
+{
+  "mcpServers": {
+    "handsforagents": {
+      "command": "npx",
+      "args": ["-y", "handsforagents-mcp"]
+    }
+  }
+}
+```
+
+No API key, no account, no registration. `list_services` and `request_quote` are open; `get_status` needs the `access_token` that `request_quote` handed you.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_services` | The seven services, the refused categories, seven example prices, the payment rules and the key contract terms. Byte for byte the same document as `/services.json`. |
+| `request_quote` | Sends a task to a human for screening and a fixed-price quote. Not an order, not binding, nothing charged. Returns `quote_id`, `access_token`, `response_due_at` and `nda_url`. A human answers by e-mail within 4 business hours. |
+| `get_status` | Reads a quote request back with its `quote_id` and `access_token`. |
+
+**There is deliberately no `create_task` and no `confirm_delivery` yet.** The payment backend does not exist, so those steps happen by e-mail with a human, and the tool list says only what is true. They will be added when Stripe Checkout is live; the schemas are already published in [openapi.yaml](https://handsforagents.com/openapi.yaml) and in `services.json`.
+
+## Try it without installing anything
+
+```bash
+curl -s https://handsforagents.com/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'MCP-Protocol-Version: 2026-07-28' \
+  -H 'Mcp-Method: tools/list' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list",
+       "params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'
+```
+
+Or without MCP at all:
+
+```bash
+curl -s https://handsforagents.com/v1/services | head -40
+```
+
+## What it costs
+
+There is no catalogue. A human quotes every task as one fixed total in EUR or USD, built from **45 EUR/hour** plus materials, subcontractors and carrier cost at cost. Minimum 45 EUR. Seven worked examples are in `list_services` — a printed PETG bracket checked with calipers and shipped tracked to Germany comes to 70 EUR, on-site verification of a business address with ten geotagged photos to 105 EUR.
+
+Payment is by card through Stripe Checkout, in full up to 150 EUR, deposit plus balance above it, with the balance due after you have seen the evidence package and before the item ships. **No cryptocurrency, no cash, no anonymous payment of any kind** — deliberately, so that every client is identifiable and every task has an invoice.
+
+## What it will not do
+
+A human reads every request before a quote is issued; nothing is accepted automatically. Refused outright: anything needing login credentials or account access, impersonation, surveillance of people, fake reviews and engagement, getting around identity/age/CAPTCHA/KYC verification, referral and coupon fraud, weapons and export-controlled dual-use goods, counterfeits, reshipping goods bought with someone else's card, and anything illegal in the Czech Republic or the EU. Three further categories — confirming a person's identity, signing a document, receiving a parcel addressed to a third party — are accepted only after the operator has been verified.
+
+Also outside the capability: safety-critical parts (medical, food-contact, pressure, lifting) without a separate written engineering agreement, in-person work outside the Czech Republic, and storage beyond 30 days.
+
+## Who you are contracting with
+
+`your engineering s.r.o.`, company ID (IČO) 09738100, Jaurisova 515/4, Michle, 140 00 Praha 4, Czech Republic. Registered 9 December 2020, file C 341512 at the Municipal Court in Prague. Verify it yourself: [justice.cz](https://or.justice.cz/ias/ui/rejstrik-$firma?ico=09738100) · [ARES, as JSON](https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/ekonomicke-subjekty/09738100).
+
+The contract is with the **operator** of the agent — the company or person on whose behalf it acts — because an agent has no legal personality. Czech law, courts in Prague for business clients, consumers keep their home protections.
+
+Everything you send is **confidential by default** from the first `request_quote`, without marking anything and without signing anything, for the task and three years after. A pre-filled one-way [NDA](https://handsforagents.com/nda.html) is there if you need a signed document.
+
+Full terms: [terms](https://handsforagents.com/terms.html) · [task policy](https://handsforagents.com/task-policy.html) · [disputes and refunds](https://handsforagents.com/disputes.html) · [privacy](https://handsforagents.com/privacy.html) · [DPA](https://handsforagents.com/dpa.html)
+
+## Honest status
+
+The service opened in September 2026 and **no tasks have been completed yet**; the statistics on the site say so and will be updated monthly. Liability insurance is being arranged and is not yet in force — the site says that too, rather than implying otherwise. Completed tasks will be published here as anonymised examples with their evidence packages, with the client's consent.
+
+## Security
+
+Found something? `security@handsforagents.com`, or see [security.txt](https://handsforagents.com/.well-known/security.txt).
+
+## Licence
+
+MIT for this bridge package. The service itself is governed by the terms of service linked above.

package/index.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * handsforagents-mcp — stdio bridge to the Hands for Agents MCP server.
+ *
+ * The real server is remote (https://handsforagents.com/mcp, Streamable HTTP).
+ * This package exists for clients that only speak stdio, and so that the server
+ * is findable on npm. It adds nothing of its own: every tools/list and
+ * tools/call is forwarded to the remote endpoint unchanged.
+ *
+ * If your client supports remote MCP servers, point it straight at
+ * https://handsforagents.com/mcp and skip this package.
+ *
+ * Usage:
+ *   npx handsforagents-mcp
+ *   HANDSFORAGENTS_URL=https://staging.example.com/mcp npx handsforagents-mcp
+ *
+ * No dependencies. Node 18+ (for global fetch).
+ */
+
+import process from "node:process";
+
+const REMOTE = process.env.HANDSFORAGENTS_URL || "https://handsforagents.com/mcp";
+const MODERN = "2026-07-28";
+const LEGACY_FALLBACK = "2025-06-18";
+const PKG_VERSION = "0.1.0";
+const TIMEOUT_MS = Number(process.env.HANDSFORAGENTS_TIMEOUT_MS || 30000);
+
+const SERVER_INFO = { name: "handsforagents", title: "Hands for Agents", version: PKG_VERSION };
+
+const INSTRUCTIONS =
+  "Human-operated physical-world service for AI agents, run by a registered Czech (EU) company. " +
+  "A person designs, makes, assembles, measures, tests, verifies on site, receives and ships physical " +
+  "things, and documents the work with evidence. Call list_services first: it carries the refused " +
+  "categories, the prices and the contract terms. Then request_quote with a plain-language description " +
+  "of the task. Ordering and payment are not exposed as tools yet — a human answers your quote request " +
+  "by e-mail and the order is placed in that thread. Payment is by card in EUR or USD; no cryptocurrency. " +
+  "The contract is with the operator of the agent, not the agent.";
+
+// --------------------------------------------------------------------------
+// stdio framing: newline-delimited JSON, as the MCP stdio transport defines
+// --------------------------------------------------------------------------
+
+function write(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+function result(id, value) {
+  write({ jsonrpc: "2.0", id, result: value });
+}
+
+function failure(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  write({ jsonrpc: "2.0", id, error });
+}
+
+/** Log to stderr only. Anything on stdout that is not JSON-RPC breaks the client. */
+function note(...args) {
+  if (process.env.HANDSFORAGENTS_DEBUG) console.error("[handsforagents-mcp]", ...args);
+}
+
+// --------------------------------------------------------------------------
+// Remote call
+// --------------------------------------------------------------------------
+
+async function callRemote(method, params, name) {
+  const body = {
+    jsonrpc: "2.0",
+    id: Math.floor(Math.random() * 1e9),
+    method,
+    params: {
+      ...params,
+      _meta: {
+        ...(params._meta || {}),
+        "io.modelcontextprotocol/protocolVersion": MODERN,
+        "io.modelcontextprotocol/clientInfo": { name: "handsforagents-mcp", version: PKG_VERSION },
+        "io.modelcontextprotocol/clientCapabilities": {},
+      },
+    },
+  };
+
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    "User-Agent": `handsforagents-mcp/${PKG_VERSION} (+https://handsforagents.com)`,
+    "MCP-Protocol-Version": MODERN,
+    "Mcp-Method": method,
+  };
+  if (name !== undefined) {
+    // The spec's Base64 sentinel, for a name that is not plain ASCII.
+    headers["Mcp-Name"] = /^[\x21-\x7e]+$/.test(name)
+      ? name
+      : `=?base64?${Buffer.from(name, "utf8").toString("base64")}?=`;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const response = await fetch(REMOTE, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(`${REMOTE} returned ${response.status} and a body that is not JSON: ${text.slice(0, 200)}`);
+    }
+    if (parsed.error) {
+      const e = new Error(parsed.error.message || "Remote error");
+      e.rpc = parsed.error;
+      throw e;
+    }
+    return parsed.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Request handling
+// --------------------------------------------------------------------------
+
+async function handle(message) {
+  const { id, method, params = {} } = message;
+
+  // Notifications get no reply.
+  if (id === undefined || id === null) {
+    note("notification", method);
+    return;
+  }
+
+  try {
+    switch (method) {
+      // Legacy era: a stdio client that opens with initialize.
+      case "initialize": {
+        const wanted = typeof params.protocolVersion === "string" ? params.protocolVersion : null;
+        const known = [MODERN, "2025-11-25", "2025-06-18", "2025-03-26"];
+        result(id, {
+          protocolVersion: wanted && known.includes(wanted) ? wanted : LEGACY_FALLBACK,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: SERVER_INFO,
+          instructions: INSTRUCTIONS,
+        });
+        return;
+      }
+
+      // Modern era: the stdio backward-compatibility probe.
+      case "server/discover": {
+        const remote = await callRemote("server/discover", {});
+        result(id, remote);
+        return;
+      }
+
+      case "ping":
+        result(id, {});
+        return;
+
+      case "tools/list": {
+        const remote = await callRemote("tools/list", params);
+        // Hand the client only what its own era understands.
+        result(id, { tools: remote.tools || [] });
+        return;
+      }
+
+      case "tools/call": {
+        const remote = await callRemote("tools/call", params, params.name);
+        const out = { content: remote.content || [], isError: Boolean(remote.isError) };
+        if (remote.structuredContent !== undefined) out.structuredContent = remote.structuredContent;
+        result(id, out);
+        return;
+      }
+
+      case "resources/list":
+        result(id, { resources: [] });
+        return;
+
+      case "prompts/list":
+        result(id, { prompts: [] });
+        return;
+
+      default:
+        failure(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (err) {
+    if (err.rpc) {
+      failure(id, err.rpc.code ?? -32603, err.rpc.message, err.rpc.data);
+      return;
+    }
+    const reason =
+      err.name === "AbortError"
+        ? `No answer from ${REMOTE} within ${TIMEOUT_MS} ms.`
+        : `Cannot reach ${REMOTE}: ${err.message}`;
+    // A tool call fails as a tool error so the model can react; everything else
+    // is a protocol error.
+    if (method === "tools/call") {
+      result(id, { content: [{ type: "text", text: reason }], isError: true });
+    } else {
+      failure(id, -32603, reason);
+    }
+  }
+}
+
+// --------------------------------------------------------------------------
+// Read stdin line by line
+// --------------------------------------------------------------------------
+
+let buffer = "";
+let inFlight = 0;
+let stdinEnded = false;
+
+function maybeExit() {
+  if (stdinEnded && inFlight === 0) process.exit(0);
+}
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let newline;
+  while ((newline = buffer.indexOf("\n")) !== -1) {
+    const line = buffer.slice(0, newline).trim();
+    buffer = buffer.slice(newline + 1);
+    if (!line) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      failure(null, -32700, "Parse error: the line is not valid JSON.");
+      continue;
+    }
+    if (Array.isArray(message)) {
+      failure(null, -32600, "Batches are not supported. Send one JSON-RPC message per line.");
+      continue;
+    }
+    inFlight++;
+    handle(message)
+      .catch((err) => note("unhandled", err))
+      .finally(() => {
+        inFlight--;
+        maybeExit();
+      });
+  }
+});
+
+// Do not exit while a forwarded request is still in the air: a client that
+// closes stdin immediately after writing would otherwise lose the answers.
+process.stdin.on("end", () => {
+  stdinEnded = true;
+  maybeExit();
+});
+process.on("SIGINT", () => process.exit(0));
+process.on("SIGTERM", () => process.exit(0));
+
+note("bridging stdio to", REMOTE);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "handsforagents-mcp",
+  "version": "0.1.0",
+  "mcpName": "com.handsforagents/hands",
+  "description": "MCP server for Hands for Agents: a human in the EU makes, assembles, measures, verifies and ships physical things for your agent.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "agent",
+    "agents",
+    "physical-world",
+    "manufacturing",
+    "3d-printing",
+    "human-in-the-loop",
+    "fulfilment",
+    "europe"
+  ],
+  "homepage": "https://handsforagents.com",
+  "bugs": {
+    "url": "https://github.com/handsforagents/handsforagents-mcp/issues",
+    "email": "security@handsforagents.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/handsforagents/handsforagents-mcp.git"
+  },
+  "license": "MIT",
+  "author": "your engineering s.r.o. (https://handsforagents.com)",
+  "type": "module",
+  "bin": {
+    "handsforagents-mcp": "./index.js"
+  },
+  "main": "./index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}