ama-cli 0.1.0__py3-none-any.whl

ama_cli/verify.py

@@ -0,0 +1,259 @@
+"""Prove the registration actually works, by being a client.
+
+Writing a config file proves nothing. The user finds out whether onboarding
+worked when their agent tries a tool call and fails -- by which point they have
+left the terminal and have no idea which of the moving parts is broken. So we
+connect ourselves, with the key we just minted, against the URL we just wrote,
+and count the tools.
+
+This speaks MCP streamable-http (`transport="streamable-http"` in
+`src/ama/api/app.py`, mounted at `/mcp` with path `/sse` -- the path is a
+historical name, not the transport). Three JSON-RPC messages:
+
+    initialize              -> capabilities, and a session id in a header
+    notifications/initialized -> the handshake's required ack
+    tools/list              -> the thing we actually want
+
+Deliberately hand-rolled over urllib rather than pulling in the `mcp` SDK: the
+SDK is a heavy async dependency on the install path of a one-line onboarding
+command, and this needs exactly three messages of a protocol that is stable.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+# The revision we advertise. Servers negotiate down and answer with their own,
+# so a newer server is not a failure -- we never assert on the response version.
+PROTOCOL_VERSION = "2025-06-18"
+_TIMEOUT_SECONDS = 30
+_SESSION_HEADER = "mcp-session-id"
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    """A raw HTTP response, injectable so tests need no server."""
+
+    status: int
+    body: str
+    headers: Mapping[str, str] = None  # type: ignore[assignment]
+
+    def header(self, name: str) -> str | None:
+        """Case-insensitive header lookup; HTTP header case is not guaranteed."""
+        if not self.headers:
+            return None
+        lowered = {k.lower(): v for k, v in self.headers.items()}
+        return lowered.get(name.lower())
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    """The outcome of a live connection attempt."""
+
+    ok: bool
+    tool_count: int = 0
+    detail: str = ""
+    unauthorized: bool = False
+
+    @property
+    def summary(self) -> str:
+        """One line for the terminal."""
+        if self.ok:
+            return f"Connected — {self.tool_count} tools available"
+        return self.detail or "could not connect"
+
+
+class _Rpc:
+    """A JSON-RPC id sequence. Ids must be unique within a session."""
+
+    def __init__(self) -> None:
+        self._next = 0
+
+    def take(self) -> int:
+        self._next += 1
+        return self._next
+
+
+def _headers(api_key: str, session_id: str | None) -> dict[str, str]:
+    """Headers for every request in the handshake.
+
+    Accept must list *both* json and event-stream: the streamable-http spec lets
+    the server pick either per response, and FastMCP rejects a request that does
+    not accept both with a 406 -- which would look like a broken key.
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "Authorization": f"Bearer {api_key}",
+    }
+    if session_id:
+        headers[_SESSION_HEADER] = session_id
+    return headers
+
+
+def parse_rpc_body(body: str, content_type: str | None) -> dict | None:
+    """Pull a JSON-RPC envelope out of a response body.
+
+    The same logical response arrives as either bare JSON or an SSE frame
+    depending on how the server felt, so both are handled. Returns None when the
+    body holds no recognisable envelope.
+    """
+    if content_type and "text/event-stream" in content_type.lower():
+        for line in body.splitlines():
+            if not line.startswith("data:"):
+                continue
+            try:
+                payload = json.loads(line[len("data:") :].strip())
+            except json.JSONDecodeError:
+                continue
+            if isinstance(payload, dict) and ("result" in payload or "error" in payload):
+                return payload
+        return None
+    try:
+        payload = json.loads(body)
+    except json.JSONDecodeError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _rpc_error(payload: dict) -> str | None:
+    """The human-readable half of a JSON-RPC error, if the payload is one."""
+    err = payload.get("error")
+    if not isinstance(err, dict):
+        return None
+    message = err.get("message") or "unknown error"
+    return f"{message} (code {err.get('code')})" if "code" in err else str(message)
+
+
+def verify(mcp_url: str, api_key: str, *, transport=None) -> VerifyResult:
+    """Connect to `mcp_url` with `api_key` and list tools.
+
+    Never raises: a verification failure is information to show the user, not an
+    exception to handle. `transport` is injected so tests drive the whole
+    handshake without a network.
+    """
+    post = _post if transport is None else transport
+    rpc = _Rpc()
+
+    try:
+        init = post(
+            mcp_url,
+            json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": rpc.take(),
+                    "method": "initialize",
+                    "params": {
+                        "protocolVersion": PROTOCOL_VERSION,
+                        "capabilities": {},
+                        "clientInfo": {"name": "ama-cli", "version": "0.1.0"},
+                    },
+                }
+            ).encode(),
+            _headers(api_key, None),
+        )
+    except OSError as exc:
+        return VerifyResult(ok=False, detail=f"could not reach {mcp_url}: {exc}")
+
+    if init.status in (401, 403):
+        # The single most valuable thing this function catches: a key that was
+        # minted but does not authenticate here.
+        return VerifyResult(
+            ok=False,
+            unauthorized=True,
+            detail="the key was rejected by the MCP endpoint (401)",
+        )
+    if init.status >= 400:
+        return VerifyResult(ok=False, detail=f"initialize failed (HTTP {init.status})")
+
+    payload = parse_rpc_body(init.body, init.header("content-type"))
+    if payload is None:
+        return VerifyResult(ok=False, detail="initialize returned no JSON-RPC response")
+    if (err := _rpc_error(payload)) is not None:
+        return VerifyResult(ok=False, detail=f"initialize failed: {err}")
+
+    # Absent in stateless mode (dev), present in stateful (staging/prod). Echoing
+    # it when given is what keeps the next two calls in the same session.
+    session_id = init.header(_SESSION_HEADER)
+
+    try:
+        # Required by the spec before normal operation. It is a notification, so
+        # there is no response to read.
+        #
+        # FastMCP -- what Ama runs -- is measurably fine without it (verified by
+        # deleting this call and watching tests/install/test_verify_against_real_fastmcp.py
+        # still pass). We send it anyway: the spec asks for it, and `--host`
+        # means the far end is not guaranteed to be FastMCP.
+        post(
+            mcp_url,
+            json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}).encode(),
+            _headers(api_key, session_id),
+        )
+        listed = post(
+            mcp_url,
+            json.dumps(
+                {"jsonrpc": "2.0", "id": rpc.take(), "method": "tools/list", "params": {}}
+            ).encode(),
+            _headers(api_key, session_id),
+        )
+    except OSError as exc:
+        return VerifyResult(ok=False, detail=f"tools/list failed: {exc}")
+
+    if listed.status in (401, 403):
+        return VerifyResult(
+            ok=False, unauthorized=True, detail="the key was rejected by the MCP endpoint (401)"
+        )
+    if listed.status >= 400:
+        return VerifyResult(ok=False, detail=f"tools/list failed (HTTP {listed.status})")
+
+    payload = parse_rpc_body(listed.body, listed.header("content-type"))
+    if payload is None:
+        return VerifyResult(ok=False, detail="tools/list returned no JSON-RPC response")
+    if (err := _rpc_error(payload)) is not None:
+        return VerifyResult(ok=False, detail=f"tools/list failed: {err}")
+
+    result = payload.get("result")
+    tools = result.get("tools") if isinstance(result, dict) else None
+    if not isinstance(tools, list):
+        return VerifyResult(ok=False, detail="tools/list returned no tools")
+    if not tools:
+        # Authenticated, but the agent would have nothing to call. That is a
+        # broken setup even though nothing errored, so it must not read as
+        # success -- this is precisely the "wrote the file, declared victory"
+        # failure the step exists to catch.
+        return VerifyResult(
+            ok=False, tool_count=0, detail="connected, but the server exposed no tools"
+        )
+
+    return VerifyResult(ok=True, tool_count=len(tools), detail="connected")
+
+
+def _post(url: str, body: bytes, headers: dict[str, str]) -> HttpResponse:
+    """POST and capture the response, treating HTTP errors as data.
+
+    An HTTPError is a normal outcome here (401 is the case we most want to
+    report), so it is unwrapped into a response rather than propagated.
+    """
+    req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_SECONDS) as resp:
+            return HttpResponse(
+                status=resp.status,
+                body=resp.read().decode("utf-8", "replace"),
+                headers=dict(resp.headers),
+            )
+    except urllib.error.HTTPError as exc:
+        return HttpResponse(
+            status=exc.code,
+            body=exc.read().decode("utf-8", "replace"),
+            headers=dict(exc.headers or {}),
+        )
+    except urllib.error.URLError as exc:
+        raise OSError(str(exc.reason)) from exc
+
+
+__all__ = ["HttpResponse", "PROTOCOL_VERSION", "VerifyResult", "parse_rpc_body", "verify"]

ama_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: ama-cli
+Version: 0.1.0
+Summary: Connect your coding agent to Ama.
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# ama
+
+Connect your coding agent to [Ama](https://ama.dev).
+
+```bash
+curl -fsSL https://ama.dev/install | sh
+```
+
+That installs the CLI and runs `ama onboard`. Three questions and you are done:
+
+1. **Sign in** — in your browser.
+2. **Confirm** — which agents, and where.
+3. **Start now?** — opens your agent on a live notebook.
+
+Already have the CLI?
+
+```bash
+ama onboard
+```
+
+Re-running either line upgrades.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `ama onboard` | Sign in, detect agents, register MCP. Start here. |
+| `ama detect` | Show which coding agents were found, and why. |
+| `ama login` / `logout` / `whoami` | Manage credentials. |
+| `ama mcp add` / `list` / `remove` | Manage MCP registration directly. |
+
+## Supported agents
+
+Registered automatically:
+
+| Agent | |
+|---|---|
+| Claude Code | `claude mcp add -s user` |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex CLI | `codex mcp add` — also export `AMA_API_KEY`; Codex stores the variable name, not the token |
+| Gemini CLI | `gemini mcp add` |
+| VS Code (Copilot) | `code --add-mcp` |
+
+**Detected but not yet registered automatically:** Windsurf, Zed, Cline, Roo
+Code. `ama onboard` tells you rather than pretending, and prints what to paste.
+
+`ama detect` explains what it found and where, so you can check before anything
+is written. `ama onboard --dry-run` prints the exact diff for every file it
+would touch — and signs in to nothing, so no key is created.
+
+## Self-hosted
+
+Point at your own deployment; the CLI reads `/.well-known/mcp.json` for the
+endpoint and auth method rather than assuming anything.
+
+```bash
+ama onboard --host https://ama.internal.example.com
+```
+
+## Install without the script
+
+```bash
+uv tool install ama-cli    # binary is `ama`
+```
+
+## Notes
+
+This is the public client. It speaks HTTP to a hosted or self-hosted Ama and
+carries no server dependencies — `typer` and `rich`, nothing else.
+
+Your API key is stored in `~/.ama/credentials.json`, mode `0600`. The CLI never
+writes a literal token into a project-scoped config file, since those get
+committed; project scope uses environment-variable indirection instead.
+
+Licensed under Apache-2.0.

ama_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+ama_cli/__init__.py,sha256=tL4ADf3DjskgaheudFxWWAQdyN5yF_Y2isrV5O_6OD4,235
+ama_cli/auth.py,sha256=ICr3AZB6JzKfOAhwNHXaICIDTlA6g-_O0mRgpdT6tCg,9570
+ama_cli/cli.py,sha256=UXlzQn_Q_sJO0zmY9A0R-aheAPnlTD4gg1B5MEHYYAM,14924
+ama_cli/credentials.py,sha256=laF5xNmU_hS0Z-yKuo6--qgYs2S-000oBKI9KU_8dJI,3793
+ama_cli/discovery.py,sha256=36OtjaGphKYQIZSoPa-z1qAYqh2_0hBvKwvFZim2x4g,4095
+ama_cli/launch.py,sha256=PjDat9pjIKYffBVC8NJFF5_IuKhtjZ_5tS2OYSL2Jt0,2882
+ama_cli/onboard.py,sha256=tH0C0jXj71AsFmeMnjqFy15Uiu6k0g10xeKOBFth4oA,14931
+ama_cli/prompts.py,sha256=rx3R5Y06BI8cw7vFQD0eFvgv6t2IItPEyBH4yI40LoU,2355
+ama_cli/verify.py,sha256=1zBRr933xX5VA8uEg8lm9z8lHqiSFsGxIjZPbzHH5HY,9834
+ama_cli/agents/__init__.py,sha256=J_IA41xrdlGQbgkMvKLC6Nbb3hRGaqiaYwOjMBUv3wI,428
+ama_cli/agents/base.py,sha256=4A3QSgSbiHMJnBBdrDeTz3iM_BzN8vmXQJBeyYBnnk0,6401
+ama_cli/agents/mcp.py,sha256=8v25hgWJmExgrtXBw_DPd6iLG9hngao-hXSD0Hqo_1Y,9305
+ama_cli/agents/registry.py,sha256=06zWqhsnvg61hR_rtcVs-OAam7Ty7tKf0Vj8KB5BLMk,5950
+ama_cli/agents/adapters/__init__.py,sha256=fTxHUPtCyzNJ_m_L49szSjIVjaeboQgD52XYodxxkmk,1320
+ama_cli/agents/adapters/cli_backed.py,sha256=aCRYdovv2cul0xIfUSgoK_hFTeDnNw-_pVnMLADBTKk,9522
+ama_cli/agents/adapters/cursor.py,sha256=ys0KataR4uJlAP18WGXDlCTiwl8EigQoYn9SIPQSexE,2911
+ama_cli-0.1.0.dist-info/METADATA,sha256=9tIgxbELoge4I3gftOQaD6jNSeHEMIIwtA0uXH9eRSM,2640
+ama_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ama_cli-0.1.0.dist-info/entry_points.txt,sha256=IkXhsfKO4Xod18wjcgMDUPlQFUp6uMiwzxilAoLFvv0,40
+ama_cli-0.1.0.dist-info/RECORD,,

ama_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ama_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ama = ama_cli.cli:app