jerry-skills-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikash Vardhan
+
+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,193 @@
+# JERRY
+
+**The right skill for every prompt, picked automatically.**
+
+JERRY searches a library of 2,300+ agent skills written by the community, finds the
+ones that fit what you're working on, and hands them to your coding agent. You don't
+browse, choose or install skills. You install JERRY once and keep working.
+
+Works with **Claude Code**, **Codex** and **Gemini CLI**.
+
+---
+
+## Install (2 minutes)
+
+You need [Node.js 18+](https://nodejs.org) and `git`.
+
+### 1. Clone
+
+```bash
+git clone https://github.com/vikasvardhanv/jerry-plugin.git
+cd jerry-plugin
+```
+
+### 2. Install for your agent
+
+Run these **from inside the `jerry-plugin` folder**.
+
+**Claude Code** — start `claude` in the folder, then type:
+
+```
+/plugin marketplace add ./
+/plugin install jerry@jerry
+```
+
+**Codex** — in your terminal:
+
+```bash
+codex plugin marketplace add ./
+codex plugin add jerry@jerry
+```
+
+**Gemini CLI** — in your terminal:
+
+```bash
+gemini extensions link .
+```
+
+### 3. Restart your agent
+
+Quit and reopen Claude Code, Codex or Gemini so it loads JERRY.
+
+### 4. Check it works
+
+Ask your agent something real, for example:
+
+> Write a failing test first, then fix the off-by-one bug in this loop.
+
+Your agent will get a short list of matching skills and load the one it needs. In
+Claude Code, run `/jerry-skills` to see what JERRY offered and why.
+
+---
+
+## Other ways to install
+
+**Without cloning** (installs straight from GitHub):
+
+```bash
+# Claude Code (from a terminal)
+claude plugin marketplace add vikasvardhanv/jerry-plugin && claude plugin install jerry@jerry
+
+# Codex
+codex plugin marketplace add vikasvardhanv/jerry-plugin && codex plugin add jerry@jerry
+
+# Gemini CLI
+gemini extensions install https://github.com/vikasvardhanv/jerry-plugin --consent
+```
+
+**Ask your agent to do it.** Paste this into Claude Code, Codex or Gemini:
+
+> Install the JERRY plugin from github.com/vikasvardhanv/jerry-plugin
+
+**Any other MCP client** (Cursor, Claude Desktop, ...) — add this to its MCP config:
+
+```json
+{
+  "mcpServers": {
+    "jerry-skills": { "command": "npx", "args": ["-y", "github:vikasvardhanv/jerry-plugin"] }
+  }
+}
+```
+
+---
+
+## Update
+
+```bash
+cd jerry-plugin && git pull
+```
+
+then:
+
+| Agent | Command |
+|---|---|
+| Claude Code | `claude plugin marketplace update jerry` then `claude plugin update jerry@jerry` |
+| Codex | `codex plugin add jerry@jerry` (reinstalls from the updated folder) |
+| Gemini CLI | nothing more: `link` always uses the folder as it is |
+
+## Uninstall
+
+| Agent | Command |
+|---|---|
+| Claude Code | `claude plugin uninstall jerry@jerry` and `claude plugin marketplace remove jerry` |
+| Codex | `codex plugin remove jerry@jerry` and `codex plugin marketplace remove jerry` |
+| Gemini CLI | `gemini extensions uninstall jerry` |
+
+---
+
+## What happens on each prompt
+
+1. JERRY searches the library by meaning, not keywords, and adds a short list of the
+   best matches to your agent's context: about 30 tokens per skill, names and
+   one-line summaries only.
+2. If one fits, the agent loads that skill's full instructions. If none fit, it
+   ignores the list and carries on.
+
+In Claude Code and Codex this runs automatically on every prompt. In Gemini CLI the
+agent is instructed to search at the start of each task.
+
+JERRY never blocks a prompt. If the service is slow or down, you just don't get a list.
+
+## Why two steps
+
+Pasting every plausible skill into every prompt wastes context and mostly goes unread.
+A list costs a few dozen tokens; the agent then loads only the skill it will use.
+
+It is also how skill authors get paid: showing up in the list is free, and **loading**
+a skill credits its author.
+
+## Write skills and get paid
+
+Publish your own skills at **https://jerry.viktronconsulting.com/portal**:
+
+1. Sign in and choose your author handle.
+2. Paste or upload a `SKILL.md`. It's searchable as soon as you publish.
+3. Connect Stripe to receive payouts.
+4. See how often each skill is shown, loaded, and what it has earned.
+
+Each load credits the skill's royalty (default $0.02). The same skill loaded twice in
+one session within 24 hours is paid once.
+
+If your skills are already in the library under your GitHub name, sign in with that
+GitHub account to claim the royalties held for you.
+
+## Commands (Claude Code)
+
+- `/jerry-skills` — what was offered and loaded in this session, and why
+- `/jerry-earnings [@author]` — impressions, loads and earnings per skill
+
+## Configuration
+
+Optional environment variables:
+
+| Variable | Default | |
+|---|---|---|
+| `JERRY_API_URL` | `https://jerry.viktronconsulting.com` | API to query |
+| `JERRY_MAX_SKILLS` | `3` | candidates listed per prompt |
+| `JERRY_MIN_PROMPT_CHARS` | `24` | shorter prompts skip the search |
+| `JERRY_TIMEOUT_MS` | `6000` | the prompt goes through unchanged past this |
+
+## Troubleshooting
+
+**No skills ever appear.** Check the service answers:
+
+```bash
+curl -s -X POST https://jerry.viktronconsulting.com/api/jerry/skills/index \
+  -H 'Content-Type: application/json' -d '{"query":"write a failing test first"}'
+```
+
+You should see `"mode":"semantic"` and a list of skills. Then check Node is 18 or newer
+(`node --version`), and that you restarted your agent after installing.
+
+**Only very long prompts get skills.** Prompts under 24 characters are skipped on
+purpose. Set `JERRY_MIN_PROMPT_CHARS` lower to change that.
+
+## Privacy
+
+Your prompt is sent to the JERRY API to search the library. It is not stored: the
+ledger keeps a SHA-256 hash so usage can be grouped for author payouts without keeping
+what you typed.
+
+## License
+
+MIT

package/mcp/jerry-mcp.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * JERRY skills MCP server.
+ *
+ * Two tools, matching the two stages of retrieval:
+ *   jerry_find_skills  - cheap index of candidates, bills nothing
+ *   jerry_load_skill   - full instructions for one id, bills its author
+ *
+ * Deliberately dependency-free. MCP over stdio is JSON-RPC 2.0 with newline
+ * framing, which is about eighty lines; pulling in an SDK would make `npx
+ * jerry-skills-mcp` a package install on every cold start for no capability.
+ *
+ * Works in any MCP client: Claude Code, Codex, Gemini CLI, Claude Desktop, Cursor.
+ */
+import { createInterface } from 'node:readline';
+
+const API = (process.env.JERRY_API_URL || 'https://jerry.viktronconsulting.com').replace(/\/$/, '');
+const TIMEOUT_MS = Number(process.env.JERRY_TIMEOUT_MS || 10000);
+const CLIENT = process.env.JERRY_CLIENT || 'mcp';
+const SESSION = process.env.JERRY_SESSION_ID || `mcp-${process.pid}-${Date.now()}`;
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+/** Remembers the last search so a load can be attributed back to it. */
+const lastSearch = { queryHash: '', similarity: new Map() };
+
+async function api(path, body) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const response = await fetch(`${API}${path}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(process.env.JERRY_API_KEY
+          ? { Authorization: `Bearer ${process.env.JERRY_API_KEY}` }
+          : {}),
+      },
+      signal: controller.signal,
+      body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`${path} returned non-JSON (HTTP ${response.status}): ${text.slice(0, 200)}`);
+    }
+    if (!response.ok) throw new Error(json.error || `${path} failed with HTTP ${response.status}`);
+    return json;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const TOOLS = [
+  {
+    name: 'jerry_find_skills',
+    description:
+      'Search the JERRY marketplace for community skills relevant to the current task. ' +
+      'Returns a short list of candidates with one-line summaries and their ids. ' +
+      'This is free and loads nothing into context beyond the list; call jerry_load_skill ' +
+      'to get the actual instructions for one you want to use.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'What you are trying to do, in a sentence. More specific beats shorter.',
+        },
+        limit: { type: 'number', description: 'Max candidates to return (1-20, default 5).' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'jerry_load_skill',
+    description:
+      'Load the full instructions for one skill by id, from a prior jerry_find_skills result. ' +
+      'This credits a royalty to the skill author, so load a skill you intend to follow, ' +
+      'not one you are merely curious about.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Skill id exactly as jerry_find_skills returned it.' },
+      },
+      required: ['id'],
+    },
+  },
+];
+
+async function callTool(name, args) {
+  if (name === 'jerry_find_skills') {
+    const result = await api('/api/jerry/skills/index', {
+      query: args.query,
+      sessionId: SESSION,
+      client: CLIENT,
+      limit: args.limit ?? 5,
+    });
+
+    lastSearch.queryHash = result.queryHash || '';
+    lastSearch.similarity = new Map((result.skills || []).map((s) => [s.id, s.similarity]));
+
+    if (!result.skills?.length) {
+      return 'No marketplace skill matched this task. Proceed without one.';
+    }
+
+    const lines = result.skills.map(
+      (s) => `${s.id}  [${s.author}, match ${s.similarity}]  ${s.name} - ${s.summary}`
+    );
+    const note =
+      result.mode === 'lexical-fallback'
+        ? '\n\n(Vector index unreachable; this is a keyword fallback over built-in skills only.)'
+        : '';
+    return (
+      `${result.skills.length} candidate skill(s). Call jerry_load_skill with an id to use one:\n\n` +
+      lines.join('\n') +
+      note
+    );
+  }
+
+  if (name === 'jerry_load_skill') {
+    const result = await api('/api/jerry/skills/load', {
+      id: args.id,
+      sessionId: SESSION,
+      client: CLIENT,
+      queryHash: lastSearch.queryHash,
+      similarity: lastSearch.similarity.get(args.id) ?? null,
+    });
+
+    // Never claim a payment the server did not record.
+    const credit =
+      result.ledger === 'recorded'
+        ? `Royalty $${result.royaltyCharged} credited to ${result.author}.`
+        : result.ledger === 'duplicate'
+          ? `Already loaded in this session; ${result.author} was not charged again.`
+          : `Royalty $${result.royaltyPending} owed to ${result.author} but NOT recorded (ledger write failed).`;
+
+    return (
+      `${result.name} v${result.version} by ${result.author}\n` +
+      `${credit}\n\n${result.instructions}`
+    );
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+function respond(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function fail(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function handle(request) {
+  const { id, method, params } = request;
+
+  // Notifications carry no id and must never be answered.
+  if (id === undefined || id === null) return;
+
+  switch (method) {
+    case 'initialize':
+      return respond(id, {
+        protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'jerry-skills', version: '0.1.0' },
+      });
+    case 'tools/list':
+      return respond(id, { tools: TOOLS });
+    case 'tools/call':
+      try {
+        const text = await callTool(params?.name, params?.arguments ?? {});
+        return respond(id, { content: [{ type: 'text', text }] });
+      } catch (error) {
+        // Reported as tool output, not as a protocol error: the model should see
+        // why the marketplace was unavailable and carry on without it.
+        return respond(id, {
+          content: [{ type: 'text', text: `JERRY unavailable: ${error.message}` }],
+          isError: true,
+        });
+      }
+    case 'ping':
+      return respond(id, {});
+    default:
+      return fail(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+createInterface({ input: process.stdin }).on('line', (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let request;
+  try {
+    request = JSON.parse(trimmed);
+  } catch {
+    return fail(null, -32700, 'Parse error');
+  }
+  handle(request).catch((error) => fail(request?.id ?? null, -32603, error.message));
+});

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "jerry-skills-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the JERRY skill marketplace: semantic search over community agent skills, loaded on demand and metered so authors get paid.",
+  "type": "module",
+  "bin": { "jerry-skills-mcp": "mcp/jerry-mcp.mjs" },
+  "files": ["mcp", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["mcp", "model-context-protocol", "skills", "agent", "claude", "codex", "gemini"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/vikasvardhanv/jerry-plugin.git" }
+}