@vantageos/mcp-boilerplate 0.1.2 → 0.2.1

package/scripts/generate-signing-key.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Prints a fresh RS256 private JWK on stdout, ready to be stored as the MCP_OAUTH_SIGNING_JWK
+ * secret of the authorization server. The key id is the RFC 7638 thumbprint, so it is derived,
+ * never typed. Nothing is written to disk; pipe it straight into your secret manager.
+ */
+import { calculateJwkThumbprint, exportJWK, generateKeyPair } from "jose";
+
+const { privateKey } = await generateKeyPair("RS256", { modulusLength: 3072, extractable: true });
+const jwk = await exportJWK(privateKey);
+jwk.kid = await calculateJwkThumbprint(jwk);
+jwk.alg = "RS256";
+jwk.use = "sig";
+process.stdout.write(`${JSON.stringify(jwk)}\n`);

package/scripts/plugin-manifest.source.json

@@ -0,0 +1,35 @@
+{
+  "serverName": "mcp-boilerplate",
+  "pluginName": "vantage-mcp-boilerplate",
+  "displayName": "VantageOS MCP Boilerplate",
+  "serverUrlPlaceholder": "https://your-server.example.com/mcp",
+  "urlEnvVar": "MCP_BOILERPLATE_URL",
+  "onboardingSkill": "skills/connect-mcp-server/SKILL.md",
+  "category": "mcp-server",
+  "bilingual": true,
+  "description": {
+    "en": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
+    "fr": "Template de serveur MCP clonable : SDK v2 sur le protocole 2026-07-28 (stdio + Streamable HTTP sans état), serveur d'autorisation OAuth 2.1 propre (personne + organisation Clerk), UI MCP Apps, i18n FR/EN et un harnais d'évaluations déclaratif. Scaffolder, étendre, publier."
+  },
+  "shortDescription": "Clonable MCP server template with OAuth 2.1, MCP Apps UI and FR/EN i18n.",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "chatgpt",
+    "boilerplate",
+    "starter",
+    "template",
+    "stdio",
+    "streamable-http",
+    "oauth",
+    "multi-tenant",
+    "mcp-apps",
+    "i18n",
+    "vantage",
+    "elpi"
+  ],
+  "openai": {
+    "auth": { "type": "oauth", "client": { "mode": "cimd" } },
+    "capabilities": ["Read"]
+  }
+}

package/skills/connect-mcp-server/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: connect-mcp-server
+description: Connect this MCP server to Claude Code, ChatGPT or any MCP client, and check the connection works. Use when the user says "connect the server", "set up the MCP boilerplate", "add this MCP server", or reports that the tools do not appear.
+---
+
+# Connect the MCP boilerplate server
+
+This plugin ships one MCP server (`mcp-boilerplate`) with three tools: `ping`, `list_items`
+and `render_items_ui`. Follow the path that matches where it runs.
+
+## 1. Pick the transport
+
+- **Local (stdio)**: no account, no network. Run `npx -y @vantageos/mcp-boilerplate` as the
+  server command. The caller is the local process, so there is no sign-in.
+- **Remote (Streamable HTTP)**: a deployed server at `https://<your-host>/mcp`. It signs the
+  person in with Clerk and asks them to pick an organisation before any tool works.
+
+## 2. Connect a remote server
+
+1. Take the server URL from the deployment. The plugin reads it from `MCP_BOILERPLATE_URL`
+   (Claude Code) or from `mcp.json` (ChatGPT); the shipped value is a placeholder.
+2. In Claude Code, export the variable, then reload the plugin:
+   `export MCP_BOILERPLATE_URL=https://<your-host>/mcp`.
+3. Start the connection. A browser window opens: sign in, choose the organisation, approve.
+4. A client that publishes a Client ID Metadata Document connects directly; any other client
+   registers itself on the server's `/register` endpoint first. Nothing to configure by hand.
+
+## 3. Check it works
+
+1. Call `ping`. The reply is `pong`.
+2. Call `list_items`. A signed-in person sees only the items of the chosen organisation.
+3. Call `render_items_ui`. A host that supports MCP Apps shows the widget; any other host
+   shows the markdown list that comes with the result.
+
+## If something fails
+
+- `503 temporarily_unavailable` on sign-in: the server is missing configuration. The names of
+  the missing variables are in the server log (never the values).
+- `401` on `/mcp`: the token expired or was minted for another server. Reconnect.
+- Tools missing: the client has not reloaded. Reload the plugin or restart the client.