suggestionbox-connect 2.0.0__tar.gz

suggestionbox_connect-2.0.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# SuggestionBox Connect changelog
+
+## 2.0.0 — 2026-08-28
+
+- Identify the exact SuggestionBox bound to each Inbox credential using the
+  `suggestionbox` connection contract.
+- Rename the public client connection fields to `suggestionbox_name` and
+  `suggestionbox_slug`.
+- Require installed 1.x clients to upgrade; the removed `organization`
+  response and client attributes have no compatibility aliases.
+
+## 1.0.0 — 2026-08-17
+
+- Install SuggestionBox Connect as `suggestionbox-connect`, with the `sb`
+  command-line tool and `suggestionbox-mcp` AI-assistant connector included.
+- Connect and verify separate command-line, Codex, and Claude credentials using
+  the operating-system credential store.
+- Register the local MCP server and required operating-system environment with
+  one `sb connect codex` or `sb connect claude` command.
+- Add private Inbox items with a title, body, or both without copying one field
+  into the other.
+- Mark privately recorded requests with `--received` and accept body content
+  from standard input.
+- Inspect connection status and remove a saved credential without exposing it.
+- Run the add-only `suggestionbox-mcp` STDIO server from the same package.

suggestionbox_connect-2.0.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2026 KnowledgeTack LLC. All rights reserved.
+
+This software is proprietary. You may install and use it only to access the
+SuggestionBox.io service in accordance with the SuggestionBox.io Terms of
+Service at https://suggestionbox.io/terms/.
+
+No other license or rights are granted. The software is provided subject to
+the disclaimers and limitations of liability in those Terms.

suggestionbox_connect-2.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+include LICENSE
+include README.md

suggestionbox_connect-2.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: suggestionbox-connect
+Version: 2.0.0
+Summary: Connect your terminal and AI assistant to your private SuggestionBox.io Inbox.
+Author: KnowledgeTack LLC
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://suggestionbox.io/
+Project-URL: Changelog, https://pypi.org/project/suggestionbox-connect/#history
+Project-URL: Terms, https://suggestionbox.io/terms/
+Project-URL: Support, https://suggestionbox.io/terms/#contact
+Keywords: suggestionbox,suggestions,cli,mcp,ai,product-management
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keyring<26,>=25
+Dynamic: license-file
+
+# SuggestionBox Connect
+
+Connect your terminal and AI assistant to your private SuggestionBox.io Inbox.
+One installation provides the `sb` command-line tool and the
+`suggestionbox-mcp` AI-assistant connector.
+
+## Install
+
+Install SuggestionBox Connect in an isolated environment with
+[pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install suggestionbox-connect
+```
+
+SuggestionBox supports Python 3.10 through 3.14 on Linux, macOS, and Windows.
+
+## Connect
+
+1. Sign in to SuggestionBox.io and open **Inbox → Inbox settings**.
+2. In **Command line**, create a credential for this computer and copy it.
+3. Run:
+
+```bash
+sb connect
+```
+
+Paste the credential into the hidden prompt. The CLI verifies it before saving
+it in your operating system's credential store and names the exact
+SuggestionBox it belongs to. The credential can add private
+Inbox items only; it cannot read your Inbox or publish suggestions.
+
+Confirm the connection at any time:
+
+```bash
+sb status
+```
+
+## Add to Inbox
+
+Use a title, a body, or both:
+
+```bash
+sb add --title "Remember Inbox filters between visits"
+sb add --body "Show which CSV column failed validation."
+sb add --title "Scheduled exports" --body "Allow a weekly delivery schedule."
+```
+
+Pipe a longer body from another command:
+
+```bash
+printf '%s' "Add a dry-run option" | sb add --body -
+```
+
+Use `--received` when recording something that came from another person:
+
+```bash
+sb add --received --title "Customer requested a printable invoice"
+```
+
+Every successful command prints the private Inbox item ID and its owner-only
+review URL.
+
+## Disconnect, upgrade, or uninstall
+
+```bash
+sb disconnect
+pipx upgrade suggestionbox-connect
+pipx uninstall suggestionbox-connect
+```
+
+Deleting the credential in Inbox settings immediately prevents later use from
+this computer. `sb disconnect` removes the local copy but does not delete the
+server-side credential.
+
+## Automation
+
+For ephemeral automation, supply `SUGGESTIONBOX_INBOX_TOKEN` through the
+automation platform's secret store. Do not put an Inbox credential in a command,
+URL, project file, prompt, or log.
+
+## AI-assistant tool
+
+The same distribution includes the add-only `suggestionbox-mcp` STDIO
+server. Create and copy a separate **AI assistant** credential for each
+assistant, then run the matching command:
+
+```bash
+sb connect codex
+sb connect claude
+```
+
+Each command verifies and securely saves the credential, installs the MCP
+server in that assistant, and handles operating-system details internally.
+Start a new assistant session afterward. The MCP server cannot read or publish
+suggestions and acts only when the assistant invokes its single `add_to_inbox`
+tool.
+
+Check or remove either connection with:
+
+```bash
+sb status codex
+sb disconnect codex
+sb status claude
+sb disconnect claude
+```
+
+Use of this client and SuggestionBox.io is governed by the
+[SuggestionBox.io Terms of Service](https://suggestionbox.io/terms/). For help,
+contact [support@suggestionbox.io](mailto:support@suggestionbox.io).

suggestionbox_connect-2.0.0/README.md

@@ -0,0 +1,110 @@
+# SuggestionBox Connect
+
+Connect your terminal and AI assistant to your private SuggestionBox.io Inbox.
+One installation provides the `sb` command-line tool and the
+`suggestionbox-mcp` AI-assistant connector.
+
+## Install
+
+Install SuggestionBox Connect in an isolated environment with
+[pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install suggestionbox-connect
+```
+
+SuggestionBox supports Python 3.10 through 3.14 on Linux, macOS, and Windows.
+
+## Connect
+
+1. Sign in to SuggestionBox.io and open **Inbox → Inbox settings**.
+2. In **Command line**, create a credential for this computer and copy it.
+3. Run:
+
+```bash
+sb connect
+```
+
+Paste the credential into the hidden prompt. The CLI verifies it before saving
+it in your operating system's credential store and names the exact
+SuggestionBox it belongs to. The credential can add private
+Inbox items only; it cannot read your Inbox or publish suggestions.
+
+Confirm the connection at any time:
+
+```bash
+sb status
+```
+
+## Add to Inbox
+
+Use a title, a body, or both:
+
+```bash
+sb add --title "Remember Inbox filters between visits"
+sb add --body "Show which CSV column failed validation."
+sb add --title "Scheduled exports" --body "Allow a weekly delivery schedule."
+```
+
+Pipe a longer body from another command:
+
+```bash
+printf '%s' "Add a dry-run option" | sb add --body -
+```
+
+Use `--received` when recording something that came from another person:
+
+```bash
+sb add --received --title "Customer requested a printable invoice"
+```
+
+Every successful command prints the private Inbox item ID and its owner-only
+review URL.
+
+## Disconnect, upgrade, or uninstall
+
+```bash
+sb disconnect
+pipx upgrade suggestionbox-connect
+pipx uninstall suggestionbox-connect
+```
+
+Deleting the credential in Inbox settings immediately prevents later use from
+this computer. `sb disconnect` removes the local copy but does not delete the
+server-side credential.
+
+## Automation
+
+For ephemeral automation, supply `SUGGESTIONBOX_INBOX_TOKEN` through the
+automation platform's secret store. Do not put an Inbox credential in a command,
+URL, project file, prompt, or log.
+
+## AI-assistant tool
+
+The same distribution includes the add-only `suggestionbox-mcp` STDIO
+server. Create and copy a separate **AI assistant** credential for each
+assistant, then run the matching command:
+
+```bash
+sb connect codex
+sb connect claude
+```
+
+Each command verifies and securely saves the credential, installs the MCP
+server in that assistant, and handles operating-system details internally.
+Start a new assistant session afterward. The MCP server cannot read or publish
+suggestions and acts only when the assistant invokes its single `add_to_inbox`
+tool.
+
+Check or remove either connection with:
+
+```bash
+sb status codex
+sb disconnect codex
+sb status claude
+sb disconnect claude
+```
+
+Use of this client and SuggestionBox.io is governed by the
+[SuggestionBox.io Terms of Service](https://suggestionbox.io/terms/). For help,
+contact [support@suggestionbox.io](mailto:support@suggestionbox.io).

suggestionbox_connect-2.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "suggestionbox-connect"
+dynamic = ["version"]
+description = "Connect your terminal and AI assistant to your private SuggestionBox.io Inbox."
+readme = "README.md"
+authors = [{ name = "KnowledgeTack LLC" }]
+requires-python = ">=3.10,<3.15"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+dependencies = ["keyring>=25,<26"]
+keywords = ["suggestionbox", "suggestions", "cli", "mcp", "ai", "product-management"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://suggestionbox.io/"
+Changelog = "https://pypi.org/project/suggestionbox-connect/#history"
+Terms = "https://suggestionbox.io/terms/"
+Support = "https://suggestionbox.io/terms/#contact"
+
+[project.scripts]
+sb = "suggestionbox_connect.cli:main"
+suggestionbox-mcp = "suggestionbox_connect.mcp_server:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "suggestionbox_connect.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["suggestionbox_connect*"]

suggestionbox_connect-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

suggestionbox_connect-2.0.0/suggestionbox_connect/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

suggestionbox_connect-2.0.0/suggestionbox_connect/cli.py

@@ -0,0 +1,143 @@
+import argparse
+import getpass
+import os
+import sys
+
+from suggestionbox_connect import __version__
+from suggestionbox_connect.client import (
+    InboxClient,
+    InboxClientError,
+    InboxValidationError,
+    credential_environment_name,
+    delete_token,
+    save_token,
+)
+from suggestionbox_connect.integrations import (
+    ASSISTANT_LABELS,
+    register_assistant,
+    unregister_assistant,
+)
+
+
+def parser():
+    root = argparse.ArgumentParser(
+        prog="sb", description="Add a private thought to your SuggestionBox.io Inbox."
+    )
+    root.add_argument("--version", action="version", version=f"sb {__version__}")
+    commands = root.add_subparsers(dest="command", required=True)
+    add = commands.add_parser("add", help="Add one private unfinished thought.")
+    add.add_argument("--title", default="", help="Add an optional short title.")
+    add.add_argument(
+        "--body",
+        default="",
+        help="Add an optional body. Use - to read the body from standard input.",
+    )
+    add.add_argument("--source-url", default="")
+    add.add_argument(
+        "--received",
+        action="store_true",
+        help="Mark privately as received from someone.",
+    )
+    connect = commands.add_parser(
+        "connect",
+        help="Verify and save an Inbox credential securely.",
+    )
+    connect.add_argument(
+        "target",
+        choices=tuple(ASSISTANT_LABELS),
+        nargs="?",
+        help="Connect Codex or Claude and install its MCP server.",
+    )
+    status = commands.add_parser(
+        "status",
+        help="Verify the saved connection without reading Inbox contents.",
+    )
+    status.add_argument(
+        "target",
+        choices=tuple(ASSISTANT_LABELS),
+        nargs="?",
+        help="Check the command-line, Codex, or Claude connection.",
+    )
+    disconnect = commands.add_parser(
+        "disconnect",
+        help="Remove a saved Inbox credential from this device.",
+    )
+    disconnect.add_argument(
+        "target",
+        choices=tuple(ASSISTANT_LABELS),
+        nargs="?",
+        help="Disconnect command line, Codex, or Claude.",
+    )
+    return root
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "connect":
+            profile = args.target or "cli"
+            try:
+                token = getpass.getpass(
+                    "Paste the Inbox credential (input hidden): "
+                ).strip()
+            except (EOFError, KeyboardInterrupt):
+                raise InboxValidationError("Connection canceled.") from None
+            expected_adapter = "cli" if profile == "cli" else "mcp"
+            connection = InboxClient(token=token, profile=profile).connection(
+                expected_adapter=expected_adapter
+            )
+            save_token(token, profile=profile)
+            if args.target:
+                register_assistant(args.target)
+                label = ASSISTANT_LABELS[args.target]
+                print(
+                    f"{label} connected to {connection.suggestionbox_name} · "
+                    f"{connection.credential_label}. Start a new {label} session."
+                )
+            else:
+                print(
+                    f"Connected to {connection.suggestionbox_name} · "
+                    f"{connection.credential_label}"
+                )
+            return 0
+        if args.command == "status":
+            profile = args.target or "cli"
+            expected_adapter = "cli" if profile == "cli" else "mcp"
+            connection = InboxClient(profile=profile).connection(
+                expected_adapter=expected_adapter
+            )
+            print(
+                f"Connected to {connection.suggestionbox_name} · "
+                f"{connection.credential_label}"
+            )
+            return 0
+        if args.command == "disconnect":
+            profile = args.target or "cli"
+            removed = delete_token(profile=profile)
+            if args.target:
+                unregister_assistant(args.target)
+            environment_name = credential_environment_name(profile)
+            if os.environ.get(environment_name, "").strip():
+                print(
+                    f"Saved connection removed. {environment_name} is still set "
+                    "for this process."
+                )
+            else:
+                print("Disconnected." if removed else "No saved connection.")
+            return 0
+        body = sys.stdin.read() if args.body == "-" else args.body
+        result = InboxClient().add(
+            title=args.title,
+            body=body,
+            source_url=args.source_url,
+            origin_hint="received" if args.received else "",
+        )
+        print(f"Added to your Inbox · {result.inbox_item_id} · {result.review_url}")
+        return 0
+    except InboxClientError as error:
+        print(str(error), file=sys.stderr)
+        return error.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

suggestionbox_connect-2.0.0/suggestionbox_connect/client.py

@@ -0,0 +1,289 @@
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from uuid import uuid4
+
+from suggestionbox_connect import __version__
+
+
+DEFAULT_API_URL = "https://suggestionbox.io/api/v1/inbox-items/"
+PROFILE_ENVIRONMENT_NAMES = {
+    "cli": "SUGGESTIONBOX_INBOX_TOKEN",
+    "codex": "SUGGESTIONBOX_INBOX_CODEX_TOKEN",
+    "claude": "SUGGESTIONBOX_INBOX_CLAUDE_TOKEN",
+}
+
+
+class InboxClientError(RuntimeError):
+    exit_code = 6
+
+
+class InboxAuthenticationError(InboxClientError):
+    exit_code = 3
+
+
+class InboxValidationError(InboxClientError):
+    exit_code = 2
+
+
+class InboxRateLimitError(InboxClientError):
+    exit_code = 4
+
+
+class InboxNetworkError(InboxClientError):
+    exit_code = 5
+
+
+@dataclass(frozen=True)
+class InboxResult:
+    inbox_item_id: str
+    state: str
+    review_url: str
+
+
+@dataclass(frozen=True)
+class InboxConnection:
+    suggestionbox_name: str
+    suggestionbox_slug: str
+    credential_label: str
+    adapter: str
+
+
+def configured_token(profile="cli"):
+    environment_name = credential_environment_name(profile)
+    token = os.environ.get(environment_name, "").strip()
+    if token:
+        return token
+    try:
+        import keyring
+
+        return keyring.get_password("suggestionbox.io", f"inbox-token:{profile}") or ""
+    except Exception:
+        return ""
+
+
+def save_token(token, *, profile="cli"):
+    environment_name = credential_environment_name(profile)
+    if not token.startswith("sb_inbox_"):
+        raise InboxValidationError("That is not a SuggestionBox Inbox credential.")
+    try:
+        import keyring
+
+        keyring.set_password("suggestionbox.io", f"inbox-token:{profile}", token)
+    except Exception as error:
+        raise InboxValidationError(
+            "A secure operating-system credential store is unavailable. "
+            f"Use {environment_name} for an ephemeral process instead."
+        ) from error
+
+
+def delete_token(*, profile="cli"):
+    credential_environment_name(profile)
+    try:
+        import keyring
+        from keyring.errors import PasswordDeleteError
+
+        try:
+            keyring.delete_password("suggestionbox.io", f"inbox-token:{profile}")
+        except PasswordDeleteError:
+            return False
+        return True
+    except Exception as error:
+        raise InboxValidationError(
+            "The operating-system credential store is unavailable."
+        ) from error
+
+
+def credential_environment_name(profile):
+    try:
+        return PROFILE_ENVIRONMENT_NAMES[profile]
+    except KeyError:
+        raise InboxValidationError("Choose command line, Codex, or Claude.") from None
+
+
+class InboxClient:
+    def __init__(
+        self, *, token=None, profile="cli", api_url=None, timeout=8, opener=None
+    ):
+        selected_token = configured_token(profile) if token is None else token
+        self.token = selected_token.strip()
+        self.profile = profile
+        self.api_url = (
+            api_url or os.environ.get("SUGGESTIONBOX_INBOX_API_URL") or DEFAULT_API_URL
+        ).strip()
+        parsed_api_url = urllib.parse.urlsplit(self.api_url)
+        if (
+            parsed_api_url.scheme not in {"http", "https"}
+            or not parsed_api_url.hostname
+            or parsed_api_url.username
+            or parsed_api_url.password
+            or parsed_api_url.path != "/api/v1/inbox-items/"
+            or parsed_api_url.query
+            or parsed_api_url.fragment
+            or (
+                parsed_api_url.scheme != "https"
+                and parsed_api_url.hostname not in {"localhost", "127.0.0.1", "::1"}
+            )
+        ):
+            raise InboxValidationError(
+                "The Inbox API URL must use HTTPS; HTTP is allowed only for localhost."
+            )
+        self.timeout = timeout
+        self.opener = opener or urllib.request.urlopen
+
+    @property
+    def credential_url(self):
+        parsed = urllib.parse.urlsplit(self.api_url)
+        return urllib.parse.urlunsplit(
+            (
+                parsed.scheme,
+                parsed.netloc,
+                "/api/v1/inbox-credentials/current/",
+                "",
+                "",
+            )
+        )
+
+    def _authorization_header(self):
+        if not self.token:
+            environment_name = credential_environment_name(self.profile)
+            connect_command = (
+                "sb connect" if self.profile == "cli" else f"sb connect {self.profile}"
+            )
+            raise InboxAuthenticationError(
+                f"No Inbox credential is connected. Run `{connect_command}` or set "
+                f"{environment_name} for this process."
+            )
+        return f"Bearer {self.token}"
+
+    def _open_json(self, request):
+        for attempt in range(3):
+            try:
+                with self.opener(request, timeout=self.timeout) as response:
+                    try:
+                        return json.loads(response.read().decode("utf-8"))
+                    except (UnicodeDecodeError, json.JSONDecodeError, TypeError):
+                        raise InboxClientError(
+                            "SuggestionBox.io returned an invalid response."
+                        ) from None
+            except urllib.error.HTTPError as error:
+                try:
+                    detail = json.loads(error.read().decode("utf-8")).get(
+                        "detail", "Request failed."
+                    )
+                except Exception:
+                    detail = "Request failed."
+                if error.code in {401, 403}:
+                    raise InboxAuthenticationError(detail) from None
+                if error.code in {400, 409, 410, 413, 415, 422}:
+                    raise InboxValidationError(detail) from None
+                if error.code == 429:
+                    raise InboxRateLimitError(detail) from None
+                if 500 <= error.code < 600 and attempt < 2:
+                    time.sleep(0.15 * (attempt + 1))
+                    continue
+                raise InboxClientError(detail) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as error:
+                if attempt < 2:
+                    time.sleep(0.15 * (attempt + 1))
+                    continue
+                raise InboxNetworkError(
+                    "SuggestionBox.io could not be reached."
+                ) from error
+        raise InboxNetworkError("SuggestionBox.io could not be reached.")
+
+    def connection(self, *, expected_adapter=None):
+        request = urllib.request.Request(
+            self.credential_url,
+            method="GET",
+            headers={
+                "Authorization": self._authorization_header(),
+                "Accept": "application/json",
+                "User-Agent": f"suggestionbox-connect/{__version__}",
+            },
+        )
+        data = self._open_json(request)
+        try:
+            connection = InboxConnection(
+                suggestionbox_name=data["suggestionbox"]["name"],
+                suggestionbox_slug=data["suggestionbox"]["slug"],
+                credential_label=data["credential"]["label"],
+                adapter=data["credential"]["adapter"],
+            )
+        except (KeyError, TypeError):
+            raise InboxClientError(
+                "SuggestionBox.io returned an invalid response."
+            ) from None
+        if not all(
+            isinstance(value, str) and value.strip()
+            for value in (
+                connection.suggestionbox_name,
+                connection.suggestionbox_slug,
+                connection.credential_label,
+                connection.adapter,
+            )
+        ):
+            raise InboxClientError("SuggestionBox.io returned an invalid response.")
+        if expected_adapter and connection.adapter != expected_adapter:
+            expected_label = (
+                "AI assistant" if expected_adapter == "mcp" else "Command line"
+            )
+            raise InboxAuthenticationError(
+                f"That credential is not for {expected_label}. Create the matching credential in Inbox settings."
+            )
+        return connection
+
+    def add(
+        self,
+        *,
+        title="",
+        body="",
+        source_url="",
+        origin_hint="",
+        idempotency_key=None,
+    ):
+        authorization = self._authorization_header()
+        if not isinstance(title, str) or not isinstance(body, str):
+            raise InboxValidationError("Title and body must be text.")
+        title = title.strip()
+        body = body.strip()
+        if not title and not body:
+            raise InboxValidationError("Enter a title or body to add.")
+        if len(title) > 160:
+            raise InboxValidationError("Keep the title under 160 characters.")
+        if len(body) > 10_000:
+            raise InboxValidationError("Keep the body under 10,000 characters.")
+        payload = {"title": title, "body": body}
+        if source_url:
+            payload["source_url"] = source_url
+        if origin_hint:
+            payload["origin_hint"] = origin_hint
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        idempotency_key = idempotency_key or str(uuid4())
+        request = urllib.request.Request(
+            self.api_url,
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": authorization,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Idempotency-Key": idempotency_key,
+                "User-Agent": f"suggestionbox-connect/{__version__}",
+            },
+        )
+        data = self._open_json(request)
+        try:
+            return InboxResult(
+                inbox_item_id=data["inbox_item_id"],
+                state=data["state"],
+                review_url=data["review_url"],
+            )
+        except (KeyError, TypeError):
+            raise InboxClientError(
+                "SuggestionBox.io returned an invalid response."
+            ) from None

suggestionbox_connect-2.0.0/suggestionbox_connect/integrations.py

@@ -0,0 +1,97 @@
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from suggestionbox_connect.client import InboxValidationError
+
+
+MCP_SERVER_NAME = "suggestionbox"
+ASSISTANT_LABELS = {"codex": "Codex", "claude": "Claude"}
+
+
+def _required_executable(name):
+    executable = shutil.which(name)
+    if executable:
+        return executable
+    label = ASSISTANT_LABELS.get(name, name)
+    raise InboxValidationError(f"{label} is not installed or is not available on PATH.")
+
+
+def _mcp_executable():
+    executable = shutil.which("suggestionbox-mcp")
+    if executable:
+        return executable
+    filename = "suggestionbox-mcp.exe" if os.name == "nt" else "suggestionbox-mcp"
+    sibling = Path(sys.executable).with_name(filename)
+    if sibling.is_file():
+        return str(sibling)
+    raise InboxValidationError(
+        "suggestionbox-mcp is not installed. Reinstall SuggestionBox Connect."
+    )
+
+
+def _mcp_environment_arguments():
+    arguments = []
+    api_url = os.environ.get("SUGGESTIONBOX_INBOX_API_URL", "").strip()
+    if api_url:
+        arguments.extend(["--env", f"SUGGESTIONBOX_INBOX_API_URL={api_url}"])
+    dbus_address = os.environ.get("DBUS_SESSION_BUS_ADDRESS", "").strip()
+    if dbus_address:
+        arguments.extend(["--env", f"DBUS_SESSION_BUS_ADDRESS={dbus_address}"])
+    return arguments
+
+
+def _run(command):
+    try:
+        return subprocess.run(
+            command,
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise InboxValidationError(
+            "The AI assistant could not be configured. Try again."
+        ) from error
+
+
+def register_assistant(target):
+    if target not in ASSISTANT_LABELS:
+        raise InboxValidationError("Choose Codex or Claude.")
+    host = _required_executable(target)
+    mcp_server = _mcp_executable()
+    remove_command = [host, "mcp", "remove"]
+    if target == "claude":
+        remove_command.extend(["--scope", "user"])
+    remove_command.append(MCP_SERVER_NAME)
+    _run(remove_command)
+    command = [host, "mcp", "add"]
+    if target == "claude":
+        command.extend(["--scope", "user"])
+    command.append(MCP_SERVER_NAME)
+    command.extend(_mcp_environment_arguments())
+    command.extend(["--", mcp_server, "--profile", target])
+    result = _run(command)
+    if result.returncode:
+        detail = (result.stderr or result.stdout).strip()
+        label = ASSISTANT_LABELS[target]
+        message = f"{label} could not be configured."
+        if detail:
+            message = f"{message} {detail}"
+        raise InboxValidationError(message)
+
+
+def unregister_assistant(target):
+    if target not in ASSISTANT_LABELS:
+        raise InboxValidationError("Choose Codex or Claude.")
+    host = shutil.which(target)
+    if not host:
+        return
+    command = [host, "mcp", "remove"]
+    if target == "claude":
+        command.extend(["--scope", "user"])
+    command.append(MCP_SERVER_NAME)
+    _run(command)

suggestionbox_connect-2.0.0/suggestionbox_connect/mcp_server.py

@@ -0,0 +1,144 @@
+import argparse
+import json
+import sys
+
+from suggestionbox_connect import __version__
+from suggestionbox_connect.client import InboxClient, InboxClientError
+
+
+TOOL = {
+    "name": "add_to_inbox",
+    "description": (
+        "Store one private unfinished thought in the user's SuggestionBox.io Inbox. "
+        "This never publishes. Call only when the user explicitly asks to save or add the thought."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "title": {"type": "string", "maxLength": 160},
+            "body": {"type": "string", "maxLength": 10000},
+            "source_url": {"type": "string"},
+            "origin_hint": {"type": "string", "enum": ["", "owner", "received"]},
+        },
+        "anyOf": [{"required": ["title"]}, {"required": ["body"]}],
+        "additionalProperties": False,
+    },
+}
+
+
+def response(request_id, result=None, error=None):
+    payload = {"jsonrpc": "2.0", "id": request_id}
+    if error is not None:
+        payload["error"] = error
+    else:
+        payload["result"] = result
+    return payload
+
+
+def handle(message, client=None, profile="codex"):
+    client = client or InboxClient(profile=profile)
+    request_id = message.get("id")
+    method = message.get("method")
+    if method == "initialize":
+        requested = message.get("params", {}).get("protocolVersion", "2025-06-18")
+        return response(
+            request_id,
+            {
+                "protocolVersion": requested,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {
+                    "name": "suggestionbox-mcp",
+                    "version": __version__,
+                },
+                "instructions": (
+                    "Use add_to_inbox only when the user explicitly asks to save an unfinished "
+                    "thought. It is private and never publishes."
+                ),
+            },
+        )
+    if method == "notifications/initialized":
+        return None
+    if method == "ping":
+        return response(request_id, {})
+    if method == "shutdown":
+        return response(request_id, {})
+    if method == "tools/list":
+        return response(request_id, {"tools": [TOOL]})
+    if method == "tools/call":
+        params = message.get("params", {})
+        if params.get("name") != "add_to_inbox":
+            return response(
+                request_id, error={"code": -32602, "message": "Unknown tool."}
+            )
+        arguments = params.get("arguments", {})
+        allowed_arguments = {"title", "body", "source_url", "origin_hint"}
+        if (
+            not isinstance(arguments, dict)
+            or set(arguments) - allowed_arguments
+            or not isinstance(arguments.get("title", ""), str)
+            or not isinstance(arguments.get("body", ""), str)
+            or not (
+                arguments.get("title", "").strip() or arguments.get("body", "").strip()
+            )
+            or not isinstance(arguments.get("source_url", ""), str)
+            or arguments.get("origin_hint", "") not in {"", "owner", "received"}
+        ):
+            return response(
+                request_id,
+                error={"code": -32602, "message": "Invalid tool arguments."},
+            )
+        try:
+            result = client.add(
+                title=arguments.get("title", ""),
+                body=arguments.get("body", ""),
+                source_url=arguments.get("source_url", ""),
+                origin_hint=arguments.get("origin_hint", ""),
+            )
+        except InboxClientError as error:
+            return response(
+                request_id,
+                {
+                    "content": [{"type": "text", "text": str(error)}],
+                    "isError": True,
+                },
+            )
+        structured = {
+            "inbox_item_id": result.inbox_item_id,
+            "state": result.state,
+            "review_url": result.review_url,
+        }
+        return response(
+            request_id,
+            {
+                "content": [{"type": "text", "text": "Added to your Inbox"}],
+                "structuredContent": structured,
+                "isError": False,
+            },
+        )
+    return response(request_id, error={"code": -32601, "message": "Method not found."})
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="suggestionbox-mcp")
+    parser.add_argument("--profile", choices=("codex", "claude"), default="codex")
+    args = parser.parse_args(argv)
+    client = InboxClient(profile=args.profile)
+    for line in sys.stdin:
+        try:
+            message = json.loads(line)
+            output = handle(message, client=client)
+            if output is not None:
+                print(json.dumps(output, separators=(",", ":")), flush=True)
+        except Exception:
+            print(
+                json.dumps(
+                    response(
+                        None, error={"code": -32700, "message": "Invalid request."}
+                    )
+                ),
+                flush=True,
+            )
+
+
+if __name__ == "__main__":
+    main()

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: suggestionbox-connect
+Version: 2.0.0
+Summary: Connect your terminal and AI assistant to your private SuggestionBox.io Inbox.
+Author: KnowledgeTack LLC
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://suggestionbox.io/
+Project-URL: Changelog, https://pypi.org/project/suggestionbox-connect/#history
+Project-URL: Terms, https://suggestionbox.io/terms/
+Project-URL: Support, https://suggestionbox.io/terms/#contact
+Keywords: suggestionbox,suggestions,cli,mcp,ai,product-management
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keyring<26,>=25
+Dynamic: license-file
+
+# SuggestionBox Connect
+
+Connect your terminal and AI assistant to your private SuggestionBox.io Inbox.
+One installation provides the `sb` command-line tool and the
+`suggestionbox-mcp` AI-assistant connector.
+
+## Install
+
+Install SuggestionBox Connect in an isolated environment with
+[pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install suggestionbox-connect
+```
+
+SuggestionBox supports Python 3.10 through 3.14 on Linux, macOS, and Windows.
+
+## Connect
+
+1. Sign in to SuggestionBox.io and open **Inbox → Inbox settings**.
+2. In **Command line**, create a credential for this computer and copy it.
+3. Run:
+
+```bash
+sb connect
+```
+
+Paste the credential into the hidden prompt. The CLI verifies it before saving
+it in your operating system's credential store and names the exact
+SuggestionBox it belongs to. The credential can add private
+Inbox items only; it cannot read your Inbox or publish suggestions.
+
+Confirm the connection at any time:
+
+```bash
+sb status
+```
+
+## Add to Inbox
+
+Use a title, a body, or both:
+
+```bash
+sb add --title "Remember Inbox filters between visits"
+sb add --body "Show which CSV column failed validation."
+sb add --title "Scheduled exports" --body "Allow a weekly delivery schedule."
+```
+
+Pipe a longer body from another command:
+
+```bash
+printf '%s' "Add a dry-run option" | sb add --body -
+```
+
+Use `--received` when recording something that came from another person:
+
+```bash
+sb add --received --title "Customer requested a printable invoice"
+```
+
+Every successful command prints the private Inbox item ID and its owner-only
+review URL.
+
+## Disconnect, upgrade, or uninstall
+
+```bash
+sb disconnect
+pipx upgrade suggestionbox-connect
+pipx uninstall suggestionbox-connect
+```
+
+Deleting the credential in Inbox settings immediately prevents later use from
+this computer. `sb disconnect` removes the local copy but does not delete the
+server-side credential.
+
+## Automation
+
+For ephemeral automation, supply `SUGGESTIONBOX_INBOX_TOKEN` through the
+automation platform's secret store. Do not put an Inbox credential in a command,
+URL, project file, prompt, or log.
+
+## AI-assistant tool
+
+The same distribution includes the add-only `suggestionbox-mcp` STDIO
+server. Create and copy a separate **AI assistant** credential for each
+assistant, then run the matching command:
+
+```bash
+sb connect codex
+sb connect claude
+```
+
+Each command verifies and securely saves the credential, installs the MCP
+server in that assistant, and handles operating-system details internally.
+Start a new assistant session afterward. The MCP server cannot read or publish
+suggestions and acts only when the assistant invokes its single `add_to_inbox`
+tool.
+
+Check or remove either connection with:
+
+```bash
+sb status codex
+sb disconnect codex
+sb status claude
+sb disconnect claude
+```
+
+Use of this client and SuggestionBox.io is governed by the
+[SuggestionBox.io Terms of Service](https://suggestionbox.io/terms/). For help,
+contact [support@suggestionbox.io](mailto:support@suggestionbox.io).

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+suggestionbox_connect/__init__.py
+suggestionbox_connect/cli.py
+suggestionbox_connect/client.py
+suggestionbox_connect/integrations.py
+suggestionbox_connect/mcp_server.py
+suggestionbox_connect.egg-info/PKG-INFO
+suggestionbox_connect.egg-info/SOURCES.txt
+suggestionbox_connect.egg-info/dependency_links.txt
+suggestionbox_connect.egg-info/entry_points.txt
+suggestionbox_connect.egg-info/requires.txt
+suggestionbox_connect.egg-info/top_level.txt

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sb = suggestionbox_connect.cli:main
+suggestionbox-mcp = suggestionbox_connect.mcp_server:main

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/requires.txt

@@ -0,0 +1 @@
+keyring<26,>=25

suggestionbox_connect-2.0.0/suggestionbox_connect.egg-info/top_level.txt

@@ -0,0 +1 @@
+suggestionbox_connect