@soba-so/mcp 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @soba-so/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sets Soba up from inside your coding agent.
+
+```sh
+claude mcp add soba -- npx -y @soba-so/mcp --token mk_soba_…
+```
+
+The token is a **management key**, minted on the Integrate page of your Soba
+dashboard, which prints the whole line above with the key already in it. Then,
+in Claude Code:
+
+```
+/soba:set_up
+```
+
+Pair it with the skill, which carries the codebase half and works before any of
+this is connected:
+
+```sh
+npx skills add https://soba.so/skill
+```
+
+## What it does
+
+The step Soba's setup waits on is not dashboard work at all: it happens in your
+repo. The dashboard used to hand you a prompt, you carried it to your editor
+yourself, and the dashboard went blind afterwards.
+
+This closes that loop. The agent reads the checklist, does the next outstanding
+step, and reads it back — and the dashboard ticks along as it goes.
+
+| Tool | |
+|---|---|
+| `soba_status` | The checklist and which steps are done |
+| `soba_next_step` | The first outstanding one, with an instruction written for an agent |
+| `soba_create_key` | Mints your app's secret key, once |
+| `soba_set_connect_url` | Points Connect back at your app |
+| `soba_create_plan` | Creates a plan from numbers **you** gave it |
+
+## What it deliberately does not do
+
+**It never edits a file.** Your agent already has Read, Edit and Bash, already
+has the repo open, and already shows you its diffs. A second set of file tools
+tunnelled through this server would do the same job worse, somewhere you are not
+looking.
+
+**It cannot spend your money, and it cannot run as your users.** A management key
+is not your `sk_soba_` key and neither authenticates as the other. It can start
+one narrow kind of run — a *setup* run, on a machine you paired yourself — and
+two things bound that, both enforced where they already were rather than invented
+for this:
+
+- It runs under `development`, which allows exactly `user-hardware` and
+  `user-subscription`. There is nothing billable in that list, so a setup run
+  cannot reach metered supply however it is addressed.
+- It cannot choose whose machine to run on. The end user is pinned to your app's
+  own owner row by the gateway, not read from the request.
+
+It also never stamps `last_seen_at`, so an agent working on your behalf cannot
+make your dashboard claim your integration is live when it isn't.
+
+**It will not price your product.** `soba_create_plan` exists; there is no
+instruction telling an agent to call it. A plan is a price, an allowance, a
+ceiling and a reward, and those are decisions about your business.
+
+## Options
+
+| | |
+|---|---|
+| `--token mk_soba_…` | Your management key. `SOBA_MANAGEMENT_KEY` works too, and keeps it out of the process list. |
+| `--url` | The Soba instance. Defaults to `https://soba.so`. |
+
+No runtime dependencies. Node 22+.

package/dist/mcp.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+var u=class extends Error{constructor(e,r){super(r);this.status=e;this.name="ApiError"}},c=class{constructor(t,e){this.token=t;this.baseUrl=e}get(t){return this.call("GET",t)}post(t,e){return this.call("POST",t,e)}patch(t,e){return this.call("PATCH",t,e)}async call(t,e,r){let s=await fetch(`${this.baseUrl}${e}`,{method:t,headers:{authorization:`Bearer ${this.token}`,...r===void 0?{}:{"content-type":"application/json"}},body:r===void 0?void 0:JSON.stringify(r)}),o=await s.text(),i=null;try{i=o?JSON.parse(o):null}catch{throw new u(s.status,`${t} ${e} did not return json (${o.slice(0,120)})`)}if(!s.ok){let l=i?.error;throw new u(s.status,typeof l=="string"?l:`${t} ${e} failed with ${s.status}`)}return i}};var y=36e5,b=24*y,B={returnAfterMs:24*y,expiryMs:30*b,uniquenessMs:365*b};var H=10*6e4;var M=864e5,E=30,ee={abandonedAfterMs:E*M};var re=30*24*60*60*1e3;var oe=5*60*1e3;var _e=60*6e4;var T="https://soba.so/skill",ve=`npx skills add ${T}`;var w=`Soba is the LLM layer for an application whose users bring their own compute.
+Requests go to Soba instead of to a model provider; Soba routes each one to the
+machine or plan belonging to the user it names, meters it, and bills for it.
+
+## The two edits
+
+Two edits make a Soba app work. Everything after them makes it worth having, and
+an app that stops at two has nowhere for a run to land \u2014 so do these first, then
+keep going.
+
+### 1. Point every LLM call site at Soba
+
+    baseURL   https://api.soba.so/v1
+    apiKey    process.env.SOBA_KEY
+
+An OpenAI client already speaks this, so on most projects the base URL is the
+only line that changes. Prompts, tools, streaming and error handling stay
+exactly as they are.
+
+Pass the signed-in user's id as the \`user\` field on every request.
+
+**Resolve that id on the SERVER, from the session, never from the request
+body.** It is what decides whose machine a run may reach, so a value the browser
+can choose is a value any user can use to spend any other user's compute. This
+is the one line in the integration that must not be guessed at: if the project's
+auth is not obvious, read it until it is, or stop and ask. A wrong id here does
+not throw \u2014 it silently pairs runs to the wrong person.
+
+### Where the key comes from
+
+If \`.env.local\` already sets \`SOBA_KEY\`, use it. Otherwise run this from the
+project root:
+
+\`\`\`bash
+npx -y @soba-so/cli login
+\`\`\`
+
+It opens the person's browser, they pick the app, and it writes \`SOBA_KEY\` (a
+development key, for this machine) and \`SOBA_PROD_KEY\` (production) into
+\`.env.local\`, adding that file to \`.gitignore\` if git would commit it. The key
+never passes through you. Tell the person to approve in the browser before you
+run it; it waits up to fifteen minutes for them, so give the command a long
+timeout or run it in the background. Add \`--headless\` where no browser can
+open, and pass the link it prints on to the person.
+
+\`.env.local\` is right for Next.js, Vite and most Node servers. Where the code
+that holds the key reads a different file, pass that file with \`--env-file\`
+instead, from the project root, so the key lands where the server will look:
+
+| Server | File |
+|---|---|
+| Cloudflare Worker (\`wrangler dev\`) | \`--env-file <worker dir>/.dev.vars\` |
+| A server in a subfolder of a monorepo or an extension repo | \`--env-file <server dir>/.env.local\` |
+
+Find the file by reading how that server loads its environment, not by its
+framework's reputation. The CLI adds whatever file it writes to \`.gitignore\`
+if git would commit it.
+
+On a host that keeps secrets itself \u2014 \`wrangler secret put SOBA_KEY\`, Vercel's
+or Railway's environment \u2014 production takes \`SOBA_PROD_KEY\`'s value under the
+name \`SOBA_KEY\`. That is the person's to paste; tell them the command.
+
+A development key reaches only the user's own AI \u2014 their machine, their
+subscription, their API key. In production, \`SOBA_KEY\` is set to the value of
+\`SOBA_PROD_KEY\` in the host's environment; say so to the person rather than
+doing it.
+
+If you cannot run commands but have a \`soba_create_key\` tool, call it: the
+secret is returned once and nothing can show it again, so write it into
+\`.env.local\` in the same step. Failing both, ask the person to run the command
+above themselves. Do not leave \`SOBA_KEY\`
+empty and do not invent a value; both fail at the first request, and the first
+fails as an auth error rather than as a missing variable.
+
+Put \`SOBA_KEY\` in \`.env.local\` (or the server's own file, above), and check
+that file is gitignored before writing it. Never in \`.env\`, never in \`.env.example\`, never in anything
+tracked, and never echoed back to the terminal.
+
+### 2. Mount the connect component
+
+On the page where a user manages their own account, so they can connect a
+machine of their own:
+
+\`\`\`jsx
+import { SobaProvider, ConnectCompute } from "@soba-so/react";
+
+// Wherever a user manages their own account.
+<SobaProvider sessionEndpoint="/api/soba/session">
+  <ConnectCompute />
+</SobaProvider>
+\`\`\`
+
+Back it with \`POST /api/soba/session\`, a route in the customer's own app that
+proxies \`POST /v1/end_users/session\` using the secret key and the same
+server-resolved user id. It returns a short-lived \`est_\` credential. The
+browser never sees \`SOBA_KEY\`.
+
+Alongside it, \`<ComputeStatus />\`: asleep, offline, signed out of its CLI, or
+serving a run right now. When the compute is the user's own machine, the state of
+that machine is user-facing: they are the only one who can do anything about it.
+
+If there is no settings page yet, build one. Do not point the connect return URL
+at a page that does not render \`<ConnectCompute />\`.
+
+## The rest of the components, which are not optional in practice
+
+A settings page is where somebody checks on a machine they already attached. It
+is not where they decide to attach one, because nobody visits it wondering
+whether to. An app that mounts only \`<ConnectCompute />\` there has nowhere for a
+run to land until a user happens to wander in, and meets \`no_compute\` first.
+
+Put the decision where it is made. All of these come from \`@soba-so/react\`, and
+all of them raise the same modal \u2014 the provider mounts exactly one, so an app
+with all of them cannot put two pairings on screen at once.
+
+| Component | Where |
+|---|---|
+| \`<ModelPicker />\` | In the composer, beside the send button. Which of THEIR models answers |
+| \`<RunLimit />\` | Where a run just failed for a reason the user can fix. Render it in the place the answer was going to be |
+| \`<RunError />\` | Beside it, for every other failure. The two never both speak |
+| \`<ConnectNudge />\` | While the allowance is running down and they still have a choice |
+| \`<SobaBilling />\` | The current plan, then the grid. The billing page you probably want |
+| \`<SobaPlans showConnect />\` | A pricing page with no current-plan card on it |
+| \`<SobaCurrentPlan />\` | The card alone, when composing the page yourself |
+| \`<SobaCheckout />\` | Takes the payment and grants the entitlement |
+| \`<SobaGate feature="workspaces" />\` | Around anything a plan limits \u2014 a "New workspace" button, an export. Shows it while allowed, otherwise the reason and the plans |
+
+A gate draws the button; it does not secure the action. On the server, ask
+before you create: \`soba.users.check(user, "workspaces", { use: 1 })\` answers
+\`{ allowed, reason }\` and counts the use in the same call, so two requests for
+the last one cannot both get it. Record use you did not ask about with
+\`soba.users.track(user, "workspaces", -1)\` when one is deleted.
+
+Prices, allowances and the connected reward come from the plan objects, so
+changing them later is not a deploy. Pass \`showConnect\` only on a page with no
+current-plan card: a bring-your-own plan would otherwise state a requirement with
+no way to meet it.
+
+## Components or hooks: decide this by looking at the repo
+
+Both halves ship. **Every component above is one rendering of an exported hook,
+and the components derive nothing of their own** \u2014 so what you build from a hook
+and what we draw cannot disagree. Which half to reach for is not a matter of
+taste, and not a question to ask the person. Open the files first:
+
+**The app has no surface for this yet** \u2014 no settings page, no pricing page, a
+composer with nothing in its footer \u2014 then **mount the component.** It brings
+its own stylesheet, reads from the provider, and there is nothing left to
+decide. Do not build a settings page by hand so that you can fill it with hooks.
+
+**The app already has its own** \u2014 a chat composer with its own controls, a
+billing page in its own cards, a design system, Tailwind classes everywhere,
+anything that plainly belongs to somebody's product \u2014 then **import the hook and
+keep their markup.** Our CSS will not match the screen it lands on, and a card
+of ours in the middle of their chat reads as something the assistant said. The
+rules are ours; the pixels stay theirs.
+
+| Component | Hook | What the hook decides |
+|---|---|---|
+| \`<ModelPicker />\` | \`useModel()\` | Which models this person could be answered by, the one in force, and the two fields to put on the run |
+| \`<RunLimit />\` | \`useRunLimit()\` | The two failures a person can act on, and the offer that answers each |
+| \`<RunError />\` | \`runErrorMessage()\` | What to say about a failure, or null when it is not this one's to say |
+| \`<ConnectNudge />\` | \`useConnectNudge()\` | Whether there is anything worth saying at all, which of four reasons, and how big |
+| \`<ComputeStatus />\` | \`useCompute()\` | The machines in words, and "nothing connected" versus "we have not looked yet" |
+| \`<ConnectButton />\` | \`useConnectButton()\` | What the control says once something is attached, and what pressing it means |
+| \`<SobaPlans />\` | \`usePlans()\` | The catalogue as decisions: price, allowance, compute, the connect row, one \`take()\` per plan |
+| \`<SobaCurrentPlan />\` | \`useCurrentPlan()\` | The allowance arithmetic and the one sentence that is true of it |
+| \`<SobaCheckout />\` | \`useCheckout()\` | The session, the label, and the rule that nothing is granted in the browser |
+| \`<SobaGate />\` | \`useFeature()\` | Whether this person may use a feature, and why not: no plan, plan ended, not included, limit reached |
+
+\`<ConnectCompute />\`, \`<SobaBilling />\` and \`<ConnectModal />\` are compositions
+of the above and have no rule of their own. \`<ConnectPill />\` is the half of
+\`<ConnectButton />\` that reports \u2014 the mark, the state and the machine, with no
+popover under it and no flow behind it \u2014 for an app putting the readout in its
+own header and opening its own panel. Pressing it is yours to wire; everything
+it says is \`connectSays\`. \`<SobaProvider>\` is needed either way: the hooks
+read from it, so a hook with no provider above it is the one mistake this split
+invites.
+
+Two belong to no component of their own. \`useOpenSobaConnect()\` brings the
+Soba app forward on this person's machine and hands back the one honest thing a
+page can say about having tried \u2014 a browser cannot tell whether a \`soba://\`
+link was answered, and a page that claims it worked is guessing.
+\`useMachineRuns()\` is the "Running now" list out of \`<ConnectButton />\`'s
+panel with no panel around it: what this person's machines are running FOR THIS
+APP, and \`stop(runId)\` to end one as the person whose machine it is on. The app
+that started that run sees it finish with \`reason: "stopped_by_user"\`, which is
+the point: a surface built on this is a kill switch its owner holds, not a
+request to somebody's server.
+
+\`useRedeemCode()\` is a promo code field's behaviour: \`redeem(code)\` gives the
+user what the app's reward hands out \u2014 AI usage on top of their plan, a plan for
+some days, or a discount at their next checkout \u2014 and re-reads their plan, so
+the allowance on screen moves without a reload. Its \`error\` is a sentence ready
+to show. Put the field where somebody arrives with a code, usually the billing
+page. \`<RedeemCode />\` is that field already drawn \u2014 an input and an Apply
+button \u2014 for an app with no billing page of its own to put one in.
+
+\`useSoba()\` is the raw provider state. Reach for a named hook first and use
+this one for what no hook covers \u2014 \`run()\`, \`connect.open()\`,
+\`plan.refresh()\`. A page that reads \`compute.connected\` or \`plan.remaining\`
+straight off it is re-deriving a decision that is already exported, and the two
+copies are how our own apps drifted.
+
+### What not to write yourself
+
+These are not style preferences. Each one is a judgement this package already
+makes, and each has been got wrong in production \u2014 in our own code, which is why
+they are exported at all. If you find yourself writing one of them, delete it
+and import the answer:
+
+- **A list of model names.** The names come off the person's own machine, so a
+  list in your code refuses the model they can see on their own screen.
+  \`useModel()\` reads it from what they have connected.
+- **A model id on a run without its agent.** Soba applies a person's own agent
+  preference only to a run whose model is blank or a size, so a named model
+  travelling alone goes to whichever agent is found first. Spread
+  \`useModel().run\` whole \u2014 it is \`{ model, runtime? }\` \u2014 and have your route
+  forward both fields.
+- **"Nothing connected yet."** That is a claim about somebody's account and it
+  is only true once the account has been read. Said while the first request is
+  in flight, or after it failed, it tells a person with a paired laptop that it
+  has vanished. \`useCompute().view\` is the four-way answer.
+- **A match on an error message.** \`useRunLimit\` and \`runErrorMessage\` read the
+  CODE. Messages are prose we rewrite, and matching on them breaks on a copy
+  edit.
+- **Words for a cost class.** \`tierLabel(tier)\` is the one glossary for the five
+  economics this product is about. Four hand-written copies in this repo
+  disagreed with each other, and three reported somebody's own API key as
+  frontier supply the app had paid for.
+- **Where the pick is remembered, or how a stale one is handled.** A model whose
+  machine is gone falls back to Automatic and stays picked. \`useModel()\` does
+  that and tells you with \`unavailable\`.
+
+Read \`https://soba.so/docs/components\` for each hook's full shape.
+
+## Reaching Claude Code and Codex
+
+\`chat/completions\` is stateless and the caller owns the agent loop, so it
+reaches models. Reaching a user's own Claude or ChatGPT subscription means
+letting Soba own the loop instead:
+
+\`\`\`js
+import { Soba } from "@soba-so/sdk";
+import { sobaUserId } from "@soba-so/sdk/identity";
+
+const soba = new Soba({ apiKey: process.env.SOBA_KEY });
+
+const run = await soba.run({
+  // Derived from something that outlives your database. A primary key
+  // minted at sign-up is not: reset it and the same person arrives as
+  // somebody new, stranded from the machine they paired.
+  // https://soba.so/docs/identity
+  user: sobaUserId(session.user.username),
+  model: "auto",
+  prompt: "Summarise everything I saved this week",
+  tools: [listNotes, readNote],   // your code, executed in your app
+});
+\`\`\`
+
+Tools passed to a run execute in the customer's own process, so they can read
+the app's own data. The model asks for data by calling them; the data does not
+travel in the prompt.
+
+## Proving it
+
+\`soba/echo\` is answered by Soba itself \u2014 no machine, no metered supply,
+nothing billed \u2014 and still proves the key, the base URL and the \`user\` field:
+
+\`\`\`sh
+curl https://api.soba.so/v1/chat/completions \\
+  -H "Authorization: Bearer $SOBA_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{ "model": "soba/echo", "user": "usr_123",
+        "messages": [{ "role": "user", "content": "ping" }] }'
+\`\`\`
+
+A curl is evidence the credential works. It is NOT evidence the app is
+integrated \u2014 the dashboard's integrate step ticks on a request arriving from the
+real call site, and it cannot tell a curl from a deployment. Do not send one to
+make a checklist go green.
+
+## A new project rather than an existing one
+
+There is no separate procedure for this and no question to ask the person: look
+at the directory. If there is no app yet, run \`npx create-soba@latest\` and let
+it write one \u2014 it ships a correct \`/api/soba/session\`, which is the security
+boundary of the whole integration, and a plausible hand-written one is the
+failure mode that matters. Then the two edits above are already done and what
+remains is the key.
+
+## What is not yours to do
+
+Pairing is a person installing the Soba app on their own laptop and approving
+it. Pricing, allowances and rewards are decisions about somebody's business.
+Do neither on their behalf; say what is left and stop.`;var C=2.5*1e6,d=[{upTo:null,microsPerUnit:C}];var Ae=[{id:"hobby",name:"Hobby",feeMicros:19*1e6,includedActivations:12,seatLimit:2,appLimit:3,bands:d,features:["All three envelope dials: duration, volume and feature scope","3 projects","2 seats","Owner and Member roles","Activation counts","Docs support"]},{id:"starter",seatLimit:null,appLimit:null,name:"Starter",feeMicros:199*1e6,includedActivations:90,bands:d,features:["Unlimited projects","Unlimited seats","Admin and Billing roles","Cohort and conversion attribution","Email support"]},{id:"growth",seatLimit:null,appLimit:null,name:"Growth",feeMicros:599*1e6,includedActivations:300,bands:d,features:["Window A/B experimentation","Email support, one business day"]},{id:"scale",seatLimit:null,appLimit:null,name:"Scale",feeMicros:1999*1e6,includedActivations:1500,bands:d,features:["Custom roles and audit log","Effective-vs-configured window analytics","Shared channel with an SLA"]}];var p=[{name:"set_up",title:"Set Soba up in this repo",description:"Works through Soba's setup checklist one step at a time, editing this repo and showing you each diff.",text:`Set this project up on Soba, working from the real checklist rather than from memory.
+
+The loop, and keep to it:
+
+1. Call \`soba_status\`. That is the truth about what is done; nothing you did
+   earlier in this conversation counts until it shows up there.
+2. Call \`soba_next_step\` for the first outstanding one.
+3. Do it. The repo is yours to read and edit with your own tools \u2014 find the
+   actual LLM call sites rather than assuming where they are, and show me the
+   diff before you write anything.
+4. Call \`soba_status\` again. If the step did not flip, say so and work out why
+   instead of moving on. A step that silently did not take is the failure this
+   whole checklist exists to catch.
+5. Repeat until it says complete.
+
+Three things not to do:
+
+- Do not invent a plan. Pricing, allowances and rewards are decisions about my
+  business \u2014 ask me, and only then call \`soba_create_plan\`.
+- Do not put the secret key anywhere but \`.env.local\`, and check that file is
+  gitignored before you write it. Do not echo it back to the terminal.
+- Do not guess the connect return URL. It has to be a page that actually renders
+  \`<ConnectCompute />\`; if there isn't one yet, build it first.
+
+Start with \`soba_status\`.
+
+---
+
+What the codebase steps actually involve, so you are not working from memory
+there either:
+
+${w}`}],_=new Map(p.map(n=>[n.name,n]));function a(n){process.stderr.write(`soba-mcp: ${n}
+`)}function x(n){process.stdout.write(`${JSON.stringify(n)}
+`)}function k(n){let t="",e=new Set,r=!1,s=o=>{e.add(o),o.finally(()=>{e.delete(o),r&&e.size===0&&process.exit(0)})};process.stdin.setEncoding("utf8"),process.stdin.on("data",o=>{t+=o;let i=t.indexOf(`
+`);for(;i!==-1;){let l=t.slice(0,i).trim();t=t.slice(i+1),l&&s(I(l,n)),i=t.indexOf(`
+`)}}),process.stdin.on("end",()=>{r=!0,e.size===0&&process.exit(0),setTimeout(()=>process.exit(0),1e4).unref()})}async function I(n,t){let e;try{e=JSON.parse(n)}catch{a("ignored a line that was not json");return}let r=e.id===void 0||e.id===null;try{let s=await t(e.method,e.params??{});r||x({jsonrpc:"2.0",id:e.id,result:s})}catch(s){if(r)return;let o=s instanceof Error?s.message:String(s),i=o==="method not found"?-32601:-32603;x({jsonrpc:"2.0",id:e.id,error:{code:i,message:o}})}}var v={type:"object",properties:{},additionalProperties:!1};function S(n){let t=n.steps.map(r=>`${r.done?"[x]":"[ ]"} ${r.title} \u2014 ${r.state}`),e=n.complete?"Every step is done. Nothing here needs you again.":`Next: ${n.next}. Call soba_next_step for what to do.`;return`${t.join(`
+`)}
+
+${e}`}function P(n,t){return n.steps.find(e=>e.id===t)}var m=[{name:"soba_status",title:"Read the setup checklist",description:"Soba's setup checklist for this app and which steps are done. Call this first, and again after every change, so you are acting on what is true rather than on what you did last.",inputSchema:v,run:async n=>S(await n.get("/v1/manage/progress"))},{name:"soba_next_step",title:"What to do next",description:"The first outstanding step, with an instruction written for you. Do what it says using your own tools \u2014 read the repo, make the edits, show the diff. Then call soba_status again to confirm it took.",inputSchema:v,run:async n=>{let t=await n.get("/v1/manage/progress");if(t.complete)return"Setup is complete. There is nothing to do.";let e=P(t,t.next);return e?e.effect==="human"?e.id==="price"?`Next: ${e.title}
+
+${e.lede}
+
+This one is not yours to decide. Ask what the plan should cost, what it includes, and what connecting a machine earns back \u2014 then call soba_create_plan with the answers.`:e.id==="run"?`Next: ${e.title}
+
+${e.lede}
+
+There is nothing to do here and nothing to press. This step ticks when a request arrives from the app's own call site, so the way to finish it is to run the app and use it. A curl will not do it: the gateway stamps a key at authentication and cannot tell one from a deployment.`:`Next: ${e.title}
+
+${e.lede}
+
+This one is done in the dashboard, not from here \u2014 there is no tool on this server for it. Tell whoever asked to open the Set up page and take this step, then call soba_status to confirm it landed.`:`Next: ${e.title}  (${e.effect})
+
+${e.instruction??e.lede}
+
+When you are done, call soba_status to confirm it registered.`:S(t)}},{name:"soba_create_key",title:"Mint a secret key",description:"Mints this app's secret key and returns it ONCE. Write it straight into the project's .env.local as SOBA_KEY, confirm .env.local is gitignored, and do not print it back to the terminal or put it in a file that is committed.",inputSchema:{type:"object",properties:{name:{type:"string",description:"What to call it in the dashboard's key list."},environment:{type:"string",enum:["development","production"],description:"Defaults to production, like the dashboard. Only say development if this key is for a machine that never serves real users."}},additionalProperties:!1},run:async(n,t)=>{let e=await n.post("/v1/manage/keys",{name:t.name??"MCP",environment:t.environment});return`Created ${e.preview} (${e.environment}).
+
+SOBA_KEY=${e.key}
+
+This is the only time it exists. Put it in .env.local now.`}},{name:"soba_set_connect_url",title:"Point Connect back at the app",description:"Sets where someone who started pairing in their terminal gets sent to sign in. It must be the public https page that renders <ConnectCompute />. If no such page exists yet, do not guess one \u2014 build the page first.",inputSchema:{type:"object",properties:{url:{type:"string",description:"The https URL of the page. Loopback is allowed in development."}},required:["url"],additionalProperties:!1},run:async(n,t)=>(await n.patch("/v1/manage/app",{connect_return_url:t.url}),`Connect now returns to ${t.url}.`)},{name:"soba_create_plan",title:"Create a plan",description:"Creates a plan: the price, the allowance, what a run may fall back to, and what connecting a machine earns back. Only call this with numbers a person gave you. Do not invent a price.",inputSchema:{type:"object",properties:{name:{type:"string"},description:{type:"string"},price:{type:"number",description:"Dollars a month. 0 is a free plan."},unit:{type:"string",enum:["run","token","cost"],description:"What both allowances are counted in. `cost` counts hundredths of a cent (10,000 to the dollar); a token or cost overage price is per 1M tokens or per $1."},included_units:{type:["number","null"],description:"Runs a month on AI the app pays for (open-weights, frontier). Null is unlimited."},trial_days:{type:"number"},route_prefer:{type:"array",items:{type:"string",enum:["user-subscription","user-hardware","open-weights","frontier"]},description:"What a run may use, best first. This is also the ceiling: a class left out can never be billed to this app."},max_cost_per_run:{type:["number","null"],description:"Dollars one run may cost."},own_included_units:{type:["number","null"],description:"Runs a month on the user's own AI (their machine, subscription or key), counted apart from included_units. Null is unlimited."},own_unit:{type:["string","null"],enum:["run","token","credit","task",null],description:"What own_included_units counts, when not unit: a hybrid plan gives 200 runs on the user's own AI and 2,000 credits on yours. Null means the same as unit."},connected_reward:{type:"string",enum:["none","included","credit"]},connected_included_units:{type:["number","null"]},connected_credit:{type:["number","null"]}},required:["name","price","route_prefer"],additionalProperties:!1},run:async(n,t)=>{let e=await n.post("/v1/manage/plans",t);return`Created the plan "${e.name}"${e.id?` (${e.id})`:""}.`}},{name:"soba_give_reward",title:"Give a user a reward",description:"Gives one user a reward the app already has \u2014 money off, extra AI usage, or a plan for some days. Once per user per reward. Only call this when a person asked for that user to get it.",inputSchema:{type:"object",properties:{reward:{type:"string",description:"The reward's ID, e.g. early_bird."},user:{type:"string",description:"The app's own id for the user."}},required:["reward","user"],additionalProperties:!1},run:async(n,t)=>(await n.post("/v1/manage/rewards/give",t),`Gave ${t.user} the reward ${t.reward}.`)}],A=new Map(m.map(n=>[n.name,n]));var O="https://soba.so",U="2025-06-18",N="0.0.3";function L(n){let t={token:process.env.SOBA_MANAGEMENT_KEY??null,baseUrl:process.env.SOBA_MANAGE_URL??O};for(let e=0;e<n.length;e++){let r=n[e];r==="--token"?t.token=n[++e]??null:r?.startsWith("--token=")?t.token=r.slice(8):r==="--url"?t.baseUrl=n[++e]??t.baseUrl:r?.startsWith("--url=")&&(t.baseUrl=r.slice(6))}return t.baseUrl=t.baseUrl.replace(/\/+$/,""),t}var h=L(process.argv.slice(2)),g=h.token;g||(a("no management key. Pass --token mk_soba_\u2026 or set SOBA_MANAGEMENT_KEY."),a("Mint one in your Soba dashboard, on the Set up page."),process.exit(2));g.startsWith("mk_soba_")||(a("that is not a management key. It starts with mk_soba_, and sk_soba_ is a"),a("different credential \u2014 your app's secret key. Do not paste that here."),process.exit(2));var D=new c(g,h.baseUrl);k(async(n,t)=>{switch(n){case"initialize":return{protocolVersion:U,capabilities:{tools:{},prompts:{}},serverInfo:{name:"soba",version:N},instructions:"Soba's setup checklist. Call soba_status first, then soba_next_step, and do what it says with your own tools \u2014 the repo is yours to edit, not this server's. Call soba_status again afterwards to confirm the step registered rather than assuming it did."};case"notifications/initialized":case"notifications/cancelled":return{};case"ping":return{};case"prompts/list":return{prompts:p.map(e=>({name:e.name,title:e.title,description:e.description}))};case"prompts/get":{let e=typeof t.name=="string"?t.name:"",r=_.get(e);if(!r)throw new Error(`no such prompt: ${e}`);return{description:r.description,messages:[{role:"user",content:{type:"text",text:r.text}}]}}case"tools/list":return{tools:m.map(e=>({name:e.name,title:e.title,description:e.description,inputSchema:e.inputSchema}))};case"tools/call":{let e=typeof t.name=="string"?t.name:"",r=A.get(e);if(!r)return f(`no such tool: ${e}`);let s=t.arguments??{};try{return{content:[{type:"text",text:await r.run(D,s)}]}}catch(o){return o instanceof u?f(F(o)):f(o instanceof Error?o.message:String(o))}}default:throw new Error("method not found")}});function f(n){return{content:[{type:"text",text:n}],isError:!0}}function F(n){return n.status===401?"Soba refused the management key. It may have been revoked, or it may belong to a different app. Mint a new one on the Set up page.":n.message}a(`ready \u2014 ${m.length} tools, ${p.length} prompt against ${h.baseUrl}`);

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@soba-so/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.3",
+  "description": "Sets Soba up from inside your coding agent: it reads the checklist, does the next step, and reads it back.",
+  "license": "UNLICENSED",
+  "homepage": "https://soba.so/docs/quickstart",
+  "type": "module",
+  "bin": {
+    "soba-mcp": "dist/mcp.mjs"
+  },
+  "files": [
+    "dist/mcp.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-mcp.mjs",
+    "prepublishOnly": "node ../../scripts/build-mcp.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@soba-platform/core": "workspace:*"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "soba",
+    "mcp",
+    "claude",
+    "setup",
+    "byoc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreachello/soba.git",
+    "directory": "packages/soba-mcp"
+  }
+}