frameshot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kamegoro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# frameshot
+
+> Instant cross-browser component preview for AI agents. One call, one screenshot — no dev server, no Storybook, no ceremony.
+
+**Works with:** Claude Code · Cursor · Codex · Windsurf · any MCP-compatible tool
+
+## The Problem
+
+You're building UI with an AI agent. The agent writes a component but can't see it. You have to:
+1. Start the dev server
+2. Log in
+3. Navigate to the right page
+4. Scroll to the component
+5. Tell the agent what's wrong
+
+**frameshot** skips all of that. The agent renders the component itself, sees the result, and fixes it.
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add frameshot -- npx frameshot-mcp@latest
+```
+
+That's it. Now your AI agent can see UI.
+
+### Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "frameshot": {
+      "command": "npx",
+      "args": ["frameshot-mcp@latest"]
+    }
+  }
+}
+```
+
+### VS Code Copilot (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "frameshot": {
+      "command": "npx",
+      "args": ["frameshot-mcp@latest"]
+    }
+  }
+}
+```
+
+### Manual setup
+
+```json
+{
+  "mcpServers": {
+    "frameshot": {
+      "command": "npx",
+      "args": ["frameshot-mcp@latest"]
+    }
+  }
+}
+```
+
+> **Note:** On first run, Playwright will download Chromium (~150MB). For additional engines: `npx playwright install firefox webkit`
+
+## Tools
+
+### `render_component`
+
+Render isolated component code → get screenshot back instantly.
+
+```typescript
+render_component({
+  code: `
+    function App() {
+      return (
+        <div className="p-8 bg-gradient-to-r from-blue-500 to-purple-600 rounded-xl">
+          <h1 className="text-4xl font-bold text-white">Hello World</h1>
+        </div>
+      )
+    }
+  `,
+  framework: "react",
+  engines: ["chromium", "firefox", "webkit"]
+})
+// Returns 3 screenshots — one per browser engine
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `code` | required | Component source code |
+| `framework` | `"react"` | `"react"` · `"vue"` · `"html"` |
+| `engines` | `["chromium"]` | Browser engines to render in |
+| `width` | `1280` | Viewport width |
+| `height` | `800` | Viewport height |
+| `fullPage` | `true` | Capture full scroll height |
+
+### `screenshot_url`
+
+Screenshot a running app (e.g. localhost) across browsers.
+
+```typescript
+screenshot_url({
+  url: "http://localhost:3000/components/button",
+  engines: ["chromium", "firefox", "webkit"]
+})
+```
+
+## Why Not Storybook?
+
+| | Storybook | frameshot |
+|---|-----------|-----------|
+| Setup | Write .stories.tsx, configure addons, run server | **Zero** — pass code, get image |
+| Speed | Heavy dev server startup | **~800ms** warm render |
+| Cross-browser | Chromatic ($149+/mo) | **Free** — Playwright built-in |
+| AI-native | Requires pre-written stories | **Works with any code snippet** |
+| Auth required? | Need full app context | **No** — isolated component render |
+
+frameshot is not a Storybook replacement. Storybook is for documentation and design systems. frameshot is for **seeing what you just wrote, right now**.
+
+## Performance
+
+| Scenario | Time |
+|----------|------|
+| Warm render (browser reused) | **~800ms** |
+| Cold start (first render) | ~3-5s |
+| Cross-browser (3 engines parallel) | ~1-2s warm |
+
+The browser stays warm between calls. Second render onwards is sub-second.
+
+## Framework Support
+
+### React (JSX + Tailwind)
+```jsx
+function App() {
+  const [count, setCount] = React.useState(0)
+  return <button onClick={() => setCount(c => c+1)} className="btn">{count}</button>
+}
+```
+
+### Vue 3 (Composition API + Tailwind)
+```javascript
+const App = {
+  setup() {
+    const count = ref(0)
+    return { count }
+  },
+  template: `<button @click="count++">{{ count }}</button>`
+}
+```
+
+### HTML (+ Tailwind)
+```html
+<div class="flex gap-4 p-8">
+  <button class="px-4 py-2 bg-blue-500 text-white rounded">Click me</button>
+</div>
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FRAMESHOT_BROWSER_PATH` | Custom Chromium executable path |
+
+## Development
+
+```bash
+git clone https://github.com/kamegoro/frameshot.git
+cd frameshot
+npm install
+npx playwright install chromium
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node