jabb-cli 0.1.0__tar.gz → 0.2.0__tar.gz

jabb_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JABB (JAB-Bers)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jabb_cli-0.2.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: jabb-cli
+Version: 0.2.0
+Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
+Author: JABB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JAB-Bers/jabb-cli
+Project-URL: Repository, https://github.com/JAB-Bers/jabb-cli
+Project-URL: Issues, https://github.com/JAB-Bers/jabb-cli/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: mcp<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# jabb
+
+CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```bash
+export JABB_API_KEY=jabb_test_...
+jabb locations list
+```
+
+Time to first result: under 5 minutes from a minted key.
+
+## Usage
+
+```
+jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
+```
+
+Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.
+
+- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
+- `--detailed` — request more fields per row (costs more tokens/bandwidth).
+- `--cursor` — pass the previous response's `next_cursor` to page forward.
+- `--limit` — rows per page, 1-100, default 20.
+
+Examples:
+
+```bash
+jabb scores list --detailed
+jabb reviews list --limit 5
+jabb pnif list --json
+jabb locations list --cursor eyJwIjo... --limit 50
+```
+
+## Auth
+
+Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.
+
+For local development against a jabb-server instance running on your machine:
+
+```bash
+export JABB_API_BASE_URL=http://127.0.0.1:5500
+```
+
+Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic API error |
+| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
+| 3 | Rate limited (message includes retry-after seconds) |
+
+## MCP server (agent integration)
+
+`jabb mcp` starts a **stdio MCP server** that exposes the same 5 resources as agent tools, so any MCP host (Claude Code, Claude Desktop, Cursor…) can query your JABB data with nothing but an API key.
+
+### Tools exposed
+
+| Tool | When to call |
+|------|-------------|
+| `jabb_list_locations` | User asks about branches/stores or needs location IDs |
+| `jabb_get_cx_scores` | User wants quantitative CX quality metrics |
+| `jabb_list_quick_jabbs` | User wants individual evaluation content / verbatim feedback |
+| `jabb_get_pnif` | User asks for Price/Need/Impact/Frequency breakdown |
+| `jabb_get_sentiment` | User asks for sentiment labels or topic-level trends |
+
+All tools accept `cursor`, `limit`, `response_format` (`"concise"` | `"detailed"`). `jabb_get_pnif` and `jabb_get_sentiment` also accept `language` (ISO 639-1: `en`/`fr`/`ar`).
+
+Responses are capped at ~25 KB. When truncated, the payload includes `"truncated": true` and preserves the original `next_cursor` so the agent can page forward.
+
+API errors are returned as tool errors carrying the API's `code` + `hint` verbatim. 429 errors also include `Retry-After` seconds.
+
+### Connect from Claude Code
+
+```bash
+# One-time setup (project scope):
+claude mcp add jabb -- jabb mcp
+```
+
+Or add a project-scope `.mcp.json` at your repo root:
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "${JABB_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "jabb_live_..."
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JABB_API_KEY` | Yes | — | API key minted by your JABB admin |
+| `JABB_API_BASE_URL` | No | `https://api.jabb.cx` | Override for local dev |
+
+## For Claude Code users
+
+See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data. The MCP server (`jabb mcp`) is an alternative path that works with any MCP-capable host without the skill.
+
+## Scope
+
+Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.

jabb_cli-0.2.0/README.md

@@ -0,0 +1,135 @@
+# jabb
+
+CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```bash
+export JABB_API_KEY=jabb_test_...
+jabb locations list
+```
+
+Time to first result: under 5 minutes from a minted key.
+
+## Usage
+
+```
+jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
+```
+
+Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.
+
+- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
+- `--detailed` — request more fields per row (costs more tokens/bandwidth).
+- `--cursor` — pass the previous response's `next_cursor` to page forward.
+- `--limit` — rows per page, 1-100, default 20.
+
+Examples:
+
+```bash
+jabb scores list --detailed
+jabb reviews list --limit 5
+jabb pnif list --json
+jabb locations list --cursor eyJwIjo... --limit 50
+```
+
+## Auth
+
+Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.
+
+For local development against a jabb-server instance running on your machine:
+
+```bash
+export JABB_API_BASE_URL=http://127.0.0.1:5500
+```
+
+Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic API error |
+| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
+| 3 | Rate limited (message includes retry-after seconds) |
+
+## MCP server (agent integration)
+
+`jabb mcp` starts a **stdio MCP server** that exposes the same 5 resources as agent tools, so any MCP host (Claude Code, Claude Desktop, Cursor…) can query your JABB data with nothing but an API key.
+
+### Tools exposed
+
+| Tool | When to call |
+|------|-------------|
+| `jabb_list_locations` | User asks about branches/stores or needs location IDs |
+| `jabb_get_cx_scores` | User wants quantitative CX quality metrics |
+| `jabb_list_quick_jabbs` | User wants individual evaluation content / verbatim feedback |
+| `jabb_get_pnif` | User asks for Price/Need/Impact/Frequency breakdown |
+| `jabb_get_sentiment` | User asks for sentiment labels or topic-level trends |
+
+All tools accept `cursor`, `limit`, `response_format` (`"concise"` | `"detailed"`). `jabb_get_pnif` and `jabb_get_sentiment` also accept `language` (ISO 639-1: `en`/`fr`/`ar`).
+
+Responses are capped at ~25 KB. When truncated, the payload includes `"truncated": true` and preserves the original `next_cursor` so the agent can page forward.
+
+API errors are returned as tool errors carrying the API's `code` + `hint` verbatim. 429 errors also include `Retry-After` seconds.
+
+### Connect from Claude Code
+
+```bash
+# One-time setup (project scope):
+claude mcp add jabb -- jabb mcp
+```
+
+Or add a project-scope `.mcp.json` at your repo root:
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "${JABB_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "jabb_live_..."
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JABB_API_KEY` | Yes | — | API key minted by your JABB admin |
+| `JABB_API_BASE_URL` | No | `https://api.jabb.cx` | Override for local dev |
+
+## For Claude Code users
+
+See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data. The MCP server (`jabb mcp`) is an alternative path that works with any MCP-capable host without the skill.
+
+## Scope
+
+Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.

{jabb_cli-0.1.0 → jabb_cli-0.2.0}/jabb_cli/cli.py

@@ -75,3 +75,9 @@ def _make_group(name, path, help_text):
 
 for _name, (_path, _help) in RESOURCES.items():
     main.add_command(_make_group(_name, _path, _help))
+
+
+@main.command(name="mcp", help="Start a stdio MCP server exposing JABB Public API v1 as agent tools.")
+def mcp_serve():
+    from jabb_cli.mcp_server import serve
+    serve()

jabb_cli-0.2.0/jabb_cli/mcp_server.py

@@ -0,0 +1,156 @@
+"""stdio MCP server — exposes JABB Public API v1 as agent tools via FastMCP."""
+import json
+import sys
+from typing import Literal, Optional
+
+from mcp.server.fastmcp import FastMCP
+from jabb_cli.client import ApiClient, ApiError, AuthError, RateLimitError
+from jabb_cli.cli import RESOURCES
+
+_MAX_RESPONSE_BYTES = 25_000  # ~25K tokens guard
+
+mcp = FastMCP("jabb")
+
+
+def _client() -> ApiClient:
+    """Instantiate ApiClient; raises AuthError on missing key (propagated as tool error)."""
+    return ApiClient()
+
+
+def _call(path: str, params: dict) -> dict:
+    return _client().get(path, params=params)
+
+
+def _truncate(payload: dict) -> dict:
+    """Cap payload at _MAX_RESPONSE_BYTES. Sets truncated+next_cursor when trimmed."""
+    raw = json.dumps(payload)
+    if len(raw.encode()) <= _MAX_RESPONSE_BYTES:
+        return payload
+    data = payload.get("data", [])
+    if isinstance(data, list):
+        # Binary-search for the largest prefix that fits
+        lo, hi = 0, len(data)
+        while lo < hi:
+            mid = (lo + hi + 1) // 2
+            candidate = dict(payload, data=data[:mid], truncated=True)
+            if len(json.dumps(candidate).encode()) <= _MAX_RESPONSE_BYTES:
+                lo = mid
+            else:
+                hi = mid - 1
+        return dict(payload, data=data[:lo], truncated=True)
+    # Non-list data: return as-is with truncation flag (can't safely trim objects)
+    return dict(payload, truncated=True)
+
+
+def _tool_error(e: ApiError) -> str:
+    parts = [f"[{e.code}] {e.message}"]
+    if e.hint:
+        parts.append(f"Hint: {e.hint}")
+    if isinstance(e, RateLimitError):
+        parts.append(f"Retry-After: {e.retry_after}s")
+    return " | ".join(parts)
+
+
+def _list_params(
+    cursor: Optional[str],
+    limit: int,
+    response_format: Literal["concise", "detailed"],
+    extra: Optional[dict] = None,
+) -> dict:
+    p: dict = {"limit": limit, "response_format": response_format}
+    if cursor:
+        p["cursor"] = cursor
+    if extra:
+        p.update(extra)
+    return p
+
+
+@mcp.tool()
+def jabb_list_locations(
+    cursor: Optional[str] = None,
+    limit: int = 20,
+    response_format: Literal["concise", "detailed"] = "concise",
+) -> dict:
+    """Use when the user asks about physical branches/stores of the business, needs a
+    store/venue list, or requires location IDs to cross-reference other resources.
+    Returns paginated list of business locations. Use concise unless field depth is needed."""
+    try:
+        result = _call(RESOURCES["locations"][0], _list_params(cursor, limit, response_format))
+        return _truncate(result)
+    except ApiError as e:
+        raise ValueError(_tool_error(e)) from e
+
+
+@mcp.tool()
+def jabb_get_cx_scores(
+    cursor: Optional[str] = None,
+    limit: int = 20,
+    response_format: Literal["concise", "detailed"] = "concise",
+) -> dict:
+    """Use when the user asks for quantitative CX quality metrics, scores, or ratings per
+    entity. Do NOT use for raw review text — use jabb_list_quick_jabbs instead."""
+    try:
+        result = _call(RESOURCES["scores"][0], _list_params(cursor, limit, response_format))
+        return _truncate(result)
+    except ApiError as e:
+        raise ValueError(_tool_error(e)) from e
+
+
+@mcp.tool()
+def jabb_list_quick_jabbs(
+    cursor: Optional[str] = None,
+    limit: int = 20,
+    response_format: Literal["concise", "detailed"] = "concise",
+) -> dict:
+    """Use when the user asks about individual customer evaluations, review content, or
+    specific ratings with verbatim feedback. Do NOT use for aggregate scores — use
+    jabb_get_cx_scores instead."""
+    try:
+        result = _call(RESOURCES["reviews"][0], _list_params(cursor, limit, response_format))
+        return _truncate(result)
+    except ApiError as e:
+        raise ValueError(_tool_error(e)) from e
+
+
+@mcp.tool()
+def jabb_get_pnif(
+    language: str = "en",
+    cursor: Optional[str] = None,
+    limit: int = 20,
+    response_format: Literal["concise", "detailed"] = "concise",
+) -> dict:
+    """Use when the user asks for the Price/Need/Impact/Frequency analysis breakdown.
+    Do NOT use for raw scores or review text. language: ISO 639-1 code (en/fr/ar)."""
+    try:
+        extra = {"language": language}
+        result = _call(RESOURCES["pnif"][0], _list_params(cursor, limit, response_format, extra))
+        return _truncate(result)
+    except ApiError as e:
+        raise ValueError(_tool_error(e)) from e
+
+
+@mcp.tool()
+def jabb_get_sentiment(
+    language: str = "en",
+    cursor: Optional[str] = None,
+    limit: int = 20,
+    response_format: Literal["concise", "detailed"] = "concise",
+) -> dict:
+    """Use when the user asks for sentiment labels, trends, or topic-level sentiment mapping.
+    Do NOT use for raw scores or PNIF breakdown. language: ISO 639-1 code (en/fr/ar)."""
+    try:
+        extra = {"language": language}
+        result = _call(RESOURCES["sentiment"][0], _list_params(cursor, limit, response_format, extra))
+        return _truncate(result)
+    except ApiError as e:
+        raise ValueError(_tool_error(e)) from e
+
+
+def serve() -> None:
+    """Entry point: validate key then run stdio MCP server."""
+    try:
+        ApiClient()  # fail-fast: raises AuthError if JABB_API_KEY missing
+    except AuthError as e:
+        print(f"[jabb-mcp] {e.message} {e.hint}", file=sys.stderr)
+        sys.exit(2)
+    mcp.run(transport="stdio")

jabb_cli-0.2.0/jabb_cli.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: jabb-cli
+Version: 0.2.0
+Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
+Author: JABB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JAB-Bers/jabb-cli
+Project-URL: Repository, https://github.com/JAB-Bers/jabb-cli
+Project-URL: Issues, https://github.com/JAB-Bers/jabb-cli/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: mcp<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# jabb
+
+CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```bash
+export JABB_API_KEY=jabb_test_...
+jabb locations list
+```
+
+Time to first result: under 5 minutes from a minted key.
+
+## Usage
+
+```
+jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
+```
+
+Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.
+
+- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
+- `--detailed` — request more fields per row (costs more tokens/bandwidth).
+- `--cursor` — pass the previous response's `next_cursor` to page forward.
+- `--limit` — rows per page, 1-100, default 20.
+
+Examples:
+
+```bash
+jabb scores list --detailed
+jabb reviews list --limit 5
+jabb pnif list --json
+jabb locations list --cursor eyJwIjo... --limit 50
+```
+
+## Auth
+
+Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.
+
+For local development against a jabb-server instance running on your machine:
+
+```bash
+export JABB_API_BASE_URL=http://127.0.0.1:5500
+```
+
+Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic API error |
+| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
+| 3 | Rate limited (message includes retry-after seconds) |
+
+## MCP server (agent integration)
+
+`jabb mcp` starts a **stdio MCP server** that exposes the same 5 resources as agent tools, so any MCP host (Claude Code, Claude Desktop, Cursor…) can query your JABB data with nothing but an API key.
+
+### Tools exposed
+
+| Tool | When to call |
+|------|-------------|
+| `jabb_list_locations` | User asks about branches/stores or needs location IDs |
+| `jabb_get_cx_scores` | User wants quantitative CX quality metrics |
+| `jabb_list_quick_jabbs` | User wants individual evaluation content / verbatim feedback |
+| `jabb_get_pnif` | User asks for Price/Need/Impact/Frequency breakdown |
+| `jabb_get_sentiment` | User asks for sentiment labels or topic-level trends |
+
+All tools accept `cursor`, `limit`, `response_format` (`"concise"` | `"detailed"`). `jabb_get_pnif` and `jabb_get_sentiment` also accept `language` (ISO 639-1: `en`/`fr`/`ar`).
+
+Responses are capped at ~25 KB. When truncated, the payload includes `"truncated": true` and preserves the original `next_cursor` so the agent can page forward.
+
+API errors are returned as tool errors carrying the API's `code` + `hint` verbatim. 429 errors also include `Retry-After` seconds.
+
+### Connect from Claude Code
+
+```bash
+# One-time setup (project scope):
+claude mcp add jabb -- jabb mcp
+```
+
+Or add a project-scope `.mcp.json` at your repo root:
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "${JABB_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "jabb": {
+      "command": "jabb",
+      "args": ["mcp"],
+      "env": {
+        "JABB_API_KEY": "jabb_live_..."
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `JABB_API_KEY` | Yes | — | API key minted by your JABB admin |
+| `JABB_API_BASE_URL` | No | `https://api.jabb.cx` | Override for local dev |
+
+## For Claude Code users
+
+See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data. The MCP server (`jabb mcp`) is an alternative path that works with any MCP-capable host without the skill.
+
+## Scope
+
+Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.

{jabb_cli-0.1.0 → jabb_cli-0.2.0}/jabb_cli.egg-info/SOURCES.txt

@@ -1,8 +1,10 @@
+LICENSE
 README.md
 pyproject.toml
 jabb_cli/__init__.py
 jabb_cli/cli.py
 jabb_cli/client.py
+jabb_cli/mcp_server.py
 jabb_cli/output.py
 jabb_cli.egg-info/PKG-INFO
 jabb_cli.egg-info/SOURCES.txt
@@ -13,4 +15,6 @@ jabb_cli.egg-info/top_level.txt
 tests/test_cli_errors.py
 tests/test_cli_resources.py
 tests/test_client.py
+tests/test_mcp_entry.py
+tests/test_mcp_tools.py
 tests/test_output.py

{jabb_cli-0.1.0 → jabb_cli-0.2.0}/jabb_cli.egg-info/requires.txt

@@ -1,5 +1,6 @@
 click>=8.1
 requests>=2.31
+mcp<2,>=1.0
 
 [dev]
 pytest>=8.0

jabb_cli-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "jabb-cli"
+version = "0.2.0"
+description = "CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment."
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "JABB" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["click>=8.1", "requests>=2.31", "mcp>=1.0,<2"]
+
+[project.urls]
+Homepage = "https://github.com/JAB-Bers/jabb-cli"
+Repository = "https://github.com/JAB-Bers/jabb-cli"
+Issues = "https://github.com/JAB-Bers/jabb-cli/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+jabb = "jabb_cli.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["jabb_cli*"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

jabb_cli-0.2.0/tests/test_mcp_entry.py

@@ -0,0 +1,28 @@
+"""Task 1 tests: mcp subcommand wired + missing-key fail-fast."""
+import pytest
+from unittest.mock import patch
+from click.testing import CliRunner
+from jabb_cli.cli import main
+
+
+def test_mcp_subcommand_registered():
+    """jabb mcp --help must exit 0 (subcommand is registered)."""
+    result = CliRunner().invoke(main, ["mcp", "--help"])
+    assert result.exit_code == 0
+    assert "stdio" in result.output.lower() or "mcp" in result.output.lower()
+
+
+def test_mcp_missing_key_exits_nonzero(monkeypatch):
+    """jabb mcp without JABB_API_KEY must exit 2 and print a message to stderr."""
+    monkeypatch.delenv("JABB_API_KEY", raising=False)
+    with patch("jabb_cli.mcp_server.mcp.run"):  # prevent actual stdio server start
+        result = CliRunner().invoke(main, ["mcp"])
+    assert result.exit_code == 2
+
+
+def test_mcp_with_key_calls_serve(monkeypatch):
+    """jabb mcp with a valid key proceeds to mcp.run (no early exit)."""
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.mcp.run") as mock_run:
+        CliRunner().invoke(main, ["mcp"])
+    mock_run.assert_called_once_with(transport="stdio")

jabb_cli-0.2.0/tests/test_mcp_tools.py

@@ -0,0 +1,134 @@
+"""Task 2 tests: MCP tool path mapping, param forwarding, concise/detailed, error mapping, truncation."""
+import json
+import pytest
+from unittest.mock import patch, MagicMock
+from jabb_cli.mcp_server import (
+    jabb_list_locations,
+    jabb_get_cx_scores,
+    jabb_list_quick_jabbs,
+    jabb_get_pnif,
+    jabb_get_sentiment,
+    _truncate,
+    _MAX_RESPONSE_BYTES,
+)
+from jabb_cli.client import ApiError, AuthError, RateLimitError
+from jabb_cli.cli import RESOURCES
+
+
+# ── path mapping ──────────────────────────────────────────────────────────────
+
+TOOL_PATH_CASES = [
+    (jabb_list_locations, "locations"),
+    (jabb_get_cx_scores, "scores"),
+    (jabb_list_quick_jabbs, "reviews"),
+    (jabb_get_pnif, "pnif"),
+    (jabb_get_sentiment, "sentiment"),
+]
+
+
+@pytest.mark.parametrize("tool_fn,resource_key", TOOL_PATH_CASES)
+def test_tool_calls_correct_path(monkeypatch, tool_fn, resource_key):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    expected_path = RESOURCES[resource_key][0]
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value={"data": [], "next_cursor": None}) as m:
+        tool_fn()
+    assert m.call_args.args[0] == expected_path
+
+
+# ── param forwarding ──────────────────────────────────────────────────────────
+
+def test_cursor_and_limit_forwarded(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value={"data": [], "next_cursor": None}) as m:
+        jabb_list_locations(cursor="tok_abc", limit=5)
+    params = m.call_args.kwargs["params"]
+    assert params["cursor"] == "tok_abc"
+    assert params["limit"] == 5
+
+
+def test_language_forwarded_pnif(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value={"data": {}, "next_cursor": None}) as m:
+        jabb_get_pnif(language="ar")
+    assert m.call_args.kwargs["params"]["language"] == "ar"
+
+
+def test_language_forwarded_sentiment(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value={"data": {}, "next_cursor": None}) as m:
+        jabb_get_sentiment(language="fr")
+    assert m.call_args.kwargs["params"]["language"] == "fr"
+
+
+# ── concise vs detailed ───────────────────────────────────────────────────────
+
+@pytest.mark.parametrize("fmt", ["concise", "detailed"])
+def test_response_format_forwarded(monkeypatch, fmt):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value={"data": [], "next_cursor": None}) as m:
+        jabb_list_locations(response_format=fmt)
+    assert m.call_args.kwargs["params"]["response_format"] == fmt
+
+
+# ── error mapping ─────────────────────────────────────────────────────────────
+
+def test_api_error_raises_value_error_with_hint(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", side_effect=ApiError("not_found", "Resource not found", "Check the entity ID.")):
+        with pytest.raises(ValueError) as exc:
+            jabb_list_locations()
+    assert "not_found" in str(exc.value)
+    assert "Check the entity ID." in str(exc.value)
+
+
+def test_rate_limit_error_includes_retry_after(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", side_effect=RateLimitError("rate_limited", "Too many requests", "Slow down.", 42)):
+        with pytest.raises(ValueError) as exc:
+            jabb_list_locations()
+    assert "42" in str(exc.value)
+    assert "Retry-After" in str(exc.value)
+
+
+def test_auth_error_propagated(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    with patch("jabb_cli.mcp_server.ApiClient.get", side_effect=AuthError("forbidden", "Invalid key.", "Regenerate key in JABB admin.")):
+        with pytest.raises(ValueError) as exc:
+            jabb_list_locations()
+    assert "forbidden" in str(exc.value)
+
+
+# ── 25K truncation ────────────────────────────────────────────────────────────
+
+def test_truncate_small_payload_unchanged():
+    payload = {"data": [{"id": "1"}], "next_cursor": None}
+    assert _truncate(payload) == payload
+
+
+def test_truncate_large_list_sets_truncated_flag():
+    big_item = {"id": "x", "description": "a" * 500}
+    items = [big_item] * 200  # well over 25K
+    payload = {"data": items, "next_cursor": "tok_next"}
+    result = _truncate(payload)
+    assert result["truncated"] is True
+    assert len(result["data"]) < 200
+    assert len(json.dumps(result).encode()) <= _MAX_RESPONSE_BYTES
+
+
+def test_truncate_sets_truncated_and_next_cursor_survives(monkeypatch):
+    monkeypatch.setenv("JABB_API_KEY", "jabb_test_x")
+    big_item = {"id": "x", "description": "a" * 500}
+    items = [big_item] * 200
+    large_response = {"data": items, "next_cursor": "tok_next"}
+    with patch("jabb_cli.mcp_server.ApiClient.get", return_value=large_response):
+        result = jabb_list_locations()
+    assert result["truncated"] is True
+    assert result["next_cursor"] == "tok_next"
+
+
+def test_truncate_non_list_data_flag_only():
+    big_obj = {"key": "v" * 30_000}
+    payload = {"data": big_obj, "next_cursor": None}
+    result = _truncate(payload)
+    assert result["truncated"] is True
+    assert result["data"] == big_obj  # object preserved, can't trim safely

jabb_cli-0.1.0/PKG-INFO

@@ -1,9 +0,0 @@
-Metadata-Version: 2.4
-Name: jabb-cli
-Version: 0.1.0
-Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
-Requires-Python: >=3.11
-Requires-Dist: click>=8.1
-Requires-Dist: requests>=2.31
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"

jabb_cli-0.1.0/README.md

@@ -1,69 +0,0 @@
-# jabb
-
-CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment. A thin wrapper: every command is one HTTP GET, no business logic.
-
-## Install
-
-```bash
-pip install -e .
-```
-
-## Quickstart
-
-```bash
-export JABB_API_KEY=jabb_test_...
-jabb locations list
-```
-
-Time to first result: under 5 minutes from a minted key.
-
-## Usage
-
-```
-jabb [--json] [--detailed] <resource> list [--cursor <opaque>] [--limit <1-100>]
-```
-
-Resources: `locations`, `scores`, `reviews`, `pnif`, `sentiment`.
-
-- `--json` — print the raw API envelope (`{"data": [...], "next_cursor": ...}`) instead of a table. Use for scripting/agents.
-- `--detailed` — request more fields per row (costs more tokens/bandwidth).
-- `--cursor` — pass the previous response's `next_cursor` to page forward.
-- `--limit` — rows per page, 1-100, default 20.
-
-Examples:
-
-```bash
-jabb scores list --detailed
-jabb reviews list --limit 5
-jabb pnif list --json
-jabb locations list --cursor eyJwIjo... --limit 50
-```
-
-## Auth
-
-Set `JABB_API_KEY` to a key minted by your JABB admin (`jabb_live_...` in production, `jabb_test_...` for sandbox). No config file, no `--api-key` flag — env var only, so keys don't land in shell history.
-
-For local development against a jabb-server instance running on your machine:
-
-```bash
-export JABB_API_BASE_URL=http://127.0.0.1:5500
-```
-
-Default base URL is `https://api.jabb.cx`. There is no automatic failover to `api.jabb.pro` — that host runs a separate, diverged database, and silently reading from it would risk returning stale data.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Success |
-| 1 | Generic API error |
-| 2 | Auth/config error (missing/invalid/revoked key, wrong scope) |
-| 3 | Rate limited (message includes retry-after seconds) |
-
-## For Claude Code users
-
-See `skills/jabb-cx/SKILL.md` — copy it into your project's `.claude/skills/jabb-cx/` to let Claude Code drive this CLI directly when you ask about your CX data.
-
-## Scope
-
-Read-only. `list` operations against 5 resources, nothing else. No write/create/update commands exist.

jabb_cli-0.1.0/jabb_cli.egg-info/PKG-INFO

@@ -1,9 +0,0 @@
-Metadata-Version: 2.4
-Name: jabb-cli
-Version: 0.1.0
-Summary: CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment.
-Requires-Python: >=3.11
-Requires-Dist: click>=8.1
-Requires-Dist: requests>=2.31
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"

jabb_cli-0.1.0/pyproject.toml

@@ -1,19 +0,0 @@
-[project]
-name = "jabb-cli"
-version = "0.1.0"
-description = "CLI for JABB Public API v1 — locations, CX scores, reviews, PNIF, sentiment."
-requires-python = ">=3.11"
-dependencies = ["click>=8.1", "requests>=2.31"]
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0"]
-
-[project.scripts]
-jabb = "jabb_cli.cli:main"
-
-[tool.setuptools.packages.find]
-include = ["jabb_cli*"]
-
-[build-system]
-requires = ["setuptools>=68"]
-build-backend = "setuptools.build_meta"