@stackable-labs/mcp-app-extension 0.4.0 → 0.4.1

package/README.md

@@ -0,0 +1,93 @@
+# `@stackable-labs/mcp-app-extension`
+
+MCP server exposing Stackable Labs extension-platform tools to AI agents (Claude Code, etc.). Supports both **stdio** (local process, SDK self-auth via OAuth) and **streamable HTTP** (deployed Lambda, Claude Code native OAuth) transports.
+
+## Transports
+
+| Transport | Home | Auth flow | Best for |
+|-----------|------|-----------|----------|
+| **HTTP** (streamable) | Deployed at `api-{stage}-use1.stackablelabs.io/mcp/app-extension` | Claude Code native OAuth — SDK discovers `.well-known/oauth-authorization-server` via `WWW-Authenticate` header, stores token in keychain | Most users. Simplest to configure. |
+| **stdio** | Local process via `pnpm dlx @stackable-labs/mcp-app-extension@latest` | Package-level OAuth flow — spins up localhost callback listener, caches token to `~/.stackable/mcp-auth.json` | Local dev, agent orchestration outside a Claude Code keychain |
+
+Both transports expose the same tool surface: `list_apps`, `list_extensions`, `get_extension`, `list_instances`, plus SDK-only tools (`list_skills`, `lookup_skill`, `validate_manifest`, `validate_permissions`).
+
+## Claude Code `.mcp.json` config
+
+Drop into your project root (or `~/.claude.json` for user-scoped setup). Both entries can coexist — Claude Code routes tool calls per-server.
+
+**Dev (against deployed `api-dev-use1.stackablelabs.io`):**
+
+```json
+{
+  "mcpServers": {
+    "stackable-dev-http": {
+      "type": "http",
+      "url": "https://api-dev-use1.stackablelabs.io/mcp/app-extension"
+    },
+    "stackable-dev-stdio": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": [
+        "--config.dlx-cache-max-age=0",
+        "dlx",
+        "@stackable-labs/mcp-app-extension@latest"
+      ],
+      "env": {
+        "MCP_API_BASE_URL": "https://api-dev-use1.stackablelabs.io/mcp",
+        "ADMIN_API_BASE_URL": "https://api-dev-use1.stackablelabs.io/admin"
+      }
+    }
+  }
+}
+```
+
+**Prod (defaults, no env vars needed):**
+
+```json
+{
+  "mcpServers": {
+    "stackable-http": {
+      "type": "http",
+      "url": "https://api-use1.stackablelabs.io/mcp/app-extension"
+    },
+    "stackable-stdio": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": ["--config.dlx-cache-max-age=0", "dlx", "@stackable-labs/mcp-app-extension@latest"]
+    }
+  }
+}
+```
+
+## Env vars (stdio only)
+
+Both optional — defaults point at prod. Override per-stage as needed.
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `MCP_API_BASE_URL` | `https://api-use1.stackablelabs.io/mcp` | MCP host root. OAuth discovery URL is derived as `${mcpBase}/.well-known/oauth-authorization-server`. |
+| `ADMIN_API_BASE_URL` | `https://api-use1.stackablelabs.io/admin` | Admin API endpoint for platform tool calls (`list_apps`, etc.). |
+
+HTTP transport reads URLs from the deployed Lambda's env (set via CDK + `packages/infra/cdk/.env.{stage}` — not client-controlled).
+
+## Auth isolation
+
+Stdio transport stores its token at `~/.stackable/mcp-auth.json`. CLI (`@stackable-labs/cli-app-extension`) stores its token at `~/.stackable/auth.json`. The two are independent — authenticating via stdio MCP does not affect CLI auth and vice versa. HTTP transport stores its token in the Claude Code keychain, completely separate from both file-based caches.
+
+## Development
+
+```bash
+pnpm --filter @stackable-labs/mcp-app-extension build     # tsup bundle
+pnpm --filter @stackable-labs/mcp-app-extension test      # vitest
+pnpm --filter @stackable-labs/mcp-app-extension typecheck
+```
+
+To test a local build via stdio, point the `.mcp.json` `command`/`args` at the built dist:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/packages/mcp/app-extension/dist/index.js"],
+  "env": { "MCP_API_BASE_URL": "...", "ADMIN_API_BASE_URL": "..." }
+}
+```

package/dist/index.js

@@ -3759,7 +3759,7 @@ var package_default = {
 // src/server.ts
 var MCP_CLIENT_NAME = STANDALONE_CLIENT.MCP;
 var DEFAULT_ADMIN_API_URL = "https://api-use1.stackablelabs.io/admin";
-var DEFAULT_MCP_DISCOVERY_URL = "https://api-use1.stackablelabs.io/mcp/.well-known/oauth-authorization-server";
+var DEFAULT_MCP_API_BASE_URL = "https://api-use1.stackablelabs.io/mcp";
 var textContent = (text) => ({ content: [{ type: "text", text }] });
 var errorContent = (text) => ({ content: [{ type: "text", text }], isError: true });
 var createMcpServer = (options = {}) => {
@@ -3776,8 +3776,8 @@ var createMcpServer = (options = {}) => {
     } catch {
     }
     const { performOAuthFlow } = await import('./auth-AJDGAQSE.js');
-    const discoveryUrl = process.env.MCP_DISCOVERY_URL ?? DEFAULT_MCP_DISCOVERY_URL;
-    return performOAuthFlow(discoveryUrl);
+    const MCP_API_BASE_URL = process.env.MCP_API_BASE_URL ?? DEFAULT_MCP_API_BASE_URL;
+    return performOAuthFlow(`${MCP_API_BASE_URL}/.well-known/oauth-authorization-server`);
   };
   const authHeaders = (token) => ({
     authorization: `Bearer ${token}`,
@@ -3786,10 +3786,18 @@ var createMcpServer = (options = {}) => {
   });
   const callApi = async (path) => {
     const token = await getAuthToken();
-    const baseUrl = process.env.ADMIN_API_BASE_URL ?? DEFAULT_ADMIN_API_URL;
-    const res = await fetch(`${baseUrl}${path}`, { headers: authHeaders(token) });
+    const ADMIN_API_BASE_URL = process.env.ADMIN_API_BASE_URL ?? DEFAULT_ADMIN_API_URL;
+    const url = `${ADMIN_API_BASE_URL}${path}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: authHeaders(token) });
+    } catch (err) {
+      return errorContent(
+        `Network error calling ${url}: ${err.message}. Check ADMIN_API_BASE_URL env var (currently "${ADMIN_API_BASE_URL}").`
+      );
+    }
     if (!res.ok) {
-      return errorContent(`API error: ${res.status} ${res.statusText}`);
+      return errorContent(`API error: ${res.status} ${res.statusText} (${url})`);
     }
     const data = await res.json();
     return textContent(JSON.stringify(data, null, 2));
@@ -3798,7 +3806,14 @@ var createMcpServer = (options = {}) => {
     try {
       return await fn();
     } catch (err) {
-      return errorContent(err.message);
+      const e = err;
+      if (e.message.includes("fetch")) {
+        const MCP_API_BASE_URL = process.env.MCP_API_BASE_URL ?? DEFAULT_MCP_API_BASE_URL;
+        return errorContent(
+          `MCP auth flow failed: ${e.message}. Check MCP_API_BASE_URL env var (currently "${MCP_API_BASE_URL}"). To re-auth from scratch: rm ~/.stackable/mcp-auth.json`
+        );
+      }
+      return errorContent(e.message);
     }
   };
   const registrySkills = listSkills("registry");

package/dist/server.js

@@ -3757,7 +3757,7 @@ var package_default = {
 // src/server.ts
 var MCP_CLIENT_NAME = STANDALONE_CLIENT.MCP;
 var DEFAULT_ADMIN_API_URL = "https://api-use1.stackablelabs.io/admin";
-var DEFAULT_MCP_DISCOVERY_URL = "https://api-use1.stackablelabs.io/mcp/.well-known/oauth-authorization-server";
+var DEFAULT_MCP_API_BASE_URL = "https://api-use1.stackablelabs.io/mcp";
 var textContent = (text) => ({ content: [{ type: "text", text }] });
 var errorContent = (text) => ({ content: [{ type: "text", text }], isError: true });
 var createMcpServer = (options = {}) => {
@@ -3774,8 +3774,8 @@ var createMcpServer = (options = {}) => {
     } catch {
     }
     const { performOAuthFlow } = await import('./auth-JRYNP3PL.js');
-    const discoveryUrl = process.env.MCP_DISCOVERY_URL ?? DEFAULT_MCP_DISCOVERY_URL;
-    return performOAuthFlow(discoveryUrl);
+    const MCP_API_BASE_URL = process.env.MCP_API_BASE_URL ?? DEFAULT_MCP_API_BASE_URL;
+    return performOAuthFlow(`${MCP_API_BASE_URL}/.well-known/oauth-authorization-server`);
   };
   const authHeaders = (token) => ({
     authorization: `Bearer ${token}`,
@@ -3784,10 +3784,18 @@ var createMcpServer = (options = {}) => {
   });
   const callApi = async (path) => {
     const token = await getAuthToken();
-    const baseUrl = process.env.ADMIN_API_BASE_URL ?? DEFAULT_ADMIN_API_URL;
-    const res = await fetch(`${baseUrl}${path}`, { headers: authHeaders(token) });
+    const ADMIN_API_BASE_URL = process.env.ADMIN_API_BASE_URL ?? DEFAULT_ADMIN_API_URL;
+    const url = `${ADMIN_API_BASE_URL}${path}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: authHeaders(token) });
+    } catch (err) {
+      return errorContent(
+        `Network error calling ${url}: ${err.message}. Check ADMIN_API_BASE_URL env var (currently "${ADMIN_API_BASE_URL}").`
+      );
+    }
     if (!res.ok) {
-      return errorContent(`API error: ${res.status} ${res.statusText}`);
+      return errorContent(`API error: ${res.status} ${res.statusText} (${url})`);
     }
     const data = await res.json();
     return textContent(JSON.stringify(data, null, 2));
@@ -3796,7 +3804,14 @@ var createMcpServer = (options = {}) => {
     try {
       return await fn();
     } catch (err) {
-      return errorContent(err.message);
+      const e = err;
+      if (e.message.includes("fetch")) {
+        const MCP_API_BASE_URL = process.env.MCP_API_BASE_URL ?? DEFAULT_MCP_API_BASE_URL;
+        return errorContent(
+          `MCP auth flow failed: ${e.message}. Check MCP_API_BASE_URL env var (currently "${MCP_API_BASE_URL}"). To re-auth from scratch: rm ~/.stackable/mcp-auth.json`
+        );
+      }
+      return errorContent(e.message);
     }
   };
   const registrySkills = listSkills("registry");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/mcp-app-extension",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "bin": {
     "mcp-app-extension": "./dist/index.js"