spritecook-mcp 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# spritecook-mcp
+
+Connect your AI agent (Cursor, VS Code, Claude Desktop, Claude Code) to [SpriteCook](https://spritecook.ai) for AI-powered pixel art and game asset generation.
+
+## Quick Setup
+
+```bash
+npx spritecook-mcp setup
+```
+
+This will:
+
+1. **Authenticate** your SpriteCook account (browser-based or manual API key)
+2. **Detect** your editors (Cursor, VS Code, Claude Desktop, Claude Code)
+3. **Configure** MCP connections automatically
+4. **Install** an optional agent skill for smarter AI integration
+
+## What You Get
+
+After setup, your AI agent can generate pixel art and game assets directly:
+
+> "Generate a 64x64 pixel art sword sprite"
+
+> "Create a character sprite sheet for my platformer game"
+
+> "Make a set of potion icons with transparent backgrounds"
+
+## Manual Configuration
+
+If you prefer to configure manually, add this to your editor's MCP config:
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "spritecook": {
+      "url": "https://api.spritecook.ai/mcp/",
+      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/settings.json`):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "spritecook": {
+        "type": "http",
+        "url": "https://api.spritecook.ai/mcp/",
+        "headers": { "Authorization": "Bearer YOUR_API_KEY" }
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+- `SPRITECOOK_API_URL` - Override the API base URL (for local development)
+
+## Links
+
+- [SpriteCook](https://spritecook.ai) - AI game asset generator
+- [API Documentation](https://spritecook.ai/docs) - Full API reference
+- [Get API Key](https://app.spritecook.ai) - Sign up and manage API keys

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from '../src/setup.mjs';
+
+run().catch((err) => {
+  console.error('\nUnexpected error:', err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spritecook-mcp",
-  "version": "0.0.1",
-  "description": "SpriteCook MCP Server - Model Context Protocol server for AI-powered pixel art generation. Connect your AI agent to SpriteCook for game asset creation.",
+  "version": "0.1.0",
+  "description": "SpriteCook MCP Server - Connect your AI agent (Cursor, VS Code, Claude) to SpriteCook for pixel art and game asset generation.",
   "keywords": [
     "spritecook",
     "mcp",
@@ -11,7 +11,8 @@
     "ai-agent",
     "cursor",
     "claude",
-    "vscode"
+    "vscode",
+    "cli"
   ],
   "homepage": "https://spritecook.ai",
   "repository": {
@@ -20,5 +21,19 @@
   },
   "license": "MIT",
   "author": "SpriteCook <hello@spritecook.ai>",
-  "main": "index.js"
+  "type": "module",
+  "bin": {
+    "spritecook-mcp": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "open": "^10.1.0",
+    "ora": "^8.1.0",
+    "prompts": "^2.4.2"
+  }
 }

package/src/auth.mjs

@@ -0,0 +1,156 @@
+import prompts from 'prompts';
+import open from 'open';
+import { spinner, error, info } from './ui.mjs';
+import { getApiBase } from './config.mjs';
+
+/**
+ * Authenticate via the browser-based device authorization flow.
+ * Returns the raw API key string on success, or null on failure.
+ */
+export async function deviceFlow() {
+  const apiBase = getApiBase();
+
+  // Step 1: Start a device auth session
+  let session;
+  try {
+    const res = await fetch(`${apiBase}/v1/api/device-auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      error(`Failed to start device auth: ${res.status} ${body}`);
+      return null;
+    }
+    session = await res.json();
+  } catch (err) {
+    error(`Could not connect to SpriteCook API at ${apiBase}`);
+    error(err.message || String(err));
+    return null;
+  }
+
+  const { session_id, device_code, connect_url, expires_in } = session;
+
+  // Step 2: Open the browser
+  info(`Your verification code: ${device_code}`);
+  console.log();
+
+  try {
+    await open(connect_url);
+    info('Browser opened. Please log in and click "Authorize".');
+  } catch {
+    info(`Could not open browser automatically.`);
+    info(`Please open this URL manually:`);
+    console.log(`  ${connect_url}`);
+  }
+
+  // Step 3: Poll for completion
+  const spin = spinner('Waiting for authorization...');
+  spin.start();
+
+  const pollInterval = 3000; // 3 seconds
+  const deadline = Date.now() + expires_in * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(pollInterval);
+
+    try {
+      const res = await fetch(`${apiBase}/v1/api/device-auth/poll/${session_id}`);
+      if (!res.ok) {
+        continue; // Retry on transient errors
+      }
+      const data = await res.json();
+
+      if (data.status === 'completed' && data.api_key) {
+        spin.succeed('  Authorized!');
+        return data.api_key;
+      }
+
+      if (data.status === 'expired') {
+        spin.fail('  Session expired.');
+        error('The authorization session expired. Please try again.');
+        return null;
+      }
+
+      // status === 'pending' -- keep polling
+    } catch {
+      // Network hiccup, keep polling
+    }
+  }
+
+  spin.fail('  Timed out waiting for authorization.');
+  error('Authorization timed out. Please try again.');
+  return null;
+}
+
+/**
+ * Authenticate by having the user paste their API key manually.
+ * Returns the raw API key string on success, or null on failure.
+ */
+export async function manualKeyEntry() {
+  const response = await prompts({
+    type: 'text',
+    name: 'key',
+    message: 'Paste your SpriteCook API key (sc_live_...):',
+    validate: (val) => {
+      if (!val || !val.startsWith('sc_live_')) {
+        return 'API key must start with sc_live_';
+      }
+      if (val.length < 20) {
+        return 'API key seems too short';
+      }
+      return true;
+    },
+  });
+
+  if (!response.key) {
+    return null; // User cancelled
+  }
+
+  return response.key;
+}
+
+/**
+ * Prompt the user to choose an auth method and execute it.
+ * Returns the API key or null.
+ */
+export async function authenticate() {
+  const response = await prompts({
+    type: 'select',
+    name: 'method',
+    message: 'How would you like to authenticate?',
+    choices: [
+      { title: 'Connect via browser (recommended)', value: 'browser' },
+      { title: 'Enter API key manually', value: 'manual' },
+    ],
+    initial: 0,
+  });
+
+  if (!response.method) {
+    return null; // User cancelled
+  }
+
+  if (response.method === 'browser') {
+    const key = await deviceFlow();
+    if (!key) {
+      info('Browser auth failed. You can try entering your key manually.');
+      const fallback = await prompts({
+        type: 'confirm',
+        name: 'retry',
+        message: 'Try manual key entry instead?',
+        initial: true,
+      });
+      if (fallback.retry) {
+        return manualKeyEntry();
+      }
+      return null;
+    }
+    return key;
+  }
+
+  return manualKeyEntry();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/config.mjs

@@ -0,0 +1,13 @@
+/**
+ * Shared configuration for the SpriteCook CLI.
+ */
+
+/** Get the API base URL (env override for local dev/testing) */
+export function getApiBase() {
+  return process.env.SPRITECOOK_API_URL || 'https://api.spritecook.ai';
+}
+
+/** Get the MCP server URL */
+export function getMcpUrl() {
+  return `${getApiBase()}/mcp/`;
+}

package/src/editors.mjs

@@ -0,0 +1,214 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { success, warn, info } from './ui.mjs';
+import { getMcpUrl } from './config.mjs';
+
+/**
+ * Detect which editors/IDEs are available and return a list of
+ * { name, detected, configPath, write(apiKey) } objects.
+ */
+export function detectEditors() {
+  const cwd = process.cwd();
+  const home = homedir();
+  const editors = [];
+
+  // Cursor - project-level .cursor/mcp.json
+  const cursorDir = join(cwd, '.cursor');
+  editors.push({
+    name: 'Cursor',
+    detected: existsSync(cursorDir),
+    configPath: join(cursorDir, 'mcp.json'),
+    write: (apiKey) => writeCursorConfig(cursorDir, apiKey),
+  });
+
+  // VS Code - project-level .vscode/settings.json
+  const vscodeDir = join(cwd, '.vscode');
+  editors.push({
+    name: 'VS Code',
+    detected: existsSync(vscodeDir),
+    configPath: join(vscodeDir, 'settings.json'),
+    write: (apiKey) => writeVSCodeConfig(vscodeDir, apiKey),
+  });
+
+  // Claude Desktop - platform-specific
+  const claudeDesktopPath = getClaudeDesktopConfigPath();
+  editors.push({
+    name: 'Claude Desktop',
+    detected: claudeDesktopPath ? existsSync(join(claudeDesktopPath, '..')) : false,
+    configPath: claudeDesktopPath,
+    write: (apiKey) => writeClaudeDesktopConfig(claudeDesktopPath, apiKey),
+  });
+
+  // Claude Code - ~/.claude.json or ~/.claude/settings.json
+  const claudeCodePath1 = join(home, '.claude.json');
+  const claudeCodePath2 = join(home, '.claude', 'settings.json');
+  const claudeCodeDetected = existsSync(claudeCodePath1) || existsSync(claudeCodePath2);
+  const claudeCodeConfigPath = existsSync(claudeCodePath2) ? claudeCodePath2 : claudeCodePath1;
+  editors.push({
+    name: 'Claude Code',
+    detected: claudeCodeDetected,
+    configPath: claudeCodeConfigPath,
+    write: (apiKey) => writeClaudeCodeConfig(claudeCodeConfigPath, apiKey),
+  });
+
+  return editors;
+}
+
+/**
+ * Write MCP config for all detected editors.
+ * Returns the count of configs successfully written.
+ */
+export function writeConfigs(editors, apiKey) {
+  let written = 0;
+
+  for (const editor of editors) {
+    if (!editor.detected) continue;
+
+    try {
+      editor.write(apiKey);
+      success(`${editor.configPath}`);
+      written++;
+    } catch (err) {
+      warn(`Failed to write ${editor.name} config: ${err.message}`);
+    }
+  }
+
+  return written;
+}
+
+// ── Writer Functions ────────────────────────────────────────────────────
+
+function writeCursorConfig(cursorDir, apiKey) {
+  const configPath = join(cursorDir, 'mcp.json');
+  const mcpUrl = getMcpUrl();
+
+  // Read existing config or start fresh
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Corrupted file, start fresh
+    }
+  }
+
+  // Merge the spritecook server entry
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers.spritecook = {
+    url: mcpUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+
+  ensureDir(cursorDir);
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+function writeVSCodeConfig(vscodeDir, apiKey) {
+  const configPath = join(vscodeDir, 'settings.json');
+  const mcpUrl = getMcpUrl();
+
+  // Read existing config or start fresh
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Corrupted file, start fresh
+    }
+  }
+
+  // Merge into mcp.servers without overwriting other servers
+  if (!config.mcp) config.mcp = {};
+  if (!config.mcp.servers) config.mcp.servers = {};
+  config.mcp.servers.spritecook = {
+    type: 'http',
+    url: mcpUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+
+  ensureDir(vscodeDir);
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+function writeClaudeDesktopConfig(configPath, apiKey) {
+  if (!configPath) {
+    warn('Claude Desktop config path not found for this platform.');
+    return;
+  }
+  const mcpUrl = getMcpUrl();
+
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers.spritecook = {
+    url: mcpUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+
+  ensureDir(join(configPath, '..'));
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+function writeClaudeCodeConfig(configPath, apiKey) {
+  const mcpUrl = getMcpUrl();
+
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers.spritecook = {
+    url: mcpUrl,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+  };
+
+  ensureDir(join(configPath, '..'));
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function getClaudeDesktopConfigPath() {
+  const platform = process.platform;
+  const home = homedir();
+
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  if (platform === 'win32') {
+    const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+    return join(appData, 'Claude', 'claude_desktop_config.json');
+  }
+  if (platform === 'linux') {
+    return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+  }
+
+  return null;
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}

package/src/setup.mjs

@@ -0,0 +1,76 @@
+import chalk from 'chalk';
+import { printBanner, step, success, info, warn, error } from './ui.mjs';
+import { authenticate } from './auth.mjs';
+import { verifyApiKey } from './verify.mjs';
+import { detectEditors, writeConfigs } from './editors.mjs';
+import { maybeInstallSkill } from './skill.mjs';
+
+/**
+ * Main setup flow orchestrator.
+ * Called by bin/cli.mjs as the entry point.
+ */
+export async function run() {
+  printBanner();
+
+  // ── Step 1: Authenticate ──────────────────────────────────────────
+  step(1, 'Authentication');
+
+  const apiKey = await authenticate();
+  if (!apiKey) {
+    console.log();
+    error('Setup cancelled. No API key obtained.');
+    process.exit(1);
+  }
+
+  // ── Step 2: Verify the key works ──────────────────────────────────
+  step(2, 'Verification');
+
+  const verification = await verifyApiKey(apiKey);
+  if (!verification.ok) {
+    error('API key verification failed. Please check your key and try again.');
+    process.exit(1);
+  }
+
+  // ── Step 3: Detect editors and write configs ──────────────────────
+  step(3, 'Editor Configuration');
+
+  const editors = detectEditors();
+  const detected = editors.filter((e) => e.detected);
+
+  if (detected.length === 0) {
+    warn('No supported editors detected in the current directory.');
+    info('Supported editors: Cursor, VS Code, Claude Desktop, Claude Code');
+    info('Run this command from your project root where .cursor/ or .vscode/ exists.');
+    console.log();
+    info('You can also configure manually. Your API key:');
+    console.log(`  ${chalk.dim(apiKey.slice(0, 16) + '...')}`);
+  } else {
+    console.log();
+    info('Detected editors:');
+    for (const editor of editors) {
+      const mark = editor.detected ? chalk.green('[x]') : chalk.dim('[ ]');
+      const label = editor.detected ? editor.name : chalk.dim(`${editor.name} (not found)`);
+      console.log(`    ${mark} ${label}`);
+    }
+
+    console.log();
+    info('Writing MCP config...');
+    const written = writeConfigs(detected, apiKey);
+
+    if (written === 0) {
+      warn('No configs were written. You may need to configure manually.');
+    }
+  }
+
+  // ── Step 4: Optional agent skill ─────────────────────────────────
+  step(4, 'Agent Skill (optional)');
+  await maybeInstallSkill();
+
+  // ── Done ──────────────────────────────────────────────────────────
+  console.log();
+  console.log(chalk.bold.green('  Setup complete!'));
+  console.log();
+  console.log(chalk.dim('  Try asking your AI agent:'));
+  console.log(chalk.white('  "Generate a 64x64 pixel art sword sprite"'));
+  console.log();
+}

package/src/skill.mjs

@@ -0,0 +1,73 @@
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import prompts from 'prompts';
+import { success, info } from './ui.mjs';
+
+const SKILL_CONTENT = `# SpriteCook - AI Game Asset Generator
+
+Use SpriteCook MCP tools when the user needs pixel art sprites, game assets, icons, or visual game content.
+
+## When to use
+
+- User asks to "generate a sprite", "create pixel art", "make a game asset", "create an icon"
+- User needs visual assets for a game project (characters, items, backgrounds, UI elements)
+- User references game art, sprites, or pixel art in their request
+
+## Available MCP Tools
+
+### generate_pixel_art
+Generate pixel art or detailed game assets from a text prompt.
+
+**Parameters:**
+- \`prompt\` (required): Description of what to generate (e.g. "a medieval knight with a sword")
+- \`pixel\` (optional, default true): Whether to generate pixel art style
+- \`size\` (optional, default 64): Sprite size in pixels (16, 32, 64, 128, 256, 512)
+- \`background\` (optional, default "transparent"): Background mode ("transparent", "white", "include")
+
+### check_job_status
+Check the status of a generation job. Returns progress and result URLs when complete.
+
+### get_credit_balance
+Check remaining credits on the connected SpriteCook account.
+
+## Tips
+
+- For game characters: use size 64 or 128 with transparent background
+- For icons/items: use size 32 or 64 with transparent background
+- For tilesets/backgrounds: use size 128 or 256 with "include" background
+- Be specific in prompts: "a red dragon breathing fire, side view" works better than "dragon"
+- The tool returns download URLs for the generated images
+`;
+
+/**
+ * Optionally install the SpriteCook agent skill for Cursor.
+ * Only offered if .cursor/ directory exists.
+ */
+export async function maybeInstallSkill() {
+  const cwd = process.cwd();
+  const cursorDir = join(cwd, '.cursor');
+
+  if (!existsSync(cursorDir)) {
+    return; // Cursor not detected, skip silently
+  }
+
+  const response = await prompts({
+    type: 'confirm',
+    name: 'install',
+    message: 'Install SpriteCook agent skill for Cursor? (helps AI use SpriteCook proactively)',
+    initial: true,
+  });
+
+  if (!response.install) {
+    return;
+  }
+
+  const skillDir = join(cursorDir, 'skills', 'spritecook');
+  if (!existsSync(skillDir)) {
+    mkdirSync(skillDir, { recursive: true });
+  }
+
+  const skillPath = join(skillDir, 'SKILL.md');
+  writeFileSync(skillPath, SKILL_CONTENT, 'utf-8');
+  success(`Agent skill installed at .cursor/skills/spritecook/SKILL.md`);
+}

package/src/ui.mjs

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+import ora from 'ora';
+
+/** Print the SpriteCook header banner */
+export function printBanner() {
+  console.log();
+  console.log(chalk.bold('  SpriteCook MCP Setup'));
+  console.log(chalk.dim('  Connect your AI agent to SpriteCook'));
+  console.log();
+}
+
+/** Print a success message */
+export function success(msg) {
+  console.log(chalk.green('  [ok]') + ' ' + msg);
+}
+
+/** Print an info message */
+export function info(msg) {
+  console.log(chalk.blue('  [info]') + ' ' + msg);
+}
+
+/** Print a warning message */
+export function warn(msg) {
+  console.log(chalk.yellow('  [warn]') + ' ' + msg);
+}
+
+/** Print an error message */
+export function error(msg) {
+  console.log(chalk.red('  [error]') + ' ' + msg);
+}
+
+/** Create a spinner */
+export function spinner(text) {
+  return ora({ text: '  ' + text, color: 'cyan' });
+}
+
+/** Print a step header */
+export function step(num, msg) {
+  console.log();
+  console.log(chalk.bold.white(`  ${num}. ${msg}`));
+}

package/src/verify.mjs

@@ -0,0 +1,41 @@
+import { spinner, success, error } from './ui.mjs';
+import { getApiBase } from './config.mjs';
+
+/**
+ * Verify an API key by calling the credits endpoint.
+ * Returns { ok: boolean, credits?: number, tier?: string }
+ */
+export async function verifyApiKey(apiKey) {
+  const spin = spinner('Verifying API key...');
+  spin.start();
+
+  try {
+    const res = await fetch(`${getApiBase()}/v1/api/credits`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    if (!res.ok) {
+      spin.fail('  Verification failed');
+      const body = await res.text();
+      if (res.status === 401) {
+        error('Invalid or expired API key.');
+      } else {
+        error(`API returned ${res.status}: ${body}`);
+      }
+      return { ok: false };
+    }
+
+    const data = await res.json();
+    const credits = data.credits ?? data.credits_remaining ?? 0;
+    const tier = data.tier || data.subscription_tier || 'free';
+
+    spin.succeed(`  Verified! (${credits} credits, ${tier} tier)`);
+    return { ok: true, credits, tier };
+  } catch (err) {
+    spin.fail('  Verification failed');
+    error(`Could not reach SpriteCook API: ${err.message || err}`);
+    return { ok: false };
+  }
+}

package/index.js

@@ -1,8 +0,0 @@
-// SpriteCook MCP Server - Model Context Protocol server for AI-powered pixel art generation
-// This package is a placeholder. Full MCP server package coming soon.
-// Visit https://spritecook.ai for more information.
-
-module.exports = {
-  version: "0.0.1",
-  message: "SpriteCook MCP Server coming soon. Visit https://spritecook.ai for more information.",
-};