bowmark-mcp 0.1.0__tar.gz

bowmark_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/

bowmark_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: bowmark-mcp
+Version: 0.1.0
+Summary: Bowmark MCP over stdio — a thin bridge to the hosted Bowmark MCP at https://api.bowmark.ai/mcp
+Project-URL: Homepage, https://bowmark.ai
+Project-URL: Documentation, https://bowmark.ai/install
+Author-email: Bowmark AI <christopher@bowmark.ai>
+License: MIT
+Keywords: ai-agents,bowmark,browser-automation,mcp,model-context-protocol
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.16
+Description-Content-Type: text/markdown
+
+# bowmark-mcp — Bowmark MCP over stdio
+
+Bowmark gives agents pre-computed navigation recipes for public websites (skip
+explore-and-discover). The canonical server is hosted, streamable HTTP, no auth
+required: `https://api.bowmark.ai/mcp`.
+
+This package is a **thin stdio bridge** to that hosted server, for MCP hosts
+whose client only speaks stdio (for example browser-use's `MCPClient`). Tool
+schemas, descriptions, and results pass through verbatim — the hosted server
+stays the single source of truth; nothing is reimplemented here.
+
+`mcp-name: ai.bowmark/bowmark`
+
+## Use
+
+```sh
+uvx bowmark-mcp        # or: pipx run bowmark-mcp / python -m bowmark_mcp
+```
+
+Example — browser-use:
+
+```python
+from browser_use.mcp.client import MCPClient
+
+bowmark = MCPClient(server_name="bowmark", command="uvx", args=["bowmark-mcp"])
+```
+
+Example — any MCP host config:
+
+```json
+{ "mcpServers": { "bowmark": { "command": "uvx", "args": ["bowmark-mcp"] } } }
+```
+
+If your host speaks streamable HTTP, skip this bridge and connect directly to
+`https://api.bowmark.ai/mcp`.
+
+## Environment
+
+| Var | Meaning |
+|---|---|
+| `BOWMARK_MCP_URL` | Target MCP URL. Default `https://api.bowmark.ai/mcp?s=p` (`?s=p` attributes the install to the PyPI bridge). Point at `http://localhost:3001/mcp` for a local Bowmark API. |
+| `BOWMARK_API_KEY` | Optional. Forwarded as `X-Bowmark-Key`; a free key (bowmark.ai dashboard) raises the anonymous per-IP daily synthesis cap to your plan budget. |
+
+## Design notes (repo-internal)
+
+- **One remote session per request, retried once.** `streamablehttp_client` is
+  an anyio-scoped context manager; holding one session across handler tasks
+  trips "exit cancel scope in a different task". The hosted MCP is stateless,
+  so a fresh session per request is semantically identical and costs one
+  initialize round-trip — noise next to an `ask` synthesis.
+- **Pass-through only.** No tool logic lives here; the agent-surfaces sync rule
+  in the root CLAUDE.md is unaffected because descriptions/schemas ride through
+  from `apps/api/src/routes/mcp.ts`.
+- **`?s=p` source code** is registered in `apps/api/src/mcp-sources.ts` +
+  `mcp-registry/sources.json` (PyPI stdio bridge channel).
+- **The `mcp-name: ai.bowmark/bowmark` line above is load-bearing**: the
+  official MCP Registry validates PyPI package ownership by finding that
+  marker in the package README. Don't remove it.
+- **Versioning is manual** (this is a thin bridge, not the api): bump
+  `pyproject.toml` when it changes. Not wired into release-please.
+
+## Tests
+
+```sh
+cd packages/mcp-stdio
+uv run --with pytest --with-editable . pytest -q
+```
+
+Network-free (the remote hop is monkeypatched). A live smoke against prod:
+
+```sh
+uv run --with-editable . python - <<'EOF'
+import asyncio, bowmark_mcp
+async def main():
+    tools = await bowmark_mcp.list_tools_impl()
+    print([t.name for t in tools])
+asyncio.run(main())
+EOF
+```
+
+## Publishing to PyPI (manual, Christopher)
+
+1. `cd packages/mcp-stdio && uv build`
+2. `uv publish` (needs the PyPI token; mirror it to 1Password when minted).
+3. After the package is live, add a `packages` entry (registryType `pypi`,
+   identifier `bowmark-mcp`, transport `stdio`) to `mcp-registry/server.json`
+   and republish — the registry validates ownership via the `mcp-name` marker
+   above, so it must come AFTER the PyPI publish. See `mcp-registry/README.md`.

bowmark_mcp-0.1.0/README.md

@@ -0,0 +1,88 @@
+# bowmark-mcp — Bowmark MCP over stdio
+
+Bowmark gives agents pre-computed navigation recipes for public websites (skip
+explore-and-discover). The canonical server is hosted, streamable HTTP, no auth
+required: `https://api.bowmark.ai/mcp`.
+
+This package is a **thin stdio bridge** to that hosted server, for MCP hosts
+whose client only speaks stdio (for example browser-use's `MCPClient`). Tool
+schemas, descriptions, and results pass through verbatim — the hosted server
+stays the single source of truth; nothing is reimplemented here.
+
+`mcp-name: ai.bowmark/bowmark`
+
+## Use
+
+```sh
+uvx bowmark-mcp        # or: pipx run bowmark-mcp / python -m bowmark_mcp
+```
+
+Example — browser-use:
+
+```python
+from browser_use.mcp.client import MCPClient
+
+bowmark = MCPClient(server_name="bowmark", command="uvx", args=["bowmark-mcp"])
+```
+
+Example — any MCP host config:
+
+```json
+{ "mcpServers": { "bowmark": { "command": "uvx", "args": ["bowmark-mcp"] } } }
+```
+
+If your host speaks streamable HTTP, skip this bridge and connect directly to
+`https://api.bowmark.ai/mcp`.
+
+## Environment
+
+| Var | Meaning |
+|---|---|
+| `BOWMARK_MCP_URL` | Target MCP URL. Default `https://api.bowmark.ai/mcp?s=p` (`?s=p` attributes the install to the PyPI bridge). Point at `http://localhost:3001/mcp` for a local Bowmark API. |
+| `BOWMARK_API_KEY` | Optional. Forwarded as `X-Bowmark-Key`; a free key (bowmark.ai dashboard) raises the anonymous per-IP daily synthesis cap to your plan budget. |
+
+## Design notes (repo-internal)
+
+- **One remote session per request, retried once.** `streamablehttp_client` is
+  an anyio-scoped context manager; holding one session across handler tasks
+  trips "exit cancel scope in a different task". The hosted MCP is stateless,
+  so a fresh session per request is semantically identical and costs one
+  initialize round-trip — noise next to an `ask` synthesis.
+- **Pass-through only.** No tool logic lives here; the agent-surfaces sync rule
+  in the root CLAUDE.md is unaffected because descriptions/schemas ride through
+  from `apps/api/src/routes/mcp.ts`.
+- **`?s=p` source code** is registered in `apps/api/src/mcp-sources.ts` +
+  `mcp-registry/sources.json` (PyPI stdio bridge channel).
+- **The `mcp-name: ai.bowmark/bowmark` line above is load-bearing**: the
+  official MCP Registry validates PyPI package ownership by finding that
+  marker in the package README. Don't remove it.
+- **Versioning is manual** (this is a thin bridge, not the api): bump
+  `pyproject.toml` when it changes. Not wired into release-please.
+
+## Tests
+
+```sh
+cd packages/mcp-stdio
+uv run --with pytest --with-editable . pytest -q
+```
+
+Network-free (the remote hop is monkeypatched). A live smoke against prod:
+
+```sh
+uv run --with-editable . python - <<'EOF'
+import asyncio, bowmark_mcp
+async def main():
+    tools = await bowmark_mcp.list_tools_impl()
+    print([t.name for t in tools])
+asyncio.run(main())
+EOF
+```
+
+## Publishing to PyPI (manual, Christopher)
+
+1. `cd packages/mcp-stdio && uv build`
+2. `uv publish` (needs the PyPI token; mirror it to 1Password when minted).
+3. After the package is live, add a `packages` entry (registryType `pypi`,
+   identifier `bowmark-mcp`, transport `stdio`) to `mcp-registry/server.json`
+   and republish — the registry validates ownership via the `mcp-name` marker
+   above, so it must come AFTER the PyPI publish. See `mcp-registry/README.md`.

bowmark_mcp-0.1.0/bowmark_mcp/__init__.py

@@ -0,0 +1,117 @@
+"""Bowmark MCP stdio bridge.
+
+A thin stdio MCP server that proxies every request to the hosted Bowmark MCP
+(streamable HTTP, https://api.bowmark.ai/mcp). Exists for MCP hosts whose
+client only speaks stdio (e.g. browser-use's ``MCPClient``): they run
+``uvx bowmark-mcp`` and get the exact hosted tools — schemas, descriptions,
+and envelopes pass through verbatim, so the hosted server stays the single
+source of truth.
+
+Env:
+  BOWMARK_MCP_URL   Target MCP URL. Default ``https://api.bowmark.ai/mcp?s=p``
+                    (the ``?s=p`` tags the install source as the PyPI bridge;
+                    point at ``http://localhost:3001/mcp`` for a local API).
+  BOWMARK_API_KEY   Optional Bowmark API key, forwarded as ``X-Bowmark-Key``.
+                    Omit for the anonymous tier.
+
+Design note — one remote session PER REQUEST, not one held for the process
+lifetime. The MCP Python SDK's ``streamablehttp_client`` is an anyio-scoped
+context manager: entering it in one handler task and closing it from another
+raises "attempted to exit cancel scope in a different task". Since the hosted
+Bowmark MCP is stateless and auth-free, a fresh session per request is
+semantically identical, and its cost (one initialize round-trip) is noise next
+to an ``ask`` synthesis. Each request still retries once on a transport
+failure before surfacing the error.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+import mcp.types as types
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.server.lowlevel import Server
+from mcp.server.stdio import stdio_server
+
+DEFAULT_URL = "https://api.bowmark.ai/mcp?s=p"
+
+T = TypeVar("T")
+
+
+def target_url() -> str:
+    return os.environ.get("BOWMARK_MCP_URL", "").strip() or DEFAULT_URL
+
+
+def auth_headers() -> dict[str, str] | None:
+    """Optional API key -> X-Bowmark-Key header (the hosted MCP also accepts
+    Authorization: Bearer; one header is enough)."""
+    key = os.environ.get("BOWMARK_API_KEY", "").strip()
+    return {"X-Bowmark-Key": key} if key else None
+
+
+async def _with_remote(fn: Callable[[ClientSession], Awaitable[T]]) -> T:
+    async with streamablehttp_client(target_url(), headers=auth_headers()) as (
+        read,
+        write,
+        _,
+    ):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            return await fn(session)
+
+
+async def call_remote(fn: Callable[[ClientSession], Awaitable[T]]) -> T:
+    """One retry on any failure: the remote is stateless, so a fresh session is
+    equivalent, and a transient network blip shouldn't fail the host's call."""
+    try:
+        return await _with_remote(fn)
+    except Exception as first:
+        print(f"bowmark-mcp: retrying after: {first}", file=sys.stderr)
+        return await _with_remote(fn)
+
+
+def error_text(result: types.CallToolResult, name: str) -> str:
+    """Flatten an isError result's text content for re-raising locally."""
+    texts = [c.text for c in result.content if isinstance(c, types.TextContent)]
+    return "; ".join(t for t in texts if t) or f"{name} failed upstream"
+
+
+async def list_tools_impl() -> list[types.Tool]:
+    res = await call_remote(lambda s: s.list_tools())
+    return res.tools
+
+
+async def call_tool_impl(name: str, arguments: dict[str, Any] | None) -> list[Any]:
+    result = await call_remote(lambda s: s.call_tool(name, arguments or {}))
+    # The lowlevel server wraps a raised exception as an isError result with
+    # the exception text, so upstream errors round-trip with their message.
+    if result.isError:
+        raise RuntimeError(error_text(result, name))
+    return list(result.content)
+
+
+def build_server() -> Server:
+    server = Server("bowmark")
+    server.list_tools()(list_tools_impl)
+    server.call_tool()(call_tool_impl)
+    return server
+
+
+async def _serve() -> None:
+    server = build_server()
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def main() -> None:
+    # stdout belongs to the protocol; anything human goes to stderr.
+    asyncio.run(_serve())
+
+
+if __name__ == "__main__":
+    main()

bowmark_mcp-0.1.0/bowmark_mcp/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+main()

bowmark_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "bowmark-mcp"
+version = "0.1.0"
+description = "Bowmark MCP over stdio — a thin bridge to the hosted Bowmark MCP at https://api.bowmark.ai/mcp"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Bowmark AI", email = "christopher@bowmark.ai" }]
+keywords = ["mcp", "model-context-protocol", "bowmark", "browser-automation", "ai-agents"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+# The official MCP Python SDK is the only dependency — it brings the
+# streamable-HTTP client (httpx) with it. <2 guards against a future major.
+dependencies = ["mcp>=1.16,<2"]
+
+[project.urls]
+Homepage = "https://bowmark.ai"
+Documentation = "https://bowmark.ai/install"
+
+[project.scripts]
+bowmark-mcp = "bowmark_mcp:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["bowmark_mcp"]

bowmark_mcp-0.1.0/tests/test_bridge.py

@@ -0,0 +1,96 @@
+# Network-free unit tests for the stdio bridge. The remote hop is
+# monkeypatched at the call_remote seam; nothing here opens a socket.
+#
+# Run: cd packages/mcp-stdio && uv run --with pytest --with-editable . pytest -q
+
+import asyncio
+
+import mcp.types as types
+import pytest
+
+import bowmark_mcp
+
+
+def test_target_url_default(monkeypatch):
+    monkeypatch.delenv("BOWMARK_MCP_URL", raising=False)
+    assert bowmark_mcp.target_url() == bowmark_mcp.DEFAULT_URL
+
+
+def test_target_url_override_and_blank(monkeypatch):
+    monkeypatch.setenv("BOWMARK_MCP_URL", "http://localhost:3001/mcp")
+    assert bowmark_mcp.target_url() == "http://localhost:3001/mcp"
+    # Blank/whitespace env must not blank the target.
+    monkeypatch.setenv("BOWMARK_MCP_URL", "   ")
+    assert bowmark_mcp.target_url() == bowmark_mcp.DEFAULT_URL
+
+
+def test_auth_headers(monkeypatch):
+    monkeypatch.delenv("BOWMARK_API_KEY", raising=False)
+    assert bowmark_mcp.auth_headers() is None
+    monkeypatch.setenv("BOWMARK_API_KEY", "bmk_test123")
+    assert bowmark_mcp.auth_headers() == {"X-Bowmark-Key": "bmk_test123"}
+
+
+def _tool_result(text: str, is_error: bool) -> types.CallToolResult:
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=text)], isError=is_error
+    )
+
+
+def test_call_tool_passes_content_through(monkeypatch):
+    async def fake_call_remote(fn):
+        return _tool_result('{"status":"ok"}', is_error=False)
+
+    monkeypatch.setattr(bowmark_mcp, "call_remote", fake_call_remote)
+    content = asyncio.run(bowmark_mcp.call_tool_impl("ask", {"site": "x.com", "task": "y"}))
+    assert len(content) == 1
+    assert content[0].text == '{"status":"ok"}'
+
+
+def test_call_tool_raises_on_upstream_error(monkeypatch):
+    async def fake_call_remote(fn):
+        return _tool_result("upstream exploded", is_error=True)
+
+    monkeypatch.setattr(bowmark_mcp, "call_remote", fake_call_remote)
+    with pytest.raises(RuntimeError, match="upstream exploded"):
+        asyncio.run(bowmark_mcp.call_tool_impl("ask", {}))
+
+
+def test_call_remote_retries_once_then_raises(monkeypatch):
+    calls = {"n": 0}
+
+    async def flaky(_fn):
+        calls["n"] += 1
+        raise ConnectionError("boom")
+
+    monkeypatch.setattr(bowmark_mcp, "_with_remote", flaky)
+    with pytest.raises(ConnectionError):
+        asyncio.run(bowmark_mcp.call_remote(lambda s: s))
+    assert calls["n"] == 2  # exactly one retry
+
+
+def test_call_remote_retry_succeeds(monkeypatch):
+    calls = {"n": 0}
+
+    async def flaky_then_ok(_fn):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise ConnectionError("boom")
+        return "ok"
+
+    monkeypatch.setattr(bowmark_mcp, "_with_remote", flaky_then_ok)
+    assert asyncio.run(bowmark_mcp.call_remote(lambda s: s)) == "ok"
+    assert calls["n"] == 2
+
+
+def test_error_text_flattens_and_falls_back():
+    r = _tool_result("", is_error=True)
+    assert bowmark_mcp.error_text(r, "ask") == "ask failed upstream"
+    r2 = types.CallToolResult(
+        content=[
+            types.TextContent(type="text", text="a"),
+            types.TextContent(type="text", text="b"),
+        ],
+        isError=True,
+    )
+    assert bowmark_mcp.error_text(r2, "ask") == "a; b"