@gera-services/mcp-gera-skills 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Gera Services Ltd
+Copyright (c) 2026 Gera Systems 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

package/README.md

@@ -1,36 +1,107 @@
-# @gera-services/mcp-gera-skills
+# GeraSkills MCP Server
 
-MCP server for **GeraSkills** — the App Store for robot capability packs from Gera Services.
+[![A Gera Systems product](https://img.shields.io/badge/Gera-Systems-0a7?style=flat)](https://skills.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)
+An [MCP](https://modelcontextprotocol.io) server that lets AI agents — Claude
+Desktop, ChatGPT with tools, Cursor, Windsurf, or any MCP client — **search,
+inspect, and recommend AI skill packs** from the
+[GeraSkills](https://skills.gera.services) marketplace.
 
-## Usage
+The full catalogue (104 skill packs across 12 categories — Healthcare, Legal &
+Compliance, Education, Home & Lifestyle, Business & Finance, Agriculture &
+Food, Environment & Sustainability, Real Estate, Personal Finance, Government &
+Civic, Wellness & Mental Health, Science & Research) is embedded from the real
+GeraSkills web data. **No backend, no network, no auth** — every tool answers
+locally, so it is safe to run anywhere and returns the same skills the live
+marketplace shows.
 
-```jsonc
-// claude_desktop_config.json
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_skills` | Full-text search the catalogue with optional filters (category, region, max monthly price, badge). Returns compact cards. |
+| `get_skill` | Full detail for one skill by id or name — every capability, both price options, tags, target user, regions, badge, marketplace URL. |
+| `recommend_skills` | Given a plain-language goal, return a ranked "skill path" of the most relevant skills, scored by goal-term overlap. |
+| `list_categories` | All 12 categories with a skill count each — scope a search before drilling in. |
+| `skills_for_region` | Skills explicitly tagged for a region/country (`UK`, `EU`, `US`, `Global`) — for jurisdiction-specific needs. |
+
+A typical agent flow: `list_categories` → `search_skills` (or `recommend_skills`
+for a goal) → `get_skill` for the full record.
+
+## Install & run
+
+```bash
+# Run directly (no global install) once published to npm:
+npx -y @gera-services/mcp-gera-skills
+
+# Or from this repo:
+cd packages/mcp-gera-skills
+npm run build      # tsc --noCheck + copy catalogue -> dist/
+node bin/cli.js    # starts on stdio
+```
+
+## Client configuration
+
+### Claude Desktop / Claude Code (`claude_desktop_config.json`)
+
+```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>"
-      }
+      "args": ["-y", "@gera-services/mcp-gera-skills"]
     }
   }
 }
 ```
 
-## Revenue model
+Local (unpublished) variant — point at the built CLI:
+
+```json
+{
+  "mcpServers": {
+    "gera-skills": {
+      "command": "node",
+      "args": ["/Users/armen/Gera/packages/mcp-gera-skills/bin/cli.js"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf (`.cursor/mcp.json` etc.)
+
+```json
+{
+  "mcpServers": {
+    "gera-skills": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-skills"]
+    }
+  }
+}
+```
+
+## Verify it works
+
+```bash
+npm run build
+node scripts/smoke.mjs
+```
+
+The smoke test speaks raw MCP JSON-RPC over stdio (`initialize` → `tools/list`
+→ several `tools/call`) and asserts the results. Expected output ends with
+`ALL SMOKE CHECKS PASSED`.
+
+## Example
+
+Ask your agent: *"I'm setting up a small UK accountancy practice — what
+GeraSkills should I look at?"*
 
-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.
+The agent calls `recommend_skills` with `goal: "run a small UK accountancy
+practice", region: "UK"` and gets back a ranked skill path including
+`bookkeeping-assistant`, `company-secretary-assistant`, and
+`anti-money-laundering-guide`, each with its price and marketplace URL.
 
 ## License
 
-MIT · © Gera Services Ltd
+MIT © Gera Systems Ltd

package/bin/cli.js

@@ -1,2 +1,12 @@
 #!/usr/bin/env node
-require('../dist/server.js');
+/**
+ * CLI entry point for the GeraSkills MCP server.
+ * Starts the server on stdio. Intended to be launched by an MCP client
+ * (Claude Desktop, ChatGPT-with-tools, Cursor, etc.) — not run interactively.
+ */
+import { main } from '../dist/server.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});