kloudy 0.4.5 → 0.4.7

package/README.md

@@ -14,7 +14,9 @@ No arguments detects Cursor, VS Code, Claude Desktop, Claude Code, Windsurf and
 
 The remote endpoint is https://kloudy.ai/mcp. Public catalog discovery works without a key and makes no model call. It returns up to five public metadata candidates, not execution grants. Account actions still require an existing authorized Kloudy key; self-service engine-key issuance is not connected. If you already have one, set `KLOUDY_MCP_TOKEN` privately in your environment; the installer asks before storing it in a client's headers (or Claude Desktop's stdio environment). Keys are never accepted as command-line arguments or printed by the installer.
 
-`mcp` is a local stdio-to-Streamable-HTTP proxy; stdout contains MCP messages only. Direct questions and the proxy call the same remote server. Network failures and invalid keys fail explicitly. Catalog change notifications, resource forwarding and a single reconnect after an explicit session-expired HTTP 404 are gated by `KLOUDY_MCP_AUTOUPDATE=meta` or `notify`; the default is `off`. Ambiguous tool failures are never retried.
+`mcp` is a local stdio-to-Streamable-HTTP proxy; stdout contains MCP messages only. Direct questions and the proxy call the same remote server. Network failures and invalid keys fail explicitly. Resources are forwarded whenever the upstream supports them, including with autoupdate off. Catalog change notifications and a single reconnect after an explicit session-expired HTTP 404 remain gated by `KLOUDY_MCP_AUTOUPDATE=meta` or `notify`; the default is `off`. Ambiguous tool failures are never retried.
+
+Interactive cards require a host that supports MCP Apps. The proxy relays the supported Apps MIME capability; it does not claim sampling, roots or elicitation. Hosts without Apps can use named text choices, source links and readable resources. The one-shot CLI prints text rather than rendering an interactive card. When the hosted catalog offers visual setup choices, the IDE uses its own available tools and account terms to make a local mockup; Kloudy supplies data and does not invoke backend model/image generation. Resource hosting still has operational cost. Selecting a layout does not authorize installation, account connection, paid image APIs or deployment.
 
 The existing SDK exports remain available under `kloudy/*`. For the pre-0.4 specialized engine CLI commands documented below, use `kloudy legacy <command>` (for example, `kloudy legacy init my-app`). The original CLI is retained in `bin/kloudy.mjs`.
 
@@ -305,3 +307,8 @@ MCP: operation `conversation`, `conversation_operation` = `read`, `append` or `s
 The engine owns encryption, scope checks, condensation gates and transcript deletion. Returned cards are lossy context, never grants. Artifact pointers do not authorize repository reads. The client never persists message bodies in its session file. Replayed commands return metadata only: issue a read for current cards. Conflicts and failures are not retried automatically; read the cursor and reconcile before resubmitting. Added in 0.4.1. The no-key installer and public discovery remain unchanged.
 
 Official MCP Registry name: `ai.kloudy/kloudy`. Remote endpoint: https://kloudy.ai/mcp. Public discovery and Sample cards do not grant private tools or authorize spending.
+
+## Card and website fallback (0.4.7)
+
+The remote MCP adapter returns supported card metadata and a plain-text HTTPS chooser link together. Hosts control rendering and link launch. Call show_pending_chooser_link to display the last offer/selection again in the same MCP process. Website sign-in verifies private account projects; the public template locator is never an account token or authorization. A presentation goal may be retained in the current MCP process and is kept out of the URL. Automatic authenticated IDE return is not claimed. If the process resets, use the website's existing project recovery path. No models, installation or spending are activated by these links.
+

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "kloudy",
-  "version": "0.4.5",
-  "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
-  "type": "module",
-  "license": "Apache-2.0",
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "bin": {
-    "kloudy": "bin/entry.mjs"
-  },
-  "exports": {
-    ".": "./src/client.mjs",
-    "./mcp": "./src/mcp.mjs",
-    "./wrap": "./src/wrap.mjs",
-    "./session": "./src/connection.mjs",
-    "./httpk": "./src/httpk.mjs",
-    "./hosted": "./src/hosted.mjs",
-    "./public": "./src/public.mjs",
-    "./strings": "./src/strings.mjs",
-    "./sdf": "./src/sdf.mjs",
-    "./query": "./src/query.mjs",
-    "./activity": "./src/activity.mjs",
-    "./status-indicator.css": "./src/status-indicator.css",
-    "./models": "./src/models.mjs",
-    "./host-interface": "./src/host-interface.mjs",
-    "./replies": "./src/replies.mjs",
-    "./conversation": "./src/conversation.mjs"
-  },
-  "files": [
-    "bin",
-    "src",
-    "schemas",
-    "README.md",
-    "MCP-DEFAULT.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "check": "node --check bin/kloudy.mjs && node --check src/client.mjs && npm test",
-    "start": "node bin/kloudy.mjs",
-    "proof": "node scripts/prove.mjs",
-    "build:approval": "node scripts/build-approval.mjs"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/ext-apps": "2.0.3",
-    "@modelcontextprotocol/sdk": "1.31.0",
-    "ajv": "8.20.0",
-    "ajv-formats": "3.0.1",
-    "js-tiktoken": "1.0.21",
-    "jsonc-parser": "3.3.1",
-    "smol-toml": "1.9.0",
-    "zod": "4.6.5"
-  },
-  "devDependencies": {
-    "esbuild": "0.28.2"
-  },
-  "mcpName": "ai.kloudy/kloudy",
-  "homepage": "https://kloudy.ai/install",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "bugs": {
-    "url": "https://kloudy.ai/support"
-  }
-}
+{
+  "name": "kloudy",
+  "version": "0.4.7",
+  "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "kloudy": "bin/entry.mjs"
+  },
+  "exports": {
+    ".": "./src/client.mjs",
+    "./mcp": "./src/mcp.mjs",
+    "./wrap": "./src/wrap.mjs",
+    "./session": "./src/connection.mjs",
+    "./httpk": "./src/httpk.mjs",
+    "./hosted": "./src/hosted.mjs",
+    "./public": "./src/public.mjs",
+    "./strings": "./src/strings.mjs",
+    "./sdf": "./src/sdf.mjs",
+    "./query": "./src/query.mjs",
+    "./activity": "./src/activity.mjs",
+    "./status-indicator.css": "./src/status-indicator.css",
+    "./models": "./src/models.mjs",
+    "./host-interface": "./src/host-interface.mjs",
+    "./replies": "./src/replies.mjs",
+    "./conversation": "./src/conversation.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schemas",
+    "README.md",
+    "MCP-DEFAULT.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check bin/kloudy.mjs && node --check src/client.mjs && npm test",
+    "start": "node bin/kloudy.mjs",
+    "proof": "node scripts/prove.mjs",
+    "build:approval": "node scripts/build-approval.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "2.0.3",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "js-tiktoken": "1.0.21",
+    "jsonc-parser": "3.3.1",
+    "smol-toml": "1.9.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "mcpName": "ai.kloudy/kloudy",
+  "homepage": "https://kloudy.ai/install",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bugs": {
+    "url": "https://kloudy.ai/support"
+  }
+}

package/src/chooser-link.mjs

@@ -0,0 +1,17 @@
+// Public presentation adapter. URLs contain public template locators only, never
+// a connection credential, authorization token, goal text or identity claim.
+export const CHOOSER_URL='https://kloudy.ai/api/customer/visual-chooser/start';
+export const pendingChooserTool={name:'show_pending_chooser_link',description:'Show the pending Kloudy card and its HTTPS website fallback again. The website verifies account sign-in; the link is not authorization. This does not run a tool, model, installation or payment.',inputSchema:{type:'object',properties:{},additionalProperties:false},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}};
+export function chooserResponse(result,{apps=false,goal}={}){
+ if(!result||typeof result!=='object'||Array.isArray(result)||result.isError)return result;
+ const data=result.structuredContent;if(!data||typeof data!=='object'||Array.isArray(data))return result;
+ const option=typeof data.selectedOptionId==='string'&&/^[a-z0-9-]{1,80}$/.test(data.selectedOptionId)?data.selectedOptionId:null;
+ const set=typeof data.choiceSetId==='string'&&/^visual-[a-f0-9]{1,64}$/.test(data.choiceSetId)?data.choiceSetId:null;
+ const url=option&&set?CHOOSER_URL+'#choice='+encodeURIComponent(option)+'&set='+encodeURIComponent(set):CHOOSER_URL;
+ const chooser={url,linkIsAuthorization:false,identityFromEmail:false,accountBindingVerified:false,returnMethod:'existing-authenticated-website-project-manifest',automaticIdeReturnVerified:false,...(set?{publicChoiceSetId:set}:{}),...(option?{publicOptionId:option}:{}),...(goal?{request:goal}:{})};
+ const text='Website chooser: '+url+'\nOpen this HTTPS link if your host does not show the card. Complete account sign-in/2FA on the website before opening private project choices. Email is a lookup hint, not proof. The host controls card rendering, clickable links and browser launch. Account-bound automatic return is not established by this public template locator.';
+ return {...result,content:[...(Array.isArray(result.content)?result.content:[]),{type:'text',text}],structuredContent:{...data,chooser},...(apps?{_meta:{...result._meta,ui:{...result._meta?.ui,resourceUri:'ui://widget/kloudy-visual-setup-v1.html'}}}:{})};
+}
+export function pendingChooserResponse(pending){
+ return pending?structuredClone(pending):{content:[{type:'text',text:'No pending chooser is retained in this MCP process. Open '+CHOOSER_URL+' and sign in to recover your existing project. This link is not a bearer token or authorization.'}],structuredContent:{pending:false,chooser:{url:CHOOSER_URL,linkIsAuthorization:false,accountBindingVerified:false}}};
+}

package/src/remote.mjs

@@ -1,59 +1,82 @@
-import {readFileSync} from 'node:fs';
-const packageVersion=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
-import {Client} from '@modelcontextprotocol/sdk/client/index.js';
-import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import {Server} from '@modelcontextprotocol/sdk/server/index.js';
-import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
-import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,ReadResourceRequestSchema,ToolListChangedNotificationSchema,ResourceListChangedNotificationSchema} from '@modelcontextprotocol/sdk/types.js';
-import {REMOTE} from './editor-install.mjs';
-import {autoupdateEnabled} from './autoupdate.mjs';
-const transports=new WeakMap();
-export async function connectRemote({key=process.env.KLOUDY_MCP_TOKEN,fetcher=fetch}={}){
- if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');
- const client=new Client({name:'kloudy',version:packageVersion},{capabilities:{}});
- const transport=new StreamableHTTPClientTransport(new URL(REMOTE),{requestInit:{headers:key?{Authorization:'Bearer '+key}:{},redirect:'error'},fetch:(url,options)=>fetcher(url,{...options,redirect:'error'}),reconnectionOptions:{maxRetries:0}});
- transports.set(client,transport);
- try{await client.connect(transport,{timeout:25000});return client;}catch(e){await client.close().catch(()=>{});throw e;}
-}
-export async function askRemote(question,options){
- if(typeof question!=='string'||!question.trim()||question.length>1000)throw Error('Use a question of 1–1000 characters');
- const client=await connectRemote(options);
- try{return await client.callTool({name:'kloudy',arguments:{operation:'ask',goal:question}},undefined,{timeout:25000});}finally{await client.close();}
-}
-export async function serveRemote(options={}){
- const enabled=autoupdateEnabled(options.autoupdate??process.env.KLOUDY_MCP_AUTOUPDATE);
- let remote=await connectRemote(options),reconnecting;
- const server=new Server({name:'kloudy',version:packageVersion},{capabilities:enabled?{tools:{listChanged:true},resources:{listChanged:true}}:{tools:{}},instructions:'Use Kloudy when mentioned, or to discover MCP tools and SDKs. Public discovery is free; account actions need an existing authorized key.'});
- function forward(client){
-  if(!enabled)return;
-  client.setNotificationHandler(ToolListChangedNotificationSchema,()=>server.sendToolListChanged());
-  client.setNotificationHandler(ResourceListChangedNotificationSchema,()=>server.sendResourceListChanged());
- }
- forward(remote);
- async function invoke(method,params){
-  const current=remote;
-  const run=client=>method==='callTool'?client.callTool(params,undefined,{timeout:25000}):client[method](params);
-  try{return await run(current);}catch(error){
-   // Only an explicit HTTP 404 on an established session permits one retry.
-   // Ambiguous network/timeout errors and session-less 404s are never retried.
-   if(!enabled||error.code!==404||!transports.get(current)?.sessionId)throw error;
-   if(remote===current){
-    reconnecting??=(async()=>{
-     const next=await connectRemote(options);forward(next);remote=next;
-     await current.close().catch(()=>{});
-     await server.sendToolListChanged();await server.sendResourceListChanged();
-    })().finally(()=>{reconnecting=undefined;});
-    await reconnecting;
-   }
-   return run(remote);
-  }
- }
- server.setRequestHandler(ListToolsRequestSchema,req=>invoke('listTools',req.params));
- server.setRequestHandler(CallToolRequestSchema,req=>invoke('callTool',req.params));
- if(enabled){
-  server.setRequestHandler(ListResourcesRequestSchema,req=>invoke('listResources',req.params));
-  server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
- }
- server.onclose=()=>{void remote.close();};
- await server.connect(options.transport??new StdioServerTransport());return server;
-}
+import {readFileSync} from 'node:fs';
+const packageVersion=JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {ListToolsRequestSchema,CallToolRequestSchema,ListResourcesRequestSchema,ReadResourceRequestSchema,ListResourceTemplatesRequestSchema,ToolListChangedNotificationSchema,ResourceListChangedNotificationSchema} from '@modelcontextprotocol/sdk/types.js';
+import {REMOTE} from './editor-install.mjs';
+import {autoupdateEnabled} from './autoupdate.mjs';
+import {chooserResponse,pendingChooserResponse,pendingChooserTool} from './chooser-link.mjs';
+const transports=new WeakMap();
+// This proxy can relay Apps rendering, but cannot service sampling, roots or elicitation.
+export function forwardedCapabilities(value={}){
+ const ui=value.experimental?.['io.modelcontextprotocol/ui'];
+ const mimeTypes=Array.isArray(ui?.mimeTypes)?ui.mimeTypes.filter(x=>x==='text/html;profile=mcp-app'):[];
+ return mimeTypes.length?{experimental:{'io.modelcontextprotocol/ui':{mimeTypes:[...new Set(mimeTypes)]}}}:{};
+}
+export async function connectRemote({key=process.env.KLOUDY_MCP_TOKEN,fetcher=fetch,capabilities={}}={}){
+ if(key!==undefined&&!/^\S{20,512}$/.test(key))throw Error('Invalid key');
+ const client=new Client({name:'kloudy',version:packageVersion},{capabilities:forwardedCapabilities(capabilities)});
+ const transport=new StreamableHTTPClientTransport(new URL(REMOTE),{requestInit:{headers:key?{Authorization:'Bearer '+key}:{},redirect:'error'},fetch:(url,options)=>fetcher(url,{...options,redirect:'error'}),reconnectionOptions:{maxRetries:0}});
+ transports.set(client,transport);
+ try{await client.connect(transport,{timeout:25000});return client;}catch(e){await client.close().catch(()=>{});throw e;}
+}
+export async function askRemote(question,options){
+ if(typeof question!=='string'||!question.trim()||question.length>1000)throw Error('Use a question of 1–1000 characters');
+ const client=await connectRemote(options);
+ try{return await client.callTool({name:'kloudy',arguments:{operation:'ask',goal:question}},undefined,{timeout:25000});}finally{await client.close();}
+}
+export async function serveRemote(options={}){
+ const connect=options.connect??connectRemote,enabled=autoupdateEnabled(options.autoupdate??process.env.KLOUDY_MCP_AUTOUPDATE);
+ let remote=await connect({...options,capabilities:{}}),ready=Promise.resolve(),closed=false,reconnecting,pendingChooser,requestGoal;
+ const upstream=remote.getServerCapabilities(),capabilities={};
+ if(upstream.tools)capabilities.tools=enabled&&upstream.tools.listChanged?{listChanged:true}:{};
+ if(upstream.resources)capabilities.resources=enabled&&upstream.resources.listChanged?{listChanged:true}:{};
+ const server=new Server({name:'kloudy',version:packageVersion},{capabilities,instructions:'Use Kloudy for discovery and data-only visual setup choices. Call the card tool explicitly for its UI. Hosts without Apps use named choices, sources and local assembly instructions. Existing authorization remains required for account actions.'});
+ function forward(client){
+  if(capabilities.tools?.listChanged)client.setNotificationHandler(ToolListChangedNotificationSchema,()=>server.sendToolListChanged());
+  if(capabilities.resources?.listChanged)client.setNotificationHandler(ResourceListChangedNotificationSchema,()=>server.sendResourceListChanged());
+ }
+ forward(remote);
+ server.oninitialized=()=>{
+  const actual=forwardedCapabilities(server.getClientCapabilities());
+  if(!Object.keys(actual).length)return;
+  ready=(async()=>{const next=await connect({...options,capabilities:actual});if(closed){await next.close();return;}const previous=remote;remote=next;forward(next);await previous.close();})();
+  // Requests still receive negotiation errors; avoid an unhandled rejection before the first request.
+  void ready.catch(()=>{});
+ };
+ const invoke=async(method,params)=>{
+  await ready;const current=remote,run=client=>method==='callTool'?client.callTool(params,undefined,{timeout:25000}):client[method](params);
+  try{return await run(current);}catch(error){
+   // Preserve 0.4.5's opt-in recovery: only an established HTTP session's explicit 404 permits one retry.
+   if(!enabled||error.code!==404||!transports.get(current)?.sessionId)throw error;
+   if(remote===current){reconnecting??=(async()=>{const next=await connect({...options,capabilities:forwardedCapabilities(server.getClientCapabilities())});if(closed){await next.close();throw error;}remote=next;forward(next);await current.close().catch(()=>{});if(capabilities.tools?.listChanged)await server.sendToolListChanged();if(capabilities.resources?.listChanged)await server.sendResourceListChanged();})().finally(()=>{reconnecting=undefined;});await reconnecting;}
+   return run(remote);
+  }
+ };
+ if(capabilities.tools){
+  server.setRequestHandler(ListToolsRequestSchema,async req=>{
+   const result=await invoke('listTools',req.params);
+   return {...result,tools:[...result.tools.map(tool=>tool.name==='show_visual_setup_choices'?{...tool,inputSchema:{...tool.inputSchema,properties:{...tool.inputSchema.properties,goal:{type:'string',minLength:1,maxLength:1000,description:'Presentation request retained in this MCP process; never sent as a credential or URL.'}}}}:tool),...(result.tools.some(t=>t.name===pendingChooserTool.name)?[]:[pendingChooserTool])]};
+  });
+  server.setRequestHandler(CallToolRequestSchema,async req=>{
+   if(req.params.name===pendingChooserTool.name){if(Object.keys(req.params.arguments||{}).length)throw Error('Pending chooser lookup takes no identity or credential fields');return pendingChooserResponse(pendingChooser);}
+   if(req.params.name!=='show_visual_setup_choices')return invoke('callTool',req.params);
+   const argumentsValue={...(req.params.arguments||{})};
+   let nextGoal=requestGoal;
+   if(Object.hasOwn(argumentsValue,'goal')){if(typeof argumentsValue.goal!=='string'||!argumentsValue.goal.trim()||argumentsValue.goal.length>1000)throw Error('Use a presentation request of 1-1000 characters');nextGoal=argumentsValue.goal;delete argumentsValue.goal;}
+   const result=await invoke('callTool',{...req.params,arguments:argumentsValue});
+   const decorated=chooserResponse(result,{apps:!!forwardedCapabilities(server.getClientCapabilities()).experimental,goal:nextGoal});
+   if(!decorated.isError){requestGoal=nextGoal;pendingChooser=decorated;}return decorated;
+  });
+ }
+ // Resource delivery is independent of notification/autoupdate opt-in.
+ if(capabilities.resources){
+  server.setRequestHandler(ListResourcesRequestSchema,req=>invoke('listResources',req.params));
+  server.setRequestHandler(ReadResourceRequestSchema,req=>invoke('readResource',req.params));
+  server.setRequestHandler(ListResourceTemplatesRequestSchema,req=>invoke('listResourceTemplates',req.params));
+ }
+ server.onclose=()=>{closed=true;void ready.catch(()=>{}).then(()=>remote.close());};
+ await server.connect(options.transport??new StdioServerTransport());return server;
+}