@faable/faable 4.4.0 → 4.5.0

package/dist/api/context.js

@@ -10,12 +10,19 @@ import { CliError, NOT_LOGGED_IN } from '../lib/errors.js';
 
 const context = async (targetAppId) => {
     let api;
-    // Auth resolution: FAABLE_TOKEN → OIDC (CI) → local `faable login` credentials.
+    // Auth resolution: FAABLE_TOKEN → FAABLE_API_KEY → OIDC (CI) → local
+    // `faable login` credentials.
     if (process.env.FAABLE_TOKEN) {
         // Token in environment
         const token = process.env.FAABLE_TOKEN;
         api = FaableApi.create({ authStrategy: bearer_strategy, auth: { token } });
     }
+    else if (process.env.FAABLE_API_KEY) {
+        // A dashboard API key, scoped to its project — how the hosted MCP server
+        // (`faable mcp --http`) runs each call with the caller's own key.
+        const apikey = process.env.FAABLE_API_KEY;
+        api = FaableApi.create({ authStrategy: apikey_strategy, auth: { apikey } });
+    }
     else if (process.env.GITHUB_ACTIONS === "true") {
         // Github actions environment
         try {

package/dist/api/project.js

@@ -1,4 +1,5 @@
 import { ContextStore } from '../lib/ContextStore.js';
+import { CliError } from '../lib/errors.js';
 
 let flag_value;
 // Set by the global middleware in src/index.ts.
@@ -50,7 +51,7 @@ const requireProject = async (api, store = new ContextStore(), env = process.env
     if (page.results.length === 1 && !page.next) {
         return { id: page.results[0].id, source: 'only' };
     }
-    throw new Error('No project selected. Pick one with: faable project use <id|name> (list them with: faable project list), or pass --project <id|name>.');
+    throw new CliError('project_required', 'No project selected. Pick one with: faable project use <id|name> (list them with: faable project list), or pass --project <id|name>.');
 };
 const SOURCE_LABEL = {
     flag: '--project',

package/dist/commands/mcp/index.js

@@ -1,26 +1,44 @@
+import { serve_http } from '../../mcp/http.js';
 import { serve_stdio } from '../../mcp/server.js';
 
-// `faable mcp` — this CLI as an MCP server, over stdio, for Claude Code,
-// Cursor and any MCP client:
+// `faable mcp` — this CLI as an MCP server, for Claude Code, Cursor and any
+// MCP client.
 //
-//   claude mcp add faable -- npx -y @faable/faable mcp
+//   claude mcp add faable -- npx -y @faable/faable mcp          (stdio, local)
+//   faable mcp --http --port 8080                               (mcp.faable.com)
 //
-// It acts with the `faable login` session (or FAABLE_TOKEN), and every tool is
-// one run of this same CLI (src/mcp/run_cli.ts). stdout is the protocol from
-// here on: nothing else may print there.
+// stdio acts with the `faable login` session (or FAABLE_TOKEN); --http with
+// each caller's API key (src/mcp/http.ts). Every tool is one run of this same
+// CLI (src/mcp/run_cli.ts). Over stdio, stdout is the protocol: nothing else
+// may print there.
 const mcp = {
     command: 'mcp',
-    describe: 'Run the Faable MCP server (stdio) for AI agents and editors',
+    describe: 'Run the Faable MCP server for AI agents and editors (stdio, or --http)',
     builder: yargs => yargs
         .option('writes', {
         type: 'boolean',
         default: false,
-        description: 'Also expose the reversible writes: create apps, set secrets, add domains, retry or cancel builds, change deploy settings'
+        description: 'Also expose the reversible writes: create apps, set secrets, add domains, retry or cancel builds, change deploy settings (over HTTP: ?mode=write)'
+    })
+        .option('http', {
+        type: 'boolean',
+        default: false,
+        description: 'Serve Streamable HTTP for remote clients, authenticated per request with a Faable API key'
+    })
+        .option('port', {
+        type: 'number',
+        default: Number(process.env.PORT) || 8080,
+        description: 'With --http: the port (env PORT)'
     })
         .example('claude mcp add faable -- npx -y @faable/faable mcp', 'Add it to Claude Code (read-only + deploy)')
         .example('claude mcp add faable -- npx -y @faable/faable mcp --writes', 'With the reversible writes')
+        .example('$0 mcp --http --port 8080', 'Host it (what runs at mcp.faable.com)')
         .showHelpOnFail(false),
     handler: async (args) => {
+        if (args.http) {
+            await serve_http({ port: args.port ?? 8080 });
+            return;
+        }
         await serve_stdio({ writes: args.writes });
     }
 };

package/dist/commands/whoami/index.js

@@ -1,7 +1,8 @@
 import { getMe } from '../../api/auth.js';
 import { resolveTenant } from '../../api/auth_admin.js';
 import { FaableApi } from '../../api/FaableApi.js';
-import { SOURCE_LABEL, requireProject } from '../../api/project.js';
+import { requireApi } from '../../api/context.js';
+import { requireProject, SOURCE_LABEL } from '../../api/project.js';
 import { loadLiveCredentials } from '../../api/session.js';
 import { bearer_strategy } from '../../api/strategies/bearer.strategy.js';
 import { CredentialsStore } from '../../lib/CredentialsStore.js';
@@ -41,6 +42,25 @@ const whoami = {
         const config = await loadLiveCredentials(store);
         // Bearer token from the environment (CI) or a local `faable login`.
         const token = process.env.FAABLE_TOKEN || config?.token;
+        // An API key from the environment (the hosted MCP server). It cannot be
+        // introspected at /me, and it acts with its owner's access — not only on
+        // the project it was created in — so the project is whatever this call
+        // pinned, if anything.
+        if (!token && process.env.FAABLE_API_KEY) {
+            const { api } = await requireApi();
+            const project = await requireProject(api)
+                .then(async ({ id, source }) => ({
+                id,
+                name: (await api.getProject(id).catch(() => undefined))?.name,
+                source,
+            }))
+                .catch(() => null);
+            if (args.json)
+                return print_json({ credential: "apikey", project });
+            print("Logged in with: an API key");
+            print(`Project:      ${project ? `${project.name ?? ""} (${project.id})` : "none — pass --project"}`);
+            return;
+        }
         if (!token) {
             // API-key sessions can't be introspected at the auth server's /me; fall
             // back to the email captured at login time.

package/dist/mcp/http.js

@@ -0,0 +1,258 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { version } from '../config.js';
+import { run_cli } from './run_cli.js';
+import { tools_for, create_server } from './server.js';
+import { TOOLS } from './tools.js';
+
+// `faable mcp --http` — the hosted Faable MCP server (Fase 2 of
+// arch/deploy/mcp-server-faable.md), what runs at mcp.faable.com.
+//
+// Streamable HTTP, stateless: every POST /mcp builds a server and a transport
+// for that one request, so any instance can answer anything. The caller
+// authenticates with a Faable API key (dashboard → project settings → API
+// keys). ⚠️ A key acts with its OWNER's access, not only on the project it was
+// created in (arch/deploy/mcp-cli-gaps.md) — /mcp/<project> is how a caller
+// narrows it. Each tool call runs the CLI as a child
+// with THAT key in its environment and an empty HOME of its own — two
+// callers' credentials never meet in one process, and the key is never
+// logged.
+//
+//   POST /mcp              everything the key's owner can see
+//   POST /mcp/<project>    pinned to one project (id, name or slug)
+//   ?mode=write            also the reversible writes
+//   ?readonly=1            reads only — not even deploy_app
+const PUBLIC_URL = 'https://mcp.faable.com';
+const DOCS_URL = 'https://faable.com/docs/cli#mcp-server';
+const KEYS_URL = 'https://dashboard.faable.com/settings/projects';
+const MAX_BODY_BYTES = 1024 * 1024;
+// `Authorization: Bearer <key>`, or Basic with the key as the user (what the
+// api itself accepts). Anything else is no credential.
+const api_key_of = (req) => {
+    const header = req.headers.authorization ?? '';
+    const bearer = /^Bearer\s+(\S+)$/i.exec(header);
+    let key = bearer?.[1];
+    const basic = /^Basic\s+(\S+)$/i.exec(header);
+    if (!key && basic) {
+        key = Buffer.from(basic[1], 'base64').toString('utf8').split(':')[0];
+    }
+    return key && /^[\w.~+/=-]{8,256}$/.test(key) ? key : null;
+};
+// /mcp → {}, /mcp/<project> → { project }; anything else → null.
+const route_of = (pathname) => {
+    const m = /^\/mcp(?:\/([^/]+))?\/?$/.exec(pathname);
+    if (!m)
+        return null;
+    return m[1] ? { project: decodeURIComponent(m[1]) } : {};
+};
+// The environment of one call: the server's own, minus every credential and
+// context it might carry, plus the caller's key and an empty HOME.
+const SCRUBBED = /^(FAABLE_(TOKEN|API_KEY|PROJECT|AUTH_ACCOUNT|AUTH_URL|ID_TOKEN)|GITHUB_ACTIONS|ACTIONS_ID_TOKEN_.*)$/;
+const child_env = (key, home) => {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (!SCRUBBED.test(k))
+            env[k] = v;
+    }
+    return { ...env, HOME: home, FAABLE_API_KEY: key };
+};
+// At most `max` children at once.
+const limiter = (max) => {
+    let active = 0;
+    const waiting = [];
+    return async (fn) => {
+        if (active >= max)
+            await new Promise(r => waiting.push(r));
+        active++;
+        try {
+            return await fn();
+        }
+        finally {
+            active--;
+            waiting.shift()?.();
+        }
+    };
+};
+const runner_for = (key, limit, entry) => (argv, opts) => limit(async () => {
+    const home = await mkdtemp(path.join(os.tmpdir(), 'faable-mcp-'));
+    try {
+        return await run_cli(argv, {
+            ...opts,
+            entry,
+            env: child_env(key, home)
+        });
+    }
+    finally {
+        await rm(home, { recursive: true, force: true });
+    }
+});
+const send = (res, status, body, type = 'application/json') => {
+    res.writeHead(status, {
+        'content-type': type === 'application/json' ? 'application/json; charset=utf-8' : type,
+        'cache-control': 'no-store'
+    });
+    res.end(type === 'application/json' ? JSON.stringify(body) : String(body));
+};
+const read_body = (req) => new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+        size += c.length;
+        if (size > MAX_BODY_BYTES) {
+            reject(new Error('body too large'));
+            req.destroy();
+        }
+        else
+            chunks.push(c);
+    });
+    req.on('end', () => {
+        try {
+            resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || 'null'));
+        }
+        catch {
+            reject(new Error('invalid JSON'));
+        }
+    });
+    req.on('error', reject);
+});
+const rpc_error = (code, message) => ({
+    jsonrpc: '2.0',
+    error: { code, message },
+    id: null
+});
+// The catalog as data: the landing (faable.com/mcp) and MCP directories read
+// it, so the published list is always the served one.
+const catalog = (base = PUBLIC_URL) => ({
+    name: 'faable',
+    version,
+    endpoint: `${base}/mcp`,
+    transport: 'streamable-http',
+    auth: {
+        type: 'api-key',
+        header: 'Authorization: Bearer <key>',
+        keys: KEYS_URL
+    },
+    docs: DOCS_URL,
+    tools: TOOLS.map(t => ({
+        name: t.name,
+        title: t.title,
+        description: t.description,
+        access: t.annotations.readOnlyHint ? 'read' : t.write ? 'write' : 'deploy',
+        requires: t.write ? 'mode=write' : undefined,
+        input_schema: z.toJSONSchema(z.object(t.input))
+    }))
+});
+const llms_txt = (base = PUBLIC_URL) => [
+    '# Faable MCP server',
+    '',
+    '> Connects Claude, Cursor and any MCP client to Faable Deploy: read apps, deployments, build and runtime logs, traffic and domains, and deploy — without leaving the editor.',
+    '',
+    `Endpoint: ${base}/mcp (Streamable HTTP). Authenticate with a Faable API key: \`Authorization: Bearer <key>\` (create one in the dashboard, project settings → API keys). The key acts with its owner's access; connect to \`${base}/mcp/<project>\` to keep every call in one project.`,
+    '',
+    `- \`${base}/mcp/<project>\` pins every call to one project.`,
+    '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings). Nothing destructive is exposed.',
+    '- `?readonly=1` exposes reads only.',
+    '- Local alternative, no key: `npx -y @faable/faable mcp` (uses `faable login`).',
+    '',
+    '## Tools',
+    '',
+    ...TOOLS.map(t => `- \`${t.name}\`${t.write ? ' (mode=write)' : ''}: ${t.description}`),
+    '',
+    `Docs: ${DOCS_URL}`,
+    ''
+].join('\n');
+const create_http_server = (opts) => {
+    const limit = limiter(opts.max_concurrent ?? 8);
+    const base = opts.base_url ?? PUBLIC_URL;
+    return http.createServer(async (req, res) => {
+        const started = Date.now();
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        let status = 200;
+        const done = () => 
+        // One line per request, never the key nor the body.
+        process.stderr.write(JSON.stringify({
+            msg: 'mcp_http',
+            method: req.method,
+            path: url.pathname.replace(/^\/mcp\/.+/, '/mcp/:project'),
+            status: res.statusCode || status,
+            ms: Date.now() - started
+        }) + '\n');
+        res.on('finish', done);
+        try {
+            if (req.method === 'GET' &&
+                (url.pathname === '/healthz' || url.pathname === '/livez')) {
+                return send(res, 200, { ok: true, version });
+            }
+            if (req.method === 'GET' && url.pathname === '/') {
+                res.writeHead(302, { location: DOCS_URL });
+                return res.end();
+            }
+            if (req.method === 'GET' && url.pathname === '/tools.json') {
+                return send(res, 200, catalog(base));
+            }
+            if (req.method === 'GET' && url.pathname === '/llms.txt') {
+                return send(res, 200, llms_txt(base), 'text/plain; charset=utf-8');
+            }
+            const route = route_of(url.pathname);
+            if (!route)
+                return send(res, 404, { error: 'not found', docs: DOCS_URL });
+            if (req.method !== 'POST') {
+                // Stateless: no server-initiated stream, no session to delete.
+                res.setHeader('allow', 'POST');
+                return send(res, 405, rpc_error(-32000, 'Method not allowed: this server is stateless, use POST.'));
+            }
+            const key = api_key_of(req);
+            if (!key) {
+                res.setHeader('www-authenticate', 'Bearer realm="faable"');
+                status = 401;
+                return send(res, 401, rpc_error(-32001, `Send a Faable API key: "Authorization: Bearer <key>". Create one in the dashboard (project settings → API keys): ${KEYS_URL}`));
+            }
+            let body;
+            try {
+                body = await read_body(req);
+            }
+            catch (e) {
+                return send(res, 400, rpc_error(-32700, e.message));
+            }
+            const server = create_server({
+                writes: url.searchParams.get('mode') === 'write',
+                readonly: ['1', 'true'].includes(url.searchParams.get('readonly') ?? ''),
+                project: route.project,
+                run: runner_for(key, limit, opts.entry)
+            });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true
+            });
+            res.on('close', () => {
+                transport.close().catch(() => undefined);
+                server.close().catch(() => undefined);
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (e) {
+            if (!res.headersSent)
+                send(res, 500, rpc_error(-32603, 'Internal error'));
+            process.stderr.write(JSON.stringify({ msg: 'mcp_http_error', error: e.message }) +
+                '\n');
+        }
+    });
+};
+const serve_http = async (opts) => {
+    const server = create_http_server(opts);
+    await new Promise(resolve => server.listen(opts.port, opts.host ?? '0.0.0.0', resolve));
+    process.stderr.write(JSON.stringify({
+        msg: 'mcp_http_listening',
+        port: opts.port,
+        version,
+        tools: tools_for({}).length
+    }) + '\n');
+    return server;
+};
+
+export { PUBLIC_URL, api_key_of, catalog, child_env, create_http_server, llms_txt, route_of, serve_http };

package/dist/mcp/run_cli.js

@@ -1,11 +1,27 @@
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
 import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const DEFAULT_TIMEOUT_MS = 120_000;
+// import.meta.resolve where the runtime has it; where a transpiler shims
+// import.meta (tsx under a test runner), the CommonJS resolver from the
+// current directory finds the same file.
+const resolve_loader = (spec) => {
+    try {
+        if (typeof import.meta.resolve === 'function')
+            return import.meta.resolve(spec);
+    }
+    catch {
+        // fall through
+    }
+    return pathToFileURL(createRequire(path.join(process.cwd(), 'noop.js')).resolve(spec)).href;
+};
 // The child runs from the temp dir (M3), where a bare `--import tsx` (how the
 // tests and `npm run cli` start this CLI) would no longer resolve. Resolve
 // such loaders here, from the CLI's own location, before handing them on.
-const portable_exec_argv = (exec_argv = process.execArgv, resolve = spec => import.meta.resolve(spec)) => {
+const portable_exec_argv = (exec_argv = process.execArgv, resolve = resolve_loader) => {
     const bare = (spec) => !/^(\.|\/|file:|node:|data:)/.test(spec);
     return exec_argv.map((arg, i) => {
         if (exec_argv[i - 1] === '--import' && bare(arg))

package/dist/mcp/server.js

@@ -35,6 +35,7 @@ const NEXT_STEP = {
     not_found: 'Check the id or name — list_apps / list_deployments show what exists.',
     forbidden: 'This session has no access there — check the project (list_projects).',
     app_required: 'Pass `app` (id, name or slug).',
+    project_required: 'This account sees several projects: call list_projects and pass `project` (on the hosted server, connecting to /mcp/<project> pins it).',
     timeout: 'Faable did not answer in time; retry once, then tell the user.'
 };
 const error_text = (e) => {
@@ -92,7 +93,7 @@ const build_log_text = (b) => {
     ];
     return head.concat(b.content).join('\n');
 };
-const tools_for = (opts) => TOOLS.filter(t => !t.write || opts.writes);
+const tools_for = (opts) => TOOLS.filter(t => opts.readonly ? t.annotations.readOnlyHint : !t.write || opts.writes);
 const create_server = (opts = {}) => {
     const server = new McpServer({ name: 'faable', title: 'Faable', version }, { instructions: INSTRUCTIONS });
     for (const tool of tools_for(opts)) {
@@ -101,7 +102,11 @@ const create_server = (opts = {}) => {
             description: tool.description,
             inputSchema: tool.input,
             annotations: { title: tool.title, ...tool.annotations }
-        }, ((args) => call_tool(tool, args ?? {})));
+        }, ((args) => call_tool(tool, 
+        // A pinned project wins over whatever the agent passes.
+        opts.project
+            ? { ...(args ?? {}), project: opts.project }
+            : (args ?? {}), opts.run)));
     }
     return server;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",
@@ -29,7 +29,7 @@
     "@actions/core": "^3.0.0",
     "@faable/auth-sdk": "^2.7.29",
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "axios": "^1.18.1",
+    "axios": "^1.20.0",
     "fs-extra": "^11.3.2",
     "open": "^11.0.0",
     "ora": "^9.4.0",