@linkbunny/mcp 0.1.4 → 0.1.6

package/README.md

@@ -4,10 +4,10 @@ A local stdio MCP server that lets your coding agent run LinkBunny nofollow link
 
 Its official MCP Registry name is `com.getlinkbunny/exchange`.
 
-These examples pin the `0.1.4` release.
+These examples pin the `0.1.6` release.
 
 ```sh
-npx -y @linkbunny/mcp@0.1.4
+npx -y @linkbunny/mcp@0.1.6
 ```
 
 Your MCP client starts this process and communicates over stdin/stdout. Running the command alone waits for protocol input. npm hosts package files; no LinkBunny MCP process is hosted. API requests go only to `https://api.getlinkbunny.com/v1` over HTTPS. There is no endpoint override, daemon, polling, automatic retry, publication, or tool chaining.
@@ -25,7 +25,7 @@ For [Codex](https://developers.openai.com/codex/mcp), after authorization merge
 ```toml
 [mcp_servers.linkbunny]
 command = "npx"
-args = ["-y", "@linkbunny/mcp@0.1.4", "--token-file", "/absolute/project/.env.linkbunny"]
+args = ["-y", "@linkbunny/mcp@0.1.6", "--token-file", "/absolute/project/.env.linkbunny"]
 ```
 
 Run `codex mcp list` from the intended project to check registration. Have the owner complete native trust, restart the client, and begin a fresh backing session in Codex or Agent Control before discovery. Same-process hot reload is not proven. Use `/mcp` to check the active server.
@@ -40,7 +40,7 @@ For [Claude Code](https://code.claude.com/docs/en/mcp), after authorization merg
       "command": "npx",
       "args": [
         "-y",
-        "@linkbunny/mcp@0.1.4",
+        "@linkbunny/mcp@0.1.6",
         "--token-file",
         "/absolute/project/.env.linkbunny"
       ]
@@ -59,7 +59,7 @@ For [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configurat
     "linkbunny": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@linkbunny/mcp@0.1.4"],
+      "args": ["-y", "@linkbunny/mcp@0.1.6"],
       "envFile": "${workspaceFolder}/.env.linkbunny"
     }
   }
@@ -82,7 +82,7 @@ An explicit file takes precedence over an inherited token; invalid files never f
 
 A package cached or downloaded by npm is not proof that a server is registered. Check initialization separately after saving the registration. Tokens saved in a secret store or repository environment file are not automatically loaded by the client.
 
-In the fresh session, ask the configured client to perform `initialize`, `tools/list`, `resources/list`, and `resources/read` for `linkbunny://guidance/skill`, then call `get_status` once. Expect server version `0.1.4`, exactly the six tools below, the guidance text, and a status result. `get_status` is read-only and proves token admission without reserving anything. Do not call any other tool to test configuration: even `check_in` can reserve an assignment. If a client cannot list or read resources, report that part as unverified; reading the web skill does not verify MCP resource access.
+In the fresh session, ask the configured client to perform `initialize`, `tools/list`, `resources/list`, and `resources/read` for `linkbunny://guidance/skill`, then call `get_status` once. Expect server version `0.1.6`, exactly the six tools below, the guidance text, and a status result. `get_status` is read-only and proves token admission without reserving anything. Do not call any other tool to test configuration: even `check_in` can reserve an assignment. If a client cannot list or read resources, report that part as unverified; reading the web skill does not verify MCP resource access.
 
 Discovery and resource reads make no LinkBunny API requests. Startup validates token format locally, so only `get_status` proves API token admission and shows subscription state. For isolated discovery-only testing, use the synthetic example `LINKBUNNY_API_TOKEN=synthetic-discovery-only-not-a-real-token-00000000`. It passes the local format check but cannot authorize real API activity. Never substitute a production token merely to test package startup. Discovery-only tests must not invoke `create_profile`, `update_profile`, `check_in`, `report_assignment`, or `reject_assignment`.
 

package/dist/index.js

@@ -18,7 +18,7 @@ var STATUS_PAGE_LIMIT = 100;
 var REQUEST_TIMEOUT_MS = 1e4;
 var MAX_RESPONSE_BYTES = 1048576;
 var SKILL_URI = "linkbunny://guidance/skill";
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/privacy.ts
 function redact({
@@ -32,7 +32,7 @@ function redact({
 var errorMessages = {
   invalid_request: "Request payload or path is invalid. Review the canonical guidance and correct the authorized request.",
   unauthorized: "Credential rejected. Ask the owner to check their token in the private Account page.",
-  forbidden: "A paid LinkBunny subscription is required through https://getlinkbunny.com/account. Account and billing operations are not available through this MCP.",
+  forbidden: "The free exchange limit is reached or a paid LinkBunny subscription is required through https://getlinkbunny.com/account. Account and billing operations are not available through this MCP.",
   not_found: "The owned resource is unavailable. Confirm the retained canonical ID with the owner.",
   profile_conflict: "A live profile already exists for this domain. Recover its canonical ID from the private Account page.",
   idempotency_conflict: "A previous report or rejection has different details. Do not change details to force a retry.",
@@ -323,7 +323,7 @@ function createServer({
     {
       name: "create_profile",
       title: "Create profile",
-      description: "Register an owner-managed site only after specific registration authorization. Requires subscription. Retain the returned canonical profileID privately; await review without polling.",
+      description: "Register an owner-managed site only after specific registration authorization. Free accounts get one site. Retain the returned canonical profileID privately; await review without polling.",
       input: createInput,
       response: createResponse,
       method: "POST",
@@ -478,13 +478,17 @@ function statusNextAction(result) {
   }
   const { account, profiles, nextOffset } = result.data;
   const noAutomaticWrites = "Do not run any other LinkBunny tool automatically.";
-  if (!account.subscriptionActive) {
-    return `Tell the owner the paid LinkBunny subscription is not active; they can subscribe at ${ACCOUNT_URL}. Registration and check-in are unavailable until then. Any pending assignment listed here can still be reported or rejected with specific owner authorization. ${noAutomaticWrites}`;
-  }
+  const freeExchange = account.subscriptionActive ? [] : [
+    `This account has no paid subscription, so it uses the free exchange: one site, one reported placement and one received backlink. Each direction stops on its own: after the first placement is successfully reported, check_in issues no new assignments, and after the first backlink is reported, the site is no longer picked as a target for new assignments; the other direction stays open. Already issued assignments can still be reported within their normal window and settle, so either count can go above one. A 403 from create_profile or check_in means a free exchange limit is reached; the owner can subscribe at ${ACCOUNT_URL}.`
+  ];
   if (account.profileCount === 0) {
-    return `No sites are registered. Registering a site with create_profile needs the owner's specific registration authorization. ${noAutomaticWrites}`;
+    return [
+      ...freeExchange,
+      `No sites are registered. Registering a site with create_profile needs the owner's specific registration authorization. ${noAutomaticWrites}`
+    ].join(" ");
   }
   const steps = [
+    ...freeExchange,
     ...profiles.some((profile) => profile.pendingAssignment) ? [
       "Present each existing pending assignment to the owner for review instead of checking in to reserve more. Publication, report, and rejection each need separate owner authorization."
     ] : [],

package/dist/skill.md

@@ -15,10 +15,15 @@ publishing through the site's normal workflow, or rejects the request.
 
 1. A LinkBunny account is required. The human may create an account or log in at
    `https://getlinkbunny.com`; an agent may do so only with explicitly authorized browser control.
-2. An eligible paid subscription is required before entitled operations. The human must authorize
-   starting, changing, or cancelling billing; an authorized browser-capable agent may operate the
-   website UI for that approved action.
-3. With an active subscription, create an API token in the account UI. The human must authorize
+2. A new account can try one exchange free: one site, one completed link placement and one received
+   backlink, no card. Each direction stops on its own: after the site's first placement is
+   successfully reported, it gets no new assignments to place, and after its first backlink is
+   reported, it is no longer picked as the target of new assignments. The other direction stays
+   open. Assignments already issued can still be reported within their normal window and settle,
+   so a free site can end up with more than one placement or backlink. The paid subscription removes that limit and covers up to 10 sites. The human
+   must authorize starting, changing, or cancelling billing; an authorized browser-capable agent may
+   operate the website UI for that approved action.
+3. Create an API token in the account UI. The human must authorize
    each creation, rotation, or revocation; an authorized browser-capable agent may perform it. Copy
    the token once into an owner-approved secret store and keep it secret.
 4. Use that token for the public API workflow below. The public API does not provide signup, login,
@@ -35,14 +40,15 @@ may carry out an authorized API or site action only within the approval given.
 When the owner asks you to set up LinkBunny and has no account or API token yet:
 
 1. Plan locally. Inspect the project and propose one HTTPS target URL and one HTTPS area of the
-   site where nofollow links can go, both on the same registrable domain. Tell the owner the price
-   ($20/month for up to 10 sites, no per-link fees), that profiles are reviewed before they can
-   match, that some check-ins return no request, and which later steps need their approval. Make
-   no LinkBunny API call while there is no token.
+   site where nofollow links can go, both on the same registrable domain. Tell the owner the first
+   exchange is free for one site, the price after that ($20/month for up to 10 sites, no per-link
+   fees), that profiles are reviewed before they can match, that some check-ins return no request,
+   and which later steps need their approval. Make no LinkBunny API call while there is no token.
 2. With the owner's OK, open `https://getlinkbunny.com/login?redirect=%2Faccount%3Fsetup%3Dagent`
    in their browser, or print it when you cannot open a browser (for example in a cloud or remote
    session). Opening the link is not browser control: do not read, click, fill, or otherwise
-   operate the page. The owner signs in, subscribes, and creates the API token there.
+   operate the page. The owner signs in and creates the API token there. Subscribing is optional
+   for the free exchange.
 3. With the owner's OK, create a project file `.env.linkbunny` containing only an empty
    `LINKBUNNY_API_TOKEN=` line and make sure Git ignores it, or use another secret store the owner
    chooses. The owner pastes the token there. Never ask for the token in chat, and never print,
@@ -51,12 +57,12 @@ When the owner asks you to set up LinkBunny and has no account or API token yet:
    token out of command arguments and output, for example:
    `tr -d '\r' < .env.linkbunny | sed -nE 's/^(export )?LINKBUNNY_API_TOKEN="?([A-Za-z0-9._~-]+)"?$/header = "Authorization: Bearer \2"/p' | curl -sS -w '\nHTTP %{http_code}\n' --config - https://api.getlinkbunny.com/v1/me`.
    If the LinkBunny MCP server is already configured with that token file, its `get_status` tool
-   makes the same read. `subscriptionActive: true` confirms setup. `401` means the token is missing
-   or wrong in the file; `subscriptionActive: false` means the subscription is not confirmed yet,
-   so ask the owner to finish or refresh it on the account page. Do not poll; wait until the owner
-   says it is done again.
-5. Only after `subscriptionActive: true`, continue with "A — Create a profile". Ask the owner
-   before registering the site.
+   makes the same read. A `200` response confirms setup. `subscriptionActive: false` with
+   `siteLimit: 1` means the account is on the free exchange; `subscriptionActive: true` means the
+   paid plan is active. `401` means the token is missing or wrong in the file. Do not poll; wait
+   until the owner says it is done again.
+5. After a `200` status read, continue with "A — Create a profile". Ask the owner before
+   registering the site.
 
 ## Activation and approval gates
 
@@ -83,7 +89,8 @@ plain-language descriptions are enough.
 ## Safety contract
 
 - API base: `https://api.getlinkbunny.com/v1`.
-- Put the account token in `Authorization: Bearer <token>`.
+- Put the account token in `Authorization: Bearer <token>`. With curl, pass that header through
+  standard input (`--config -`), as in the examples, so the token never appears in command arguments.
 - Keep tokens in an owner-approved secret store. Never print, echo, log, paste into chat, include in screenshots, write to source/config tracked by Git, or commit them.
 - Register only sites the owner is authorized to manage.
 - Never send repository, hosting, deployment, or provider credentials to LinkBunny.
@@ -111,8 +118,8 @@ Present an existing pending assignment for owner review rather than checking in
 
 After specific authorization, `POST /profiles` with `targetURL`, `requestedAnchor`, one documented
 `category`, and `inventoryPrefix`. Both URLs must be public HTTPS URLs without credentials or
-fragments, on the same registrable domain. This operation requires an active subscription. A
-successful Domain Rating lookup returns `201` with status `pending_review`. LinkBunny reviews each
+fragments, on the same registrable domain. Without a subscription, an account can register one
+site for its free exchange. A successful Domain Rating lookup returns `201` with status `pending_review`. LinkBunny reviews each
 new profile once before it can match as a source or target. Tell the owner review is pending and
 suggest asking the agent to check again after the advisory interval or once approval is confirmed.
 Immediately record and retain the response's canonical `profileID` in the owner's approved private
@@ -143,11 +150,13 @@ only when no more specific category fits:
 After specific authorization, `PATCH /profiles/:profileID` accepts the same fields. Changing the
 target or inventory URL materially resets the profile to Domain Rating lookup and one-time review;
 it cannot match during re-review. Anchor- or category-only edits preserve an existing approval.
+Without a subscription, a URL change made within an hour of the site's creation or previous URL
+change waits up to an hour for its Domain Rating lookup and stays `pending` until then.
 
 ### B — Check in
 
-After specific authorization, `POST /profiles/:profileID/check-in`. This operation requires an
-active subscription. The response contains the same existing pending assignment, one newly
+After specific authorization, `POST /profiles/:profileID/check-in`. Without a subscription, the
+free exchange allows check-ins until the site's one placement is reported. The response contains the same existing pending assignment, one newly
 reserved assignment, or `{ "assignment": null }`. A profile awaiting review instead returns
 `{ "assignment": null, "status": "profile_pending_review", "message": "This site is awaiting marketplace review.", "retryAfterSeconds": 3600 }`;
 the one-hour interval is advisory, and every check-in still requires specific owner authorization.
@@ -184,7 +193,8 @@ calendar day. Pending, rejected, and expired/unreported assignments do not consu
 capacity; eligibility resets at the next UTC midnight.
 
 ```sh
-curl -X POST -H "Authorization: Bearer $LINKBUNNY_API_TOKEN" \
+printf 'header = "Authorization: Bearer %s"\n' "$LINKBUNNY_API_TOKEN" |
+  curl -X POST --config - \
   "https://api.getlinkbunny.com/v1/profiles/$LINKBUNNY_PROFILE_ID/check-in"
 ```
 
@@ -238,11 +248,13 @@ may return `409 terminal_conflict`. Expected errors use `{ "error": { "code", "m
 400 invalid request, 401 credential failure, 403 entitlement failure, 404 unavailable owned
 resource, or 409 terminal conflict.
 
-When create-profile or check-in returns a subscription-required `403`, tell the owner that a paid
-LinkBunny subscription is required and must be completed through the account website at
-`https://getlinkbunny.com/account`. Do not imply that signup, billing, or token creation is
-available through the public API. Report and reject remain available for already-issued
-assignments so they can be settled after entitlement ends.
+When create-profile, check-in, or profile update returns a `403` that mentions the free exchange or a
+subscription, relay its message: the free exchange covers one site and one reported placement, and
+the paid subscription at `https://getlinkbunny.com/account` adds more. A free site that already
+placed its link still stays eligible to receive its one backlink when a match comes up. Do not
+imply that signup, billing, or token creation is available through the public API. Report and
+reject never depend on a subscription: any issued assignment can be reported or reconsidered
+within the usual windows, including after entitlement ends or the free exchange is used.
 
 Pending assignments expire at their seven-day deadline. Expiration releases the reservation but
 does not permanently exclude the directional pair. Report completion for the exact original

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@linkbunny/mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@linkbunny/mcp",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/server": "2.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkbunny/mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "mcpName": "com.getlinkbunny/exchange",
   "description": "Local stdio MCP server for LinkBunny nofollow link exchanges. Requires a LinkBunny account API token.",
   "type": "module",