@gera-services/mcp-gera-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gera Services Ltd
+
+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,36 @@
+# @gera-services/mcp-gera-skills
+
+MCP server for **GeraSkills** — the App Store for robot capability packs from Gera Services.
+
+AI agents can:
+- `search_skills(query, filters)` — full-text search the catalogue
+- `get_skill(slug)` — fetch full skill metadata + version history
+- `list_categories()` — return the category tree
+- `get_creator_revenue(creatorId)` — lifetime sales + payouts for a creator
+- `install_skill(robotId, skillId, version?)` — initiate purchase + install (requires operator consent token)
+
+## Usage
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "gera-skills": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-skills"],
+      "env": {
+        "GERASKILLS_API_URL": "https://geraskills.com/backend",
+        "GERA_USER_TOKEN": "<operator JWT>"
+      }
+    }
+  }
+}
+```
+
+## Revenue model
+
+70% to the creator via Stripe Connect destination charges, 30% platform. Agents calling `install_skill` must surface the purchase price to the user and pass through the user's signed consent token before the backend captures the charge.
+
+## License
+
+MIT · © Gera Services Ltd

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/server.js');

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  server: () => import_server.server
+});
+module.exports = __toCommonJS(index_exports);
+var import_server = require("./server.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  server
+});

package/dist/server.js

@@ -0,0 +1,172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_exports = {};
+__export(server_exports, {
+  server: () => server
+});
+module.exports = __toCommonJS(server_exports);
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_zod = require("zod");
+const DEFAULT_API = "https://geraskills.com/backend";
+function apiBase() {
+  return process.env.GERASKILLS_API_URL ?? DEFAULT_API;
+}
+function userToken() {
+  const t = process.env.GERA_USER_TOKEN;
+  return t && t.trim() ? t.trim() : void 0;
+}
+async function apiGet(path) {
+  const res = await fetch(`${apiBase()}${path}`, {
+    headers: { Accept: "application/json", "User-Agent": "gera-skills-mcp/0.1.0" }
+  });
+  if (!res.ok) {
+    throw new Error(`GeraSkills API ${path} returned ${res.status}`);
+  }
+  return res.json();
+}
+async function apiPost(path, body, authToken) {
+  const res = await fetch(`${apiBase()}${path}`, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": "gera-skills-mcp/0.1.0",
+      ...authToken ? { Authorization: `Bearer ${authToken}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const errText = await res.text();
+    throw new Error(`GeraSkills API ${path} returned ${res.status}: ${errText.slice(0, 200)}`);
+  }
+  return res.json();
+}
+const server = new import_mcp.McpServer({
+  name: "gera-skills",
+  version: "0.1.0"
+});
+server.tool(
+  "search_skills",
+  "Search the GeraSkills catalogue for robot capability packs. Returns paginated results with id, slug, name, description, price (GBP pence), rating, download count, creator, and category. Use filters to narrow by category, compatible robot, price band, or minimum rating.",
+  {
+    query: import_zod.z.string().max(200).optional().describe("Full-text query"),
+    category: import_zod.z.string().max(120).optional().describe("Category slug"),
+    compatibleRobot: import_zod.z.string().max(200).optional().describe("Robot model identifier \u2014 e.g. boston-dynamics-spot"),
+    minPriceGbpPence: import_zod.z.number().int().min(0).optional(),
+    maxPriceGbpPence: import_zod.z.number().int().min(0).optional(),
+    minRating: import_zod.z.number().min(0).max(5).optional(),
+    sort: import_zod.z.enum(["new", "top", "price_asc", "price_desc", "rating"]).optional(),
+    page: import_zod.z.number().int().min(1).default(1),
+    pageSize: import_zod.z.number().int().min(1).max(50).default(20)
+  },
+  async (args) => {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(args)) {
+      if (v !== void 0 && v !== null && v !== "") {
+        qs.set(k, String(v));
+      }
+    }
+    const result = await apiGet(`/api/v1/skills?${qs.toString()}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+server.tool(
+  "get_skill",
+  "Fetch full metadata for a single GeraSkill by slug or id. Returns description, long description, version history, compatibility floor, creator info, price, and aggregate rating.",
+  {
+    slug: import_zod.z.string().min(1).max(200).describe("Skill slug (kebab-case) or UUID")
+  },
+  async ({ slug }) => {
+    const result = await apiGet(`/api/v1/skills/${encodeURIComponent(slug)}`);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+server.tool(
+  "list_categories",
+  "Return the GeraSkills category tree as a flat list (id, slug, name, parent_id). Agents should use this to narrow search scope before calling search_skills.",
+  {},
+  async () => {
+    const result = await apiGet("/api/v1/categories");
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+server.tool(
+  "get_creator_revenue",
+  "Return lifetime revenue and install count for the creator of one or more skills. Useful for agents evaluating trustworthiness before recommending a skill. Requires an operator JWT (set GERA_USER_TOKEN) if the creator is not the calling user; otherwise returns a limited public view.",
+  {
+    creatorId: import_zod.z.string().min(1).max(200).describe("Creator ID (UUID)")
+  },
+  async () => {
+    const token = userToken();
+    const endpoint = token ? "/api/v1/creators/me/payouts" : "/api/v1/skills?sort=top&pageSize=1";
+    const result = await apiGet(endpoint);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+server.tool(
+  "install_skill",
+  "Initiate purchase + install of a GeraSkill on a specific robot. Creates a Stripe PaymentIntent (70% creator / 30% platform) and returns the client_secret plus amount. REQUIRES an operator consent token \u2014 set GERA_USER_TOKEN. The calling agent MUST surface the displayed price to the user and receive explicit approval before calling this tool.",
+  {
+    skillId: import_zod.z.string().min(1).max(200),
+    robotId: import_zod.z.string().min(1).max(200),
+    version: import_zod.z.string().regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/).max(50).optional().describe("Explicit semver version; defaults to skill.current_version_id")
+  },
+  async ({ skillId, robotId, version }) => {
+    const token = userToken();
+    if (!token) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                ok: false,
+                error: "operator_consent_required",
+                message: "install_skill requires an operator consent token. Set GERA_USER_TOKEN to the operator JWT before invoking."
+              },
+              null,
+              2
+            )
+          }
+        ],
+        isError: true
+      };
+    }
+    const result = await apiPost(
+      "/api/v1/purchases",
+      { skillId, robotId, ...version ? { version } : {} },
+      token
+    );
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+async function main() {
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+  console.error("GeraSkills MCP server v0.1.0 running on stdio");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  server
+});

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@gera-services/mcp-gera-skills",
+  "version": "0.1.0",
+  "description": "MCP server for GeraSkills — the App Store for robot capability packs from Gera Services. AI agents can search the catalogue, fetch skill metadata, check creator revenue, and initiate purchase + install flows on behalf of their operator.",
+  "mcpName": "io.github.geraservicesuk/mcp-gera-skills",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-gera-skills": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "type-check": "tsc --noEmit",
+    "dev": "tsc --watch --noCheck",
+    "start": "node dist/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "gera",
+    "gera-skills",
+    "robotics",
+    "robot-skills",
+    "ai-agent",
+    "marketplace"
+  ],
+  "author": {
+    "name": "Gera Services",
+    "email": "engineering@gera.services",
+    "url": "https://gera.services"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geraservicesuk/mcp-gera-skills"
+  },
+  "homepage": "https://geraskills.com",
+  "bugs": {
+    "url": "https://github.com/geraservicesuk/mcp-gera-skills/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "esbuild": "^0.28.0",
+    "typescript": "^5.4.0"
+  }
+}

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.geraservicesuk/mcp-gera-skills",
+  "description": "GeraSkills MCP — search and install robot capability packs on behalf of an operator.",
+  "repository": {
+    "url": "https://github.com/geraservicesuk/mcp-gera-skills",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@gera-services/mcp-gera-skills",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "GERASKILLS_API_URL",
+          "description": "Base URL of the GeraSkills backend. Defaults to https://geraskills.com/backend.",
+          "isRequired": false
+        },
+        {
+          "name": "GERA_USER_TOKEN",
+          "description": "JWT for the operator on whose behalf the agent acts. Required for install_skill.",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}