simframe 0.18.0 → 0.19.1

package/scripts/demo-gif/flow.json

@@ -0,0 +1,6 @@
+[
+  { "tap": "Accessibility" },
+  { "tap": "Display & Text Size" },
+  { "tap": "Larger Text" },
+  { "assert": { "value": "Larger Text" } }
+]

package/scripts/smithery-bundle.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Builds the Smithery bundle for the current version:
+//   node scripts/smithery-bundle.mjs            -> simframe-<version>.mcpb
+//   npx -y @smithery/cli mcp publish ./simframe-<version>.mcpb -n lvlr-xaus/simframe
+//
+// Smithery does not sync from the official MCP Registry, and its web form
+// takes only an HTTPS URL, so a local stdio server reaches it as an MCPB
+// bundle through the CLI. Two things learned publishing 0.18.0, both
+// load-bearing:
+//
+// - Smithery's validator wants an `inputSchema` on every tool it is told
+//   about, and Anthropic's `mcpb pack` refuses that key as unknown. So the
+//   tool list is taken from the server's own tools/list answer, schemas
+//   included, and the archive is a plain zip — a .mcpb is nothing else.
+// - The bundle is the packed npm tarball plus its runtime dependency
+//   installed inside it, because a bundle runs from its own directory.
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const work = fs.mkdtempSync(path.join(os.tmpdir(), 'simframe-mcpb-'));
+const dir = path.join(work, 'pkg');
+fs.mkdirSync(dir);
+
+const tarball = execFileSync('npm', ['pack', '--silent', '--pack-destination', work], { cwd: root }).toString().trim();
+execFileSync('tar', ['-xzf', path.join(work, tarball), '-C', dir, '--strip-components=1']);
+execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--silent'], { cwd: dir, stdio: 'inherit' });
+fs.copyFileSync(path.join(root, 'scripts/smithery/icon.png'), path.join(dir, 'icon.png'));
+
+// The tool list, with schemas, from the server that ships in the bundle.
+const tools = await new Promise((resolve, reject) => {
+  const child = spawn('node', [path.join(dir, 'src/cli.js'), 'mcp'], { cwd: dir, stdio: ['pipe', 'pipe', 'ignore'] });
+  let out = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.on('close', () => {
+    const line = out.split('\n').find((l) => l.includes('"id":2'));
+    line ? resolve(JSON.parse(line).result.tools) : reject(new Error('the bundled server did not answer tools/list'));
+  });
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'bundle', version: '0' } } }) + '\n');
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' }) + '\n');
+  child.stdin.end();
+});
+
+const firstSentence = (s) => s.trim().split(/(?<=[.!?])\s/)[0].slice(0, 200);
+const manifest = {
+  manifest_version: '0.3',
+  name: 'simframe',
+  display_name: 'simframe',
+  version: pkg.version,
+  description: 'Eyes, hands and memory for a coding agent driving the iOS Simulator or an Android emulator.',
+  long_description: 'simframe reads the simulator screen as a numbered text element map with tap points (accessibility tree + on-device OCR, ~20 ms warm frames instead of screenshots), runs whole tap/type/scroll/assert flows in one call with every step verified against what it did last time, and remembers screens so repeated flows need no model calls. Needs a Mac with Xcode; the first call builds a small Swift daemon from source (~15 s, once). Android emulators are driven with the same tools, without an accessibility tree.',
+  author: { name: 'Sadjad Asadi', url: 'https://github.com/lvlrSajjad' },
+  repository: { type: 'git', url: 'https://github.com/lvlrSajjad/simframe.git' },
+  homepage: 'https://lvlrsajjad.github.io/simframe/',
+  documentation: 'https://github.com/lvlrSajjad/simframe#readme',
+  support: 'https://github.com/lvlrSajjad/simframe/issues',
+  icon: 'icon.png',
+  server: { type: 'node', entry_point: 'src/cli.js', mcp_config: { command: 'node', args: ['${__dirname}/src/cli.js', 'mcp'] } },
+  tools: tools.map((t) => ({ name: t.name, description: firstSentence(t.description ?? ''), inputSchema: t.inputSchema ?? { type: 'object', properties: {} } })),
+  tools_generated: false,
+  keywords: pkg.keywords,
+  license: 'MIT',
+  compatibility: { platforms: ['darwin'], runtimes: { node: '>=18.17' } },
+};
+fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+const out = path.join(root, `simframe-${pkg.version}.mcpb`);
+// One bundle at a time. A stale one from the previous version sitting next to
+// the new one got published in its place once, by a command line that named
+// the old file.
+for (const f of fs.readdirSync(root)) if (/^simframe-.*\.mcpb$/.test(f)) fs.rmSync(path.join(root, f), { force: true });
+execFileSync('zip', ['-qr', out, '.', '-x', '*.DS_Store'], { cwd: dir });
+fs.rmSync(work, { recursive: true, force: true });
+console.log(`${path.relative(root, out)}: ${tools.length} tools, ${(fs.statSync(out).size / 1e6).toFixed(1)} MB`);
+console.log(`publish: npx -y @smithery/cli mcp publish ./${path.relative(root, out)} -n lvlr-xaus/simframe`);

package/scripts/smithery-metadata.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Sets the simframe listing's metadata on Smithery — description, links,
+// license and icon — which the bundle publish does not carry.
+//   node scripts/smithery-metadata.mjs
+//
+// The API key is the one `npx @smithery/cli` stored when it asked for it;
+// SMITHERY_API_KEY in the environment wins if set. Nothing is printed but
+// the server's answers.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const server = 'lvlr-xaus/simframe';
+
+function apiKey() {
+  if (process.env.SMITHERY_API_KEY) return process.env.SMITHERY_API_KEY;
+  const dir = process.env.SMITHERY_CONFIG_PATH
+    ?? (process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'smithery') : path.join(os.homedir(), '.config', 'smithery'));
+  const file = path.join(dir, 'settings.json');
+  const key = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')).apiKey : null;
+  if (!key) throw new Error(`no Smithery API key: set SMITHERY_API_KEY or run any \`npx @smithery/cli mcp publish\` once so it stores one in ${file}`);
+  return key;
+}
+
+const headers = { Authorization: `Bearer ${apiKey()}` };
+const base = `https://api.smithery.ai/servers/${encodeURIComponent(server)}`;
+
+const meta = await fetch(base, {
+  method: 'PATCH',
+  headers: { ...headers, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    displayName: 'simframe',
+    description: 'Eyes, hands and memory for a coding agent driving the iOS Simulator or an Android emulator. Reads the screen as text with tap points, runs whole flows in one call with every step verified, and remembers screens so repeated flows need no model calls.',
+    homepage: 'https://lvlrsajjad.github.io/simframe/',
+    repositoryUrl: 'https://github.com/lvlrSajjad/simframe',
+    backlinkUrl: 'https://lvlrsajjad.github.io/simframe/agents-shouldnt-blink.html',
+    license: 'MIT',
+  }),
+});
+console.log(`metadata: ${meta.status} ${await meta.text()}`);
+
+const icon = new FormData();
+icon.append('icon', new Blob([fs.readFileSync(path.join(root, 'scripts/smithery/icon.png'))], { type: 'image/png' }), 'icon.png');
+const up = await fetch(`${base}/icon`, { method: 'PUT', headers, body: icon });
+console.log(`icon: ${up.status} ${await up.text()}`);

package/scripts/sync-server-version.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// Keep server.json's version in step with package.json's.
+// Keep server.json's and the Claude Code plugin's versions in step with
+// package.json's.
 //
 // `npm version` only knows about package.json, and the MCP registry manifest
 // carries the version twice — once at the top level and once inside the package
@@ -8,7 +9,12 @@
 // the workflow's own agreement check.
 //
 // npm runs this as the `version` lifecycle script: after the bump, before the
-// commit. It stages server.json so the version commit contains both files.
+// commit. It stages both files so the version commit contains all three.
+//
+// The plugin manifest is the second file for the same reason server.json is:
+// a `version` in .claude-plugin/plugin.json pins every installed copy to it, so
+// a manifest left behind by one release would hold plugin users on the
+// previous release's skill forever, with nothing failing.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -30,10 +36,17 @@ server.packages[0].version = pkg.version;
 fs.writeFileSync(file, `${JSON.stringify(server, null, 2)}\n`);
 console.log(`server.json ${before.top} / ${before.pkg} -> ${pkg.version} / ${pkg.version}`);
 
-// Stage it, so `npm version` commits both files together. Harmless when run
-// with --no-git-tag-version; the file is still correct either way.
+const pluginFile = path.join(ROOT, '.claude-plugin', 'plugin.json');
+const plugin = JSON.parse(fs.readFileSync(pluginFile, 'utf8'));
+const pluginBefore = plugin.version;
+plugin.version = pkg.version;
+fs.writeFileSync(pluginFile, `${JSON.stringify(plugin, null, 2)}\n`);
+console.log(`.claude-plugin/plugin.json ${pluginBefore} -> ${pkg.version}`);
+
+// Stage them, so `npm version` commits every file together. Harmless when run
+// with --no-git-tag-version; the files are still correct either way.
 try {
-  execFileSync('git', ['add', '--', file], { cwd: ROOT, stdio: 'pipe' });
+  execFileSync('git', ['add', '--', file, pluginFile], { cwd: ROOT, stdio: 'pipe' });
 } catch {
-  console.log('(could not stage server.json — commit it yourself)');
+  console.log('(could not stage server.json and plugin.json — commit them yourself)');
 }

package/skills/simframe/SKILL.md

@@ -18,6 +18,13 @@ and CV alone. Tapping by label works; screen recognition is thinner, so prefer
 naming a device explicitly and re-reading the screen after a step you are unsure
 about.
 
+Commands are written here as the CLI (`simframe ui`, `simframe do`), which is
+the cheapest path. If `simframe` is not on your PATH — installed as a Claude Code
+plugin, say — the MCP server is already connected and the screen and flow
+commands are its tools under the same names (`sim_ui`, `sim_do`, `sim_state`,
+`sim_goto`…). Use those; for `doctor` and the other diagnostics, ask the user
+to run `npm install -g simframe`.
+
 ## The protocol: plan once, execute once, think only when told to
 
 The expensive thing in a simulator session is not the tapping. It is you —