{
  // robot.info v0.1 — FrankenClaw
  //
  // Structured product manifest for AI agents. Paired with robot.install
  // (setup) and llms.txt (docs index). Spec: mnemo-cortex/ROBOT-INFO-SPEC.md.
  //
  // Single JSON object, UTF-8. JavaScript-style // line comments are
  // stripped before parsing.

  "robot_info_version": "0.2",

  "name": "FrankenClaw",
  "tagline": "MCP tool server giving AI agents hands — search, vision, browser, Shopify, NotebookLM, Google Drive, and more.",
  "summary": "FrankenClaw is a modular MCP tool server that gives AI agents real-world capabilities: web search, image analysis, browser automation, web scraping, Shopify Admin API, NotebookLM, Google Drive, and more. Tools are auto-discovered from a tools/ directory — add a tool by dropping a file, no server edits. API keys live in a single keys.json (default location configurable). Designed as a drop-in chassis: snap it together with Mnemo Cortex (memory) for a fully-equipped local agent stack.",
  "backstory": "Guy wanted Rocky to browse the web and scrape pages. He wanted Firecrawl before OpenClaw officially supported it, and the existing MCP options for browser automation were unreliable. OpenClaw's mcporter was iffy. So instead of waiting, Guy and the team built FrankenClaw — a modular MCP chassis where any tool can bolt on. Then they kept bolting: search, vision, Shopify, NotebookLM, Google Drive. Any tool hanging off of Franky is a FrankenTool. The name came from stitching different capabilities together into one creature — Frankenstein's toolbox.",
  "version": "0.3.3",
  "license": "MIT",
  "homepage": "https://projectsparks.ai/frankenclaw",
  "source": "https://github.com/GuyMannDude/frankenclaw",
  "contact": "guy@projectsparks.ai",
  "maintainer": "Project Sparks",

  "capabilities": [
    "Web search via SearXNG — returns structured results agents can act on directly.",
    "Image analysis (vision_analyze) — describe, extract text, answer questions about any image URL or local file. Uses a configurable vision model via OpenRouter.",
    "Browser task automation (browser_task) — control a real browser (Lightpanda by default): click, fill forms, screenshot, run JS. 14 actions, session persistence.",
    "Web scrape to clean markdown (web_scrape) — strip ads/nav from any page via Firecrawl.",
    "Shopify Admin API integration — read products, inventory, collections; per-call store routing so a single agent session can target multiple stores without restart.",
    "Google Drive — search and read files (Docs, Sheets, Slides, text).",
    "NotebookLM — create/list/rename/delete notebooks, add sources, ask questions, generate podcasts/videos/infographics, download artifacts.",
    "Auto-discovery of tool modules — drop a Python file in tools/, it appears in the tool list on next start. No server.py edits, no registration step.",
    "Msearch / Fsearch / Wsearch / Recall routing commands — disambiguate memory vs. web search so the model doesn't grab the wrong tool.",
    "Single API key store — keys.json read at runtime, never duplicated per tool. Location configurable via FRANKENCLAW_KEYS_PATH.",
    "Stdio MCP transport — works with any MCP-compatible client without extra config."
  ],

  "exposes": {
    "mcp_tools": [
      {"name": "search_web", "purpose": "Web search via SearXNG. Returns structured title/URL/snippet results."},
      {"name": "vision_analyze", "purpose": "Send an image (URL or local path) to a vision model and get back a description or answer to a question about it."},
      {"name": "web_scrape", "purpose": "Scrape any URL to clean markdown using Firecrawl — no ads, no nav. Formats: markdown, html, screenshot."},
      {"name": "browser_task", "purpose": "Control a real browser — click, fill forms, screenshot, run JS. 14 actions. Default engine: Lightpanda."},
      {"name": "gdrive_search", "purpose": "Search your Google Drive for files by name or content."},
      {"name": "gdrive_read", "purpose": "Read the contents of a Google Drive file (Docs / Sheets / Slides / text)."},
      {"name": "shopify_products", "purpose": "List, create, update, delete Shopify products. Accepts an optional `store` arg for per-call store routing."},
      {"name": "shopify_inventory", "purpose": "Manage inventory levels and locations. Per-call store routing supported."},
      {"name": "shopify_collections", "purpose": "Browse and manage Shopify product collections. Per-call store routing supported."},
      {"name": "notebooklm_manage", "purpose": "Create, list, rename, or delete NotebookLM notebooks."},
      {"name": "notebooklm_source", "purpose": "Add URLs, text, or files as sources to a NotebookLM notebook."},
      {"name": "notebooklm_generate", "purpose": "Generate podcasts, videos, infographics, slide decks, and more from a notebook."},
      {"name": "notebooklm_download", "purpose": "Download generated artifacts (audio, video, PDF, etc.) from NotebookLM."},
      {"name": "notebooklm_ask", "purpose": "Ask a question about the sources in a NotebookLM notebook."},
      {"name": "sparks_stats", "purpose": "Read Project Sparks site / Peter Widget visitor stats (specific to ProjectSparks.ai deployments)."}
    ],
    "cli": [
      {"command": "python3 server.py", "purpose": "Start the MCP server over stdio. Point any MCP client at this command."}
    ]
  },

  "install": {
    "robot_install": "./robot.install",
    "robot_install_sh": "./robot-install.sh",
    "manual_docs": "https://github.com/GuyMannDude/frankenclaw#install",
    "platforms": ["linux", "macos", "windows-wsl2"],
    "runtime": "python>=3.10",
    "dependencies": [
      "mcp[cli]>=1.0.0",
      "httpx>=0.27.0",
      "Pillow>=10.0.0",
      "notebooklm-py>=0.3.0",
      "google-auth>=2.0",
      "google-auth-oauthlib>=1.0",
      "google-api-python-client>=2.0",
      "Lightpanda (system binary, default /usr/local/bin/lightpanda) for browser_task"
    ]
  },

  "compatibility": {
    "mcp_hosts": [
      "Claude Desktop",
      "Claude Code",
      "OpenClaw",
      "Hermes Agent",
      "LM Studio",
      "AnythingLLM",
      "Open WebUI",
      "Agent Zero (Docker)",
      "Any stdio MCP client"
    ],
    "models": "Any tool-capable LLM. Vision tools require a model with image input support (GPT-4o, Claude 3+, Gemini 1.5+, LLaVA-family local models).",
    "protocols": ["MCP/2025-03-26", "stdio transport"]
  },

  "privacy": {
    "telemetry": "none",
    "data_location": "No persistent agent data. Stateless tool server — each call is independent. API keys stored locally in keys.json (default ~/.frankenclaw/keys.json or path set via FRANKENCLAW_KEYS_PATH).",
    "auth": "No auth layer. Runs locally over stdio. Access is scoped to whoever can invoke the server process.",
    "outbound_calls": [
      "SearXNG instance (configured via searxng_url) — only fires on search_web calls.",
      "OpenRouter (or other configured provider) — only fires on vision_analyze calls.",
      "Firecrawl API — only fires on web_scrape calls.",
      "Lightpanda or Playwright — local browser binary, only fires on browser_task calls.",
      "Shopify Admin API — only when shopify_* tools are invoked and credentials configured.",
      "Google Drive API — only when gdrive_* tools are invoked and credentials configured.",
      "NotebookLM — only when notebooklm_* tools are invoked and credentials configured."
    ]
  },

  "related": [
    {"name": "Mnemo Cortex", "url": "https://github.com/GuyMannDude/mnemo-cortex", "purpose": "Persistent memory layer. Pair with FrankenClaw for an agent with both hands and memory."},
    {"name": "Disco-Bus", "url": "https://github.com/GuyMannDude/disco-bus", "purpose": "Agent-to-agent messaging mesh. Pair with FrankenClaw for multi-agent setups where agents need both tools and direct messaging."},
    {"name": "robot.install", "url": "./robot.install", "purpose": "Non-interactive install manifest for this product."},
    {"name": "robot.info spec", "url": "https://github.com/GuyMannDude/mnemo-cortex/blob/master/ROBOT-INFO-SPEC.md", "purpose": "Schema specification for this manifest format."}
  ],

  "common_questions": [
    {
      "q": "What is FrankenClaw?",
      "a": "A modular MCP tool server that gives AI agents real-world capabilities — web search, vision, browser, web scrape, Shopify, NotebookLM, Google Drive. Drop a Python file in tools/ to add a new tool; no server edits required."
    },
    {
      "q": "How is it different from just using MCP directly?",
      "a": "FrankenClaw is a pre-built chassis with 15 tools already integrated and a drop-in module system. Building directly on MCP means writing the server, tool descriptors, key management, and error handling yourself. FrankenClaw does all of that — you just drop in tools."
    },
    {
      "q": "Does it work with Claude Desktop / Claude Code / OpenClaw?",
      "a": "Yes — all three, plus Hermes Agent, LM Studio, AnythingLLM, Open WebUI, Agent Zero, and any stdio MCP client. FrankenClaw is host-agnostic; each integration is one MCP config line pointing at python3 server.py."
    },
    {
      "q": "How does the keys.json work? Do I need a separate key store?",
      "a": "keys.json is a flat JSON file with one entry per provider (e.g. \"openrouter\", \"firecrawl\", \"shopify\"). Default path is ~/.frankenclaw/keys.json; override with FRANKENCLAW_KEYS_PATH. The robot-install.sh installer creates a template with empty placeholders and fills in any keys it finds in your install-time environment."
    },
    {
      "q": "What are the Msearch / Fsearch / Wsearch / Recall routing commands?",
      "a": "Plain-language prefixes you add to your agent's system prompt to disambiguate tool selection. 'Msearch X' hits Mnemo memory only; 'Fsearch X' hits FrankenClaw web search only. Without these, models often grab the wrong tool when both memory and web search are available. They work because no tool is literally named Msearch — the model can't reflexively misroute."
    },
    {
      "q": "How do I add a new tool?",
      "a": "Create a Python file in the tools/ directory with an async function and a docstring. FrankenClaw auto-discovers it on next start — no edits to server.py, no registration, no config changes. A module that fails to import is logged and skipped — the rest of the server still comes up."
    },
    {
      "q": "Does vision_analyze require a specific model?",
      "a": "Any model with image input support: GPT-4o, Claude 3+, Gemini 1.5+, or local vision models (LLaVA, BakLLaVA, Moondream). Configure the provider in ~/.frankenclaw/config.json (vision_provider + vision_model)."
    },
    {
      "q": "Does browser_task require Playwright?",
      "a": "No — the default engine is Lightpanda (faster, lighter than Chromium). Playwright is supported as an alternative engine if you need full Chromium features. browser_task is optional; FrankenClaw loads clean without it if no browser binary is available."
    },
    {
      "q": "Can I use FrankenClaw without Shopify / Google Drive / NotebookLM?",
      "a": "Yes. All tools are optional. If credentials for a provider aren't configured, the corresponding tool module fails to import and is silently skipped — the rest of the server still comes up. Smoke-test the install with robot-install.sh to see which tools loaded for your environment."
    },
    {
      "q": "Can a single agent talk to multiple Shopify stores?",
      "a": "Yes — as of 0.3.1, all three shopify_* tools accept an optional `store` argument (the keys.json entry name) for per-call routing. One agent session can target multiple stores without restart. Per-store token cache prevents oscillation."
    },
    {
      "q": "How do I install it without prompts (CI / agent install)?",
      "a": "Run ./robot-install.sh. It reads robot.install (a JSON manifest) and emits a single JSON result object on stdout including an mcp_snippet ready to paste into your MCP client config. Exit 0 = success. The smoke step imports every tool module and reports which loaded so you know what's available."
    },
    {
      "q": "Does it phone home?",
      "a": "No telemetry. Outbound calls only happen when specific tools are invoked and only to the providers you configure (SearXNG, OpenRouter, Firecrawl, Shopify, Google Drive, NotebookLM). Listed in robot.info under privacy.outbound_calls."
    }
  ],

  // ─── v0.2 user-facing layer ──────────────────────────────────────────
  // Plain-language sections an AI reads to explain FrankenClaw to a
  // non-developer user. Written for the human on the other side of the AI,
  // not for a dev.

  // Read when a user asks "what is this?" / "why would I use it?"
  "why": "Your AI is smart but it can't actually DO much on its own — it can't search the live web, look at a picture, click around a website, or read your Google Drive. FrankenClaw gives your AI hands. It's a little toolbox that plugs into your AI and lets it search the web, describe and read images, scrape pages into clean text, drive a real browser, manage a Shopify store, and create things in NotebookLM. You stay in control: it runs on your own computer, you pick which AI models do the work, and your keys never leave your machine. Want a new ability? Drop one small file in a folder and your AI has a new tool — no rewiring.",

  // Read when a user asks "how do I install this?" Written for someone who
  // has never opened a terminal. The easiest real path is: clone the repo,
  // install requirements, then point your AI host at server.py. Claude Code
  // users get a single one-line command.
  "install_steps": [
    {"step": 1, "instruction": "Make sure you have Python 3.12 or newer on your computer (FrankenClaw is written in Python)."},
    {"step": 2, "instruction": "Download FrankenClaw: run 'git clone https://github.com/GuyMannDude/frankenclaw.git' then go into the new 'frankenclaw' folder."},
    {"step": 3, "instruction": "Install the pieces it needs: run 'pip install -r requirements.txt' from inside that folder."},
    {"step": 4, "instruction": "Connect it to your AI. If you use Claude Code, it's one line: 'claude mcp add frankenclaw -- python3 /full/path/to/frankenclaw/server.py'. For other apps (Claude Desktop, LM Studio, AnythingLLM, etc.) paste the small config block from the README into that app's MCP settings, pointing at server.py with its full path."},
    {"step": 5, "instruction": "Prefer hands-off? Run './robot-install.sh' instead. It sets up a clean Python environment, installs everything, and prints a ready-to-paste 'mcp_snippet' you drop into your AI app's config — no path-juggling."},
    {"step": 6, "instruction": "Add only the keys for the tools you want. FrankenClaw reads a single file (default ~/.frankenclaw/keys.json) — e.g. an OpenRouter key for image analysis, a Firecrawl key for web scraping. Tools you don't have a key for are simply skipped; the rest still work."},
    {"step": 7, "instruction": "On Windows, install and run FrankenClaw inside WSL2 (the Linux layer for Windows) — that's the tested path, especially for the browser tool."}
  ],

  // Read when a user asks "does this work with X?" Name + how to connect.
  "works_with": [
    {"name": "Claude Code", "how": "One command: 'claude mcp add frankenclaw -- python3 /path/to/frankenclaw/server.py'. No file editing."},
    {"name": "Claude Desktop", "how": "Add a 'frankenclaw' entry to claude_desktop_config.json pointing at python3 + server.py, then restart Claude Desktop."},
    {"name": "LM Studio", "how": "Add the same command+args block to ~/.lmstudio/mcp.json (native MCP since v0.3.17), then restart LM Studio."},
    {"name": "AnythingLLM", "how": "Add it as an MCP server, then flip the workspace to 'Automatic' mode so tools fire without an @agent prefix."},
    {"name": "Open WebUI / Jan / LobeChat", "how": "Add a stdio MCP server in the app's settings GUI — command 'python3', argument the full path to server.py."},
    {"name": "Hermes Agent", "how": "'hermes mcp add frankenclaw -- python3 /path/to/server.py' (first-class MCP since v0.12.0)."},
    {"name": "OpenClaw", "how": "'openclaw mcp set frankenclaw' with the command+args, then 'openclaw gateway restart' to pick up the new tools."},
    {"name": "Agent Zero (Docker)", "how": "Add it to the in-container MCP config using container-side paths, not host paths."},
    {"name": "Ollama / llama.cpp", "how": "These don't speak MCP directly — bridge through MCPHost or ollmcp (Ollama) or pass --mcp-config to llama-server. Pair with a tool-capable model like qwen3."},
    {"name": "Mnemo Cortex", "how": "Sibling product: Mnemo gives your AI memory, FrankenClaw gives it hands. Just add both as MCP servers — they don't conflict and run side by side."}
  ],

  // Read when a user asks "how do I customize / extend this?" FrankenClaw
  // is a tool server, so this is a core feature.
  "extensibility": "Adding a new tool is the whole point. Create a Python file in the 'tools/' folder with one async function and a short docstring describing what it does and its arguments — then restart FrankenClaw. It auto-discovers the function and your AI can use it immediately. No editing server.py, no registration, no config. Helper functions whose names start with '_' are ignored, so you can keep private helpers in the same file. A tool that fails to load (say it's missing an API key) is quietly skipped — the rest of the toolbox still comes up. You also choose which AI models power tools like image analysis and which search/scrape backends to use, all from ~/.frankenclaw/config.json. Everything is MIT-licensed and built to be modified.",

  // The hidden 80% — things users rarely discover from docs. An AI surfaces
  // these when timely, not as a feature dump.
  "tips": [
    "If your AI grabs the wrong search tool, teach it routing words: 'Fsearch X' forces FrankenClaw's web search, 'Msearch X' forces Mnemo memory search. They work because no tool is literally named that — the word itself becomes the routing.",
    "Always use full (absolute) paths when you point an app at server.py. A relative path fails silently because the app launches FrankenClaw from the wrong folder.",
    "Use a tool-capable model. Some small local models narrate a tool call ('I'll search the web...') instead of actually making it. qwen3:8b is verified working; llama3.1:8b is known to fake calls.",
    "You don't need every tool. Skip the keys for Shopify, Google Drive, or NotebookLM and those tools just won't load — the rest of FrankenClaw works fine.",
    "One AI session can manage multiple Shopify stores: pass a 'store' argument naming the keys.json entry, and it targets that store for just that call — no restart, no env-var swap.",
    "The browser tool opens a real, visible browser window so you can watch your AI click, fill forms, and screenshot in real time.",
    "Run the installer's smoke test (./robot-install.sh) to see exactly which tools loaded for your setup and which are missing a dependency — so you know what to add if you want the full box.",
    "No telemetry, ever. FrankenClaw only reaches out when a specific tool runs, and only to the provider that tool uses (your SearXNG, OpenRouter, Firecrawl, etc.)."
  ],

  // Recent releases in plain language. An AI reads this when a user asks
  // "what's new?" Pulled from CHANGELOG.md — real versions only.
  "changelog": [
    {"version": "0.3.3", "date": "2026-05-28", "changes": ["Security fix: the saved Shopify login token is no longer readable by other users on the same computer. It's now written private (owner-only), matching how the Google Drive token was already handled."]},
    {"version": "0.3.2", "date": "2026-05-23", "changes": ["Fixed a setup mismatch: the installer saved your API keys in one place but the tools looked in another, so fresh installs couldn't find their keys. Both now agree on ~/.frankenclaw/keys.json, and old setups keep working with a gentle warning."]},
    {"version": "0.3.1", "date": "2026-05-04", "changes": ["One AI session can now talk to multiple Shopify stores — just name the store per request. No restart needed."]},
    {"version": "0.3.0", "date": "2026-05-04", "changes": ["Public-release cleanup: removed all Project-Sparks-specific names and defaults so a fresh user gets a stock, configurable toolbox.", "Corrected the tool count and documentation; made the Shopify, Google Drive, and search settings fully configurable."]},
    {"version": "0.2.0", "date": "2026-03-31", "changes": ["Switched the browser engine to a lighter, faster one (dropped the heavy full-Chromium dependency).", "Added the web_scrape tool to turn any page into clean, AI-ready text.", "Added auto-discovery: drop a Python file in tools/ and restart to add a new tool — no code edits."]}
  ],

  // Where to get help.
  "support": {
    "github_issues": "https://github.com/GuyMannDude/frankenclaw/issues",
    "homepage": "https://projectsparks.ai/frankenclaw",
    "docs": "https://github.com/GuyMannDude/frankenclaw#readme"
  },

  "generated_at": "2026-05-30T16:00:00Z",
  "spec_url": "https://github.com/GuyMannDude/mnemo-cortex/blob/master/ROBOT-INFO-SPEC.md"
}
