create-futurity-plugin 1.0.0 → 1.1.0

package/index.ts

@@ -1,7 +1,16 @@
 #!/usr/bin/env bun
-import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { resolve, basename } from "node:path";
 import { execSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
 
 const arg = process.argv[2];
 
@@ -15,6 +24,13 @@ const isCwd = arg === ".";
 const targetDir = isCwd ? process.cwd() : resolve(process.cwd(), arg);
 const projectName = isCwd ? basename(process.cwd()) : arg;
 
+/** A plugin id is a URL-safe slug, so it is derived rather than asked for. */
+const slug =
+  projectName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "my-plugin";
+
 if (!isCwd) {
   if (existsSync(targetDir)) {
     console.error(`Error: Directory "${arg}" already exists.`);
@@ -23,26 +39,51 @@ if (!isCwd) {
   mkdirSync(targetDir, { recursive: true });
 }
 
-// Copy template files
 const templateDir = resolve(import.meta.dirname, "template");
 cpSync(templateDir, targetDir, { recursive: true });
 
-// Process package.json template
-const pkgPath = resolve(targetDir, "package.json.tmpl");
-const pkgContent = readFileSync(pkgPath, "utf-8");
-writeFileSync(
-  resolve(targetDir, "package.json"),
-  pkgContent.replace(/\{\{name\}\}/g, projectName)
-);
-unlinkSync(pkgPath);
+// npm strips a .gitignore from a published tarball and never unpacks a .env
+// file, so both ship under a plain name and are restored here.
+const renames: [from: string, to: string][] = [
+  ["package.json.tmpl", "package.json"],
+  ["_gitignore", ".gitignore"],
+  ["env.example", ".env.example"],
+];
+for (const [from, to] of renames) {
+  const source = join(targetDir, from);
+  if (existsSync(source)) renameSync(source, join(targetDir, to));
+}
+
+const TEXT_FILE = /\.(ts|json|md|example)$|^\.(gitignore|env\.example)$/;
+
+function fillPlaceholders(dir: string) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules") continue;
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      fillPlaceholders(path);
+      continue;
+    }
+    if (!TEXT_FILE.test(entry)) continue;
+
+    const content = readFileSync(path, "utf-8");
+    if (!content.includes("{{")) continue;
+    writeFileSync(
+      path,
+      content.replace(/\{\{name\}\}/g, projectName).replace(/\{\{slug\}\}/g, slug),
+    );
+  }
+}
+fillPlaceholders(targetDir);
 
-// Install dependencies
 console.log(`\nScaffolding ${projectName}...\n`);
 execSync("bun install", { cwd: targetDir, stdio: "inherit" });
 
 console.log(`\n✅ Created ${projectName}\n`);
 console.log("Next steps:\n");
-if (!isCwd) {
-  console.log(`  cd ${arg}`);
-}
-console.log("  bun run src/index.ts\n");
+if (!isCwd) console.log(`  cd ${arg}`);
+console.log("  cp .env.example .env");
+console.log("  bun run keygen          # put the private key in .env");
+console.log("  bun run dev             # serves on :3000\n");
+console.log("Then write your tools in src/index.ts, and exchange your own");
+console.log("credentials in the token endpoint in src/auth.ts.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-futurity-plugin",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Scaffold a new Futurity MCP plugin",
   "author": "Futurity",
@@ -11,7 +11,10 @@
   "scripts": {
     "test": "echo 'No tests'"
   },
-  "files": ["index.ts", "template"],
+  "files": [
+    "index.ts",
+    "template"
+  ],
   "keywords": [
     "create",
     "scaffold",

package/template/README.md

@@ -0,0 +1,51 @@
+# {{name}}
+
+A Futurity MCP plugin. It serves tools over MCP, and a signed manifest that
+Futurity checks before it trusts them.
+
+## Run it
+
+```bash
+cp .env.example .env
+bun run keygen          # writes a keypair; put the private half in .env
+bun run dev             # http://localhost:3000/mcp
+```
+
+With `FUTURITY_SIGNING_KEY` set, the manifest is served at
+`/.well-known/futurity/plugin` with its detached signature in the
+`X-Futurity-Signature` header:
+
+```bash
+curl -i http://localhost:3000/.well-known/futurity/plugin
+```
+
+## Register it
+
+1. Put the plugin on a public HTTPS address and set `PUBLIC_URL` to match.
+   While you develop: `cloudflared tunnel --url http://localhost:3000`.
+2. In Corint, open **Integrations → Developer Tools → Add**, paste the base
+   URL (not the `/mcp` path), and click **Discover**.
+3. Paste the public key from `bun run keygen` and click **Register Plugin**.
+   The signature is verified at that moment.
+
+Registration needs plugin developer access on your account. Futurity
+re-verifies the manifest every 24 hours, so keep the address stable.
+
+## Connect it
+
+This plugin declares the `client_credentials` grant, so one set of credentials
+belongs to the whole organization and an administrator saves them once. They
+land at your `/oauth/token` endpoint in `src/auth.ts`; whatever `access_token`
+you return there arrives on every tool call as `X-Plugin-Access-Token`, and
+`requireAccessToken()` hands it to your handler.
+
+Other grants — per-person OAuth, SAML bearer, an API key, or your own auth
+flow — are in the plugin authentication reference.
+
+## Where to edit
+
+| File | What lives there |
+| --- | --- |
+| `src/index.ts` | The manifest, the middleware wiring, and your tools |
+| `src/auth.ts` | The token endpoint and the per-request credentials |
+| `scripts/keygen.ts` | The Ed25519 keypair generator |

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store

package/template/env.example

@@ -0,0 +1,10 @@
+# Ed25519 private key that signs the plugin manifest. Generate with `bun run keygen`.
+# Without it the server still runs, but it serves no manifest and cannot be registered.
+FUTURITY_SIGNING_KEY=
+
+# The address Futurity reaches this plugin on. Must be public HTTPS before you
+# register — a quick tunnel works while you develop:
+#   cloudflared tunnel --url http://localhost:3000
+PUBLIC_URL=http://localhost:3000
+
+PORT=3000

package/template/package.json.tmpl

@@ -1,10 +1,11 @@
 {
-  "name": "{{name}}",
+  "name": "{{slug}}",
   "version": "0.1.0",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",
-    "start": "bun run src/index.ts"
+    "start": "bun run src/index.ts",
+    "keygen": "bun run scripts/keygen.ts"
   },
   "dependencies": {
     "@futurity/plugins": "^2.0.0"

package/template/scripts/keygen.ts

@@ -0,0 +1,8 @@
+import { generateKeyPair } from "@futurity/plugins/signing";
+
+const { privateKey, publicKey } = generateKeyPair();
+
+console.log("\nPrivate key (PKCS8 DER, base64) — keep secret, put it in .env:\n");
+console.log(`FUTURITY_SIGNING_KEY=${privateKey}\n`);
+console.log("Public key (SPKI DER, base64) — paste this into Futurity when you register:\n");
+console.log(`${publicKey}\n`);

package/template/src/auth.ts

@@ -0,0 +1,91 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Middleware } from "@futurity/plugins";
+
+/**
+ * Futurity sends two credentials on every tool call. `Authorization` carries
+ * Futurity's own short-lived token, which identifies the platform. The token
+ * your API cares about is in `X-Plugin-Access-Token`, and any extra fields the
+ * administrator filled in ride along as JSON in `X-Futurity-Data-Params`.
+ */
+export type PluginRequest = {
+  accessToken: string | null;
+  dataParams: Record<string, string>;
+};
+
+const store = new AsyncLocalStorage<PluginRequest>();
+
+/**
+ * The credentials for the call being served. Tool handlers receive their input
+ * only, so the request travels here instead of through an argument.
+ */
+export function currentRequest(): PluginRequest {
+  return store.getStore() ?? { accessToken: null, dataParams: {} };
+}
+
+/** The forwarded token, or a thrown error when the caller sent none. */
+export function requireAccessToken(): string {
+  const { accessToken } = currentRequest();
+  if (!accessToken) {
+    throw new Error(
+      "No X-Plugin-Access-Token on this request. Connect the integration in Futurity first.",
+    );
+  }
+  return accessToken;
+}
+
+function parseDataParams(raw: string | null): Record<string, string> {
+  if (!raw) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return {};
+    return Object.fromEntries(
+      Object.entries(parsed as Record<string, unknown>).filter(
+        (entry): entry is [string, string] => typeof entry[1] === "string",
+      ),
+    );
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Bind each request's credentials for the duration of that request. An async
+ * store rather than a module variable, so overlapping calls cannot read each
+ * other's token.
+ */
+export const forwardedAuth: Middleware = (req, next) =>
+  store.run(
+    {
+      accessToken: req.headers.get("X-Plugin-Access-Token"),
+      dataParams: parseDataParams(req.headers.get("X-Futurity-Data-Params")),
+    },
+    () => next(req),
+  );
+
+/**
+ * The `client_credentials` token endpoint named by the manifest. Futurity posts
+ * the credentials an administrator saved, caches what you return until shortly
+ * before `expires_in`, and forwards `access_token` on every tool call.
+ */
+export const tokenEndpoint = (path: string): Middleware => {
+  return async (req, next) => {
+    if (new URL(req.url).pathname !== path) return next(req);
+    if (req.method !== "POST") return next(req);
+
+    const form = await req.formData();
+    const clientId = String(form.get("client_id") ?? "");
+    const clientSecret = String(form.get("client_secret") ?? "");
+
+    if (!clientId || !clientSecret) {
+      return Response.json({ error: "invalid_client" }, { status: 401 });
+    }
+
+    // YOUR CODE HERE: exchange these credentials with the system you wrap, and
+    // return its token. The stub below lets the whole flow run end to end first.
+    return Response.json({
+      access_token: `${clientId}-demo-token`,
+      token_type: "Bearer",
+      expires_in: 3600,
+    });
+  };
+};

package/template/src/index.ts

@@ -1,16 +1,68 @@
-import { mcp, t } from "@futurity/plugins";
+import { cors, mcp, t } from "@futurity/plugins";
+import type { PluginManifestOptions } from "@futurity/plugins";
+import { forwardedAuth, requireAccessToken, tokenEndpoint } from "./auth";
+
+const PORT = Number(process.env.PORT ?? 3000);
+
+// Futurity reads the manifest and calls the tools from its own servers, so the
+// URLs the manifest publishes must be the ones Futurity can reach.
+const PUBLIC_URL = process.env.PUBLIC_URL ?? `http://localhost:${PORT}`;
+const TOKEN_PATH = "/oauth/token";
+
+const signingKey = process.env.FUTURITY_SIGNING_KEY;
+if (!signingKey) {
+  console.warn(
+    "FUTURITY_SIGNING_KEY is not set, so /.well-known/futurity/plugin is not served.\n" +
+      "Run `bun run keygen`, put the private key in .env, and restart to register this plugin.",
+  );
+}
+
+const manifest: PluginManifestOptions | undefined = signingKey
+  ? {
+      specVersion: 2,
+      pluginId: "{{slug}}",
+      name: "{{name}}",
+      version: "0.1.0",
+      mcpUrl: `${PUBLIC_URL}/mcp`,
+      auth: {
+        type: "forwarding",
+        grantType: "client_credentials",
+        tokenEndpoint: `${PUBLIC_URL}${TOKEN_PATH}`,
+        requiredScopes: [],
+        deliveryMethod: "header",
+      },
+      signingKey,
+    }
+  : undefined;
 
 const app = mcp({
-  name: "my-plugin",
+  name: "{{slug}}",
   version: "0.1.0",
+  pluginManifest: manifest,
 });
 
+app.use(cors()).middleware(tokenEndpoint(TOKEN_PATH)).middleware(forwardedAuth);
+
+// A tool is a name, a description, an input schema, and a handler. The agent
+// reads the description alone when it chooses a tool, so write it as *when to
+// use this*, not as what it does internally.
 app.tool("hello", {
-  description: "Say hello",
+  description: "Use when someone asks this plugin to greet a person by name.",
   input: t.obj({ name: t.str }),
-  handler: async ({ name }) => ({
-    greeting: `Hello, ${name}!`,
-  }),
+  handler: async ({ name }) => ({ greeting: `Hello, ${name}!` }),
+});
+
+// Delete this one once your own tools call a real API. `requireAccessToken()`
+// returns the credential Futurity forwarded for the caller.
+app.tool("whoami", {
+  description:
+    "Use to prove the connection works. Returns the identity behind the forwarded credentials.",
+  input: t.obj({}),
+  handler: async () => {
+    const token = requireAccessToken();
+    // YOUR CODE HERE: call the system you wrap with this token.
+    return { connected: true, tokenPreview: `${token.slice(0, 6)}…` };
+  },
 });
 
-await app.listen(3000);
+await app.listen(PORT);