{"_id":"@brainy.ink/studio-agent-kit","_rev":"2-fafb9720f01809ed8e03fdd250d8ae13","name":"@brainy.ink/studio-agent-kit","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@brainy.ink/studio-agent-kit","version":"0.1.0","keywords":["brainy","studio","intake","agent","mcp","cli","design","quote"],"author":{"name":"Brainy Circles OÜ"},"license":"MIT","_id":"@brainy.ink/studio-agent-kit@0.1.0","maintainers":[{"name":"brainyron","email":"ron@brainycircles.com"}],"homepage":"https://studio.brainy.ink","bin":{"studio-mcp":"mcp-server.mjs","studio-intake":"cli.mjs"},"dist":{"shasum":"498a0e11f122fd71d46091469e9e97a2dd14a550","tarball":"https://registry.npmjs.org/@brainy.ink/studio-agent-kit/-/studio-agent-kit-0.1.0.tgz","fileCount":5,"integrity":"sha512-qVSzRJB4H7B6IPsomFuwgIlNemOJeX4MiSnApB6dn9fjPuGAI8K0639Aquy6ZLw45K6tTIk0PEkYwgUyMqyLgw==","signatures":[{"sig":"MEQCIAS6ROwFm89BQfhRTsPG+0rMuxvSdaYCGZv7Eb3Uhp5+AiBOpVZ2xOtDKRIJVKo5NmSd76YKjQQzss81lmMvvnh4dQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23792},"type":"module","engines":{"node":">=18"},"scripts":{"cli":"node cli.mjs","mcp":"node mcp-server.mjs"},"_npmUser":{"name":"brainyron","email":"ron@brainycircles.com"},"_npmVersion":"11.9.0","description":"Connectivity kit that lets any external AI agent (Claude Code, Cursor, an MCP client) or a CLI drive a Brainy Studio client intake end to end over the public HTTP API.","directories":{},"_nodeVersion":"24.14.0","dependencies":{"convex":"^1.17.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/studio-agent-kit_0.1.0_1783342998058_0.5866404897050794","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@brainy.ink/studio-agent-kit","version":"0.1.1","description":"Connectivity kit that lets any external AI agent (Claude Code, Cursor, an MCP client) or a CLI drive a Brainy Studio client intake end to end over the public HTTP API.","type":"module","license":"MIT","author":{"name":"Brainy Circles OÜ"},"homepage":"https://studio.brainy.ink","keywords":["brainy","studio","intake","agent","mcp","cli","design","quote"],"publishConfig":{"access":"public"},"bin":{"studio-agent-kit":"cli.mjs","studio-intake":"cli.mjs","studio-mcp":"mcp-server.mjs"},"engines":{"node":">=18"},"scripts":{"mcp":"node mcp-server.mjs","cli":"node cli.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0"},"_id":"@brainy.ink/studio-agent-kit@0.1.1","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-CsNDP97cdozWd8I1xR4JoVsjg0puHbSsGLu93i9yssO5OKTM+AFTmk0hV3nR/iYgsBdd8jU4w3pRZ5zktJbEEQ==","shasum":"3f11d75be531600d9c18a5b69e97e8212f8b9709","tarball":"https://registry.npmjs.org/@brainy.ink/studio-agent-kit/-/studio-agent-kit-0.1.1.tgz","fileCount":5,"unpackedSize":24341,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF/zZNHMMeNC41invuF7EFTFZHwMaMLRr4XPO2cgpqM6AiAeuLQyuViPXxr77+q9UCtXesSpERWFb8RcNb6pItktEA=="}]},"_npmUser":{"name":"brainyron","email":"ron@brainycircles.com"},"directories":{},"maintainers":[{"name":"brainyron","email":"ron@brainycircles.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/studio-agent-kit_0.1.1_1783343590391_0.13073345606152098"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-06T13:03:17.958Z","modified":"2026-07-06T13:13:10.732Z","0.1.0":"2026-07-06T13:03:18.223Z","0.1.1":"2026-07-06T13:13:10.581Z"},"author":{"name":"Brainy Circles OÜ"},"license":"MIT","homepage":"https://studio.brainy.ink","keywords":["brainy","studio","intake","agent","mcp","cli","design","quote"],"description":"Connectivity kit that lets any external AI agent (Claude Code, Cursor, an MCP client) or a CLI drive a Brainy Studio client intake end to end over the public HTTP API.","maintainers":[{"name":"brainyron","email":"ron@brainycircles.com"}],"readme":"# @brainy.ink/studio-agent-kit\n\nThe connectivity kit for **Brainy Studio** client intake. It lets any external AI\nagent (Claude Code, Cursor, an MCP client), a CLI, or a plain `curl` take a\nproject a human already brainstormed and submit it to Studio end to end.\n\nThree ways in, all over the same public HTTP API:\n\n- **MCP server** (`mcp-server.mjs`) - tools an agent calls inside a chat.\n- **CLI** (`cli.mjs` / `studio-intake`) - drive intake from a shell or script.\n- **Raw HTTP** - `POST/GET` the `/api/intake/*` endpoints from any language.\n\n## How it works (30 seconds)\n\n1. **start** an anonymous session. You get a `sessionId` (the bearer for every\n   later call) and a `claimUrl` (where the human signs in to submit).\n2. **schema** - ask which structured field keys a service needs.\n3. **ingest** the brief you gathered. You get the live gate, price range, and a\n   `stillNeeded[]` list. Repeat to fill gaps.\n4. Hand the human the **claimUrl** to sign in and click *Request this project*.\n   The agent never submits (project ownership needs the signed-in client).\n\nNo auth is needed to start, ingest, chat, or read status: the unguessable\n`sessionId` is the bearer. Only the final submit needs the human signed in.\n\n## Install\n\nNo install needed, run it straight from npm:\n\n```bash\nnpx @brainy.ink/studio-agent-kit start\n```\n\nOr install the bins globally (`studio-intake` + `studio-mcp`):\n\n```bash\nnpm install -g @brainy.ink/studio-agent-kit\n```\n\nWorking from a checkout of this repo instead? `cd agent-kit && npm install`.\n\nRequires Node 18+ (global `fetch`).\n\n## Environment\n\n| Var | Default | Meaning |\n|-----|---------|---------|\n| `STUDIO_API_BASE` | `https://energized-narwhal-432.convex.site` (prod) | The Convex HTTP origin (the `.convex.site` host). Set to `https://hushed-perch-314.convex.site` for dev. |\n\nThe `.convex.site` host is the HTTP-actions surface of the matching\n`.convex.cloud` deployment. (Studio is also proxied at `studio.brainy.ink/api/*`\nin prod, which works too.)\n\n## MCP server\n\nRun it:\n\n```bash\nSTUDIO_API_BASE=https://energized-narwhal-432.convex.site node mcp-server.mjs\n```\n\nRegister it with your MCP client. Claude Code / Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"brainy-studio\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/agent-kit/mcp-server.mjs\"],\n      \"env\": {\n        \"STUDIO_API_BASE\": \"https://energized-narwhal-432.convex.site\"\n      }\n    }\n  }\n}\n```\n\nOr straight from npm, no install (recommended):\n\n```json\n{\n  \"mcpServers\": {\n    \"brainy-studio\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@brainy.ink/studio-agent-kit\", \"studio-mcp\"],\n      \"env\": { \"STUDIO_API_BASE\": \"https://energized-narwhal-432.convex.site\" }\n    }\n  }\n}\n```\n\n(After a global install, `\"command\": \"studio-mcp\"` works too.)\n\n### Tools\n\n| Tool | Does |\n|------|------|\n| `studio_start_intake` | Open a session. Returns `sessionId`, `claimUrl`, `opening`. |\n| `studio_get_schema` | Learn a service's field keys. Pass `{draft:{whatKind:\"website\"}}` or a `sessionId`. |\n| `studio_describe_project` | Ingest the brief. Returns gate + quote + `stillNeeded[]`. |\n| `studio_status` | Read live state (no mutation). |\n| `studio_chat` | Conversational fallback turn. |\n| `studio_submit_hint` | The `claimUrl` + exact handoff instructions for the human. |\n\n## CLI\n\n```bash\n# Open a session\nnode cli.mjs start\n# -> { \"sessionId\": \"...\", \"claimUrl\": \"https://studio.brainy.ink/intake?session=...\", \"opening\": \"...\" }\n\n# Learn a service's fields (whatKind values: website, branding, ...)\nnode cli.mjs schema --service website\nnode cli.mjs schema --session <sessionId>\n\n# Dump a brief (from a file or inline JSON)\nnode cli.mjs describe --session <sessionId> --file brief.json\nnode cli.mjs describe --session <sessionId> --json '{\"whatKind\":\"website\",\"build_intent\":\"new_site\"}'\n\n# Poll what is still needed\nnode cli.mjs status --session <sessionId>\n\n# Conversational fallback\nnode cli.mjs chat --session <sessionId> --message \"We need a 5-page marketing site\"\n```\n\nPublished, the same commands run over npm: `npx @brainy.ink/studio-agent-kit start` (or `studio-intake start` after a global install). Any subcommand works after the package name, e.g. `npx @brainy.ink/studio-agent-kit schema --service website`.\n\nEvery command prints JSON; pipe to `jq`.\n\n## Raw HTTP (curl)\n\n```bash\nBASE=https://energized-narwhal-432.convex.site\n\n# 1. start\ncurl -s -XPOST $BASE/api/intake/start | jq\n# 2. schema for a service\ncurl -s -XPOST $BASE/api/intake/schema -H 'content-type: application/json' \\\n  -d '{\"draft\":{\"whatKind\":\"website\"}}' | jq\n# 3. ingest the brief\ncurl -s -XPOST $BASE/api/intake/ingest -H 'content-type: application/json' \\\n  -d '{\"sessionId\":\"<id>\",\"fields\":{\"whatKind\":\"website\",\"build_intent\":\"new_site\",\"page_count_band\":\"5_10\"}}' | jq\n# 4. status\ncurl -s \"$BASE/api/intake/status?sessionId=<id>\" | jq\n# 5. (optional) chat fallback\ncurl -s -XPOST $BASE/api/intake/chat -H 'content-type: application/json' \\\n  -d '{\"sessionId\":\"<id>\",\"message\":\"...\"}' | jq\n```\n\n## The field contract\n\nYou send a flat map of **snake_case blueprint field keys** to `ingest`:\n\n- **Universal keys** the brain understands: `whatKind`, `journeyStage`,\n  `build_intent`, `budget_band`, `page_count_band`, `has_logo`, plus\n  `brandName`, `nameStatus`, `depth`, `complexity`, `modules`, and a freeform\n  `brief` object.\n- **Per-service keys**: always discover them with `schema` (the\n  `studio_get_schema` tool / `schema` command). It returns\n  `fields:[{key,label,kind,options,required,prompt}]` for the resolved service,\n  so you know exactly which keys + enum values to send.\n\n**Rule:** never invent values the human did not give. Leave a field out instead\nof guessing. Off-enum or unknown values are simply ignored by the gate.\n\n## Security model\n\n- Anonymous sessions: the `sessionId` is the bearer. Anyone with it can read and\n  fill that one session, nothing else.\n- The final submit (`requestProject`) requires the human signed in to Studio via\n  the `claimUrl`. The agent cannot create the project. That is by design.\n- CORS is permissive (`*`) on these endpoints because they are public anonymous\n  intake with no cookies and no credentials.\n\nSee `../docs/AGENT_API.md` for the full endpoint reference.\n","readmeFilename":"README.md"}