helve-mcp 2.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NG Tech LLC (Helve)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,90 @@
1
+ Metadata-Version: 2.4
2
+ Name: helve-mcp
3
+ Version: 2.0.2
4
+ Summary: Zero-dependency stdio-to-Streamable-HTTP MCP bridge and Python client for Helve (313 tools, 255 providers, spend_limit_usd caps, $0 failed-call escrow).
5
+ Author-email: Helve <daniel.foster@helve.dev>
6
+ License: MIT
7
+ Project-URL: Homepage, https://helve.dev
8
+ Project-URL: Documentation, https://docs.helve.dev/mcp-server
9
+ Project-URL: Repository, https://github.com/helve-dev/helve-mcp
10
+ Project-URL: Issues, https://github.com/helve-dev/helve-mcp/issues
11
+ Keywords: mcp,model-context-protocol,ai-agents,tools,gateway,helve,stdio
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # helve-mcp (Python)
27
+
28
+ Zero-dependency stdio-to-Streamable-HTTP MCP bridge and lightweight Python client for **[Helve](https://helve.dev)** — one pay-per-call API & MCP gateway for **313 live tools across 255 providers** (web search, crawl/extract, deep research, audio transcription, LLMs, SEC filings, GitHub, PDFs, finance, and utilities).
29
+
30
+ - **No monthly subscriptions:** $0/mo base with non-expiring $10 / $25 / $100 credit packs ($0.50 free signup credit).
31
+ - **Deterministic budget caps:** Per-key `spend_limit_usd` hard ceiling (`402 spend_limit_exceeded`).
32
+ - **$0 failed-call escrow:** Failed upstream calls automatically debit $0.
33
+ - **MCP + REST / Code Mode ready:** Works over Streamable HTTP MCP, stdio MCP via `uvx helve-mcp`, or direct Python/REST calls.
34
+
35
+ ## Quickstart (MCP stdio bridge)
36
+
37
+ Run directly with `uvx` (no global install):
38
+
39
+ ```bash
40
+ HELVE_API_KEY=sk_live_... uvx helve-mcp
41
+ ```
42
+
43
+ Or install with `pip`:
44
+
45
+ ```bash
46
+ pip install helve-mcp
47
+ HELVE_API_KEY=sk_live_... helve-mcp
48
+ ```
49
+
50
+ ### Claude Desktop / Cursor / Windsurf MCP config
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "helve": {
56
+ "command": "uvx",
57
+ "args": ["helve-mcp"],
58
+ "env": {
59
+ "HELVE_API_KEY": "sk_live_..."
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ > If your MCP client supports remote Streamable HTTP directly, you can also connect to `https://helve.dev/mcp` with `Authorization: Bearer sk_live_...` (or OAuth 2.1).
67
+
68
+ ## Quickstart (Python REST client)
69
+
70
+ ```python
71
+ from helve_mcp import HelveClient
72
+
73
+ client = HelveClient() # reads HELVE_API_KEY from environment
74
+
75
+ # 1. Discover tools (no API key required)
76
+ tools = client.search_tools("web extract", limit=5)
77
+
78
+ # 2. Invoke any tool by tool_id (requires HELVE_API_KEY)
79
+ result = client.call_tool(
80
+ "helve.web_extract",
81
+ {"urls": ["https://docs.helve.dev"], "content": {"max_chars": 4000}},
82
+ )
83
+ print(result)
84
+ ```
85
+
86
+ ## Links
87
+
88
+ - Website: https://helve.dev
89
+ - MCP Guide: https://docs.helve.dev/mcp-server
90
+ - Source & Agent Skills: https://github.com/helve-dev/helve-mcp
@@ -0,0 +1,65 @@
1
+ # helve-mcp (Python)
2
+
3
+ Zero-dependency stdio-to-Streamable-HTTP MCP bridge and lightweight Python client for **[Helve](https://helve.dev)** — one pay-per-call API & MCP gateway for **313 live tools across 255 providers** (web search, crawl/extract, deep research, audio transcription, LLMs, SEC filings, GitHub, PDFs, finance, and utilities).
4
+
5
+ - **No monthly subscriptions:** $0/mo base with non-expiring $10 / $25 / $100 credit packs ($0.50 free signup credit).
6
+ - **Deterministic budget caps:** Per-key `spend_limit_usd` hard ceiling (`402 spend_limit_exceeded`).
7
+ - **$0 failed-call escrow:** Failed upstream calls automatically debit $0.
8
+ - **MCP + REST / Code Mode ready:** Works over Streamable HTTP MCP, stdio MCP via `uvx helve-mcp`, or direct Python/REST calls.
9
+
10
+ ## Quickstart (MCP stdio bridge)
11
+
12
+ Run directly with `uvx` (no global install):
13
+
14
+ ```bash
15
+ HELVE_API_KEY=sk_live_... uvx helve-mcp
16
+ ```
17
+
18
+ Or install with `pip`:
19
+
20
+ ```bash
21
+ pip install helve-mcp
22
+ HELVE_API_KEY=sk_live_... helve-mcp
23
+ ```
24
+
25
+ ### Claude Desktop / Cursor / Windsurf MCP config
26
+
27
+ ```json
28
+ {
29
+ "mcpServers": {
30
+ "helve": {
31
+ "command": "uvx",
32
+ "args": ["helve-mcp"],
33
+ "env": {
34
+ "HELVE_API_KEY": "sk_live_..."
35
+ }
36
+ }
37
+ }
38
+ }
39
+ ```
40
+
41
+ > If your MCP client supports remote Streamable HTTP directly, you can also connect to `https://helve.dev/mcp` with `Authorization: Bearer sk_live_...` (or OAuth 2.1).
42
+
43
+ ## Quickstart (Python REST client)
44
+
45
+ ```python
46
+ from helve_mcp import HelveClient
47
+
48
+ client = HelveClient() # reads HELVE_API_KEY from environment
49
+
50
+ # 1. Discover tools (no API key required)
51
+ tools = client.search_tools("web extract", limit=5)
52
+
53
+ # 2. Invoke any tool by tool_id (requires HELVE_API_KEY)
54
+ result = client.call_tool(
55
+ "helve.web_extract",
56
+ {"urls": ["https://docs.helve.dev"], "content": {"max_chars": 4000}},
57
+ )
58
+ print(result)
59
+ ```
60
+
61
+ ## Links
62
+
63
+ - Website: https://helve.dev
64
+ - MCP Guide: https://docs.helve.dev/mcp-server
65
+ - Source & Agent Skills: https://github.com/helve-dev/helve-mcp
@@ -0,0 +1,39 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "helve-mcp"
7
+ version = "2.0.2"
8
+ description = "Zero-dependency stdio-to-Streamable-HTTP MCP bridge and Python client for Helve (313 tools, 255 providers, spend_limit_usd caps, $0 failed-call escrow)."
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.9"
12
+ authors = [
13
+ { name = "Helve", email = "daniel.foster@helve.dev" }
14
+ ]
15
+ keywords = ["mcp", "model-context-protocol", "ai-agents", "tools", "gateway", "helve", "stdio"]
16
+ classifiers = [
17
+ "Development Status :: 5 - Production/Stable",
18
+ "Intended Audience :: Developers",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Topic :: Software Development :: Libraries :: Python Modules",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.urls]
30
+ Homepage = "https://helve.dev"
31
+ Documentation = "https://docs.helve.dev/mcp-server"
32
+ Repository = "https://github.com/helve-dev/helve-mcp"
33
+ Issues = "https://github.com/helve-dev/helve-mcp/issues"
34
+
35
+ [project.scripts]
36
+ helve-mcp = "helve_mcp.cli:main"
37
+
38
+ [tool.setuptools.packages.find]
39
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,14 @@
1
+ """Helve MCP bridge and lightweight REST client."""
2
+
3
+ from .client import HelveClient
4
+ from .cli import DEFAULT_ENDPOINT, extract_json_from_sse, forward_jsonrpc, parse_args
5
+
6
+ __version__ = "2.0.2"
7
+ __all__ = [
8
+ "DEFAULT_ENDPOINT",
9
+ "HelveClient",
10
+ "__version__",
11
+ "extract_json_from_sse",
12
+ "forward_jsonrpc",
13
+ "parse_args",
14
+ ]
@@ -0,0 +1,173 @@
1
+ """Zero-dependency stdio-to-Streamable-HTTP MCP bridge for https://helve.dev/mcp."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import sys
8
+ import urllib.error
9
+ import urllib.request
10
+ from typing import Any, Dict, List, Optional, Tuple
11
+
12
+ DEFAULT_ENDPOINT = os.environ.get("HELVE_MCP_URL", "https://helve.dev/mcp")
13
+ VERSION = "2.0.2"
14
+
15
+
16
+ def parse_args(argv: List[str]) -> Dict[str, Any]:
17
+ endpoint = os.environ.get("HELVE_MCP_URL", "https://helve.dev/mcp")
18
+ api_key = os.environ.get("HELVE_API_KEY", "")
19
+ show_help = False
20
+ show_version = False
21
+
22
+ i = 0
23
+ while i < len(argv):
24
+ arg = argv[i]
25
+ if arg == "--url" and i + 1 < len(argv):
26
+ endpoint = argv[i + 1]
27
+ i += 2
28
+ elif arg == "--api-key" and i + 1 < len(argv):
29
+ api_key = argv[i + 1]
30
+ i += 2
31
+ elif arg in ("--help", "-h"):
32
+ show_help = True
33
+ i += 1
34
+ elif arg in ("--version", "-v"):
35
+ show_version = True
36
+ i += 1
37
+ else:
38
+ i += 1
39
+
40
+ return {
41
+ "help": show_help,
42
+ "version": show_version,
43
+ "endpoint": endpoint,
44
+ "api_key": api_key,
45
+ }
46
+
47
+
48
+ def extract_json_from_sse(text: str) -> List[Dict[str, Any]]:
49
+ messages: List[Dict[str, Any]] = []
50
+ for line in text.splitlines():
51
+ if line.startswith("data:"):
52
+ payload = line[5:].strip()
53
+ if payload and payload != "[DONE]":
54
+ messages.append(json.loads(payload))
55
+ return messages
56
+
57
+
58
+ def forward_jsonrpc(
59
+ message: Dict[str, Any],
60
+ *,
61
+ endpoint: str = DEFAULT_ENDPOINT,
62
+ api_key: str = "",
63
+ session_id: str = "",
64
+ timeout: float = 120.0,
65
+ ) -> Tuple[List[Dict[str, Any]], str]:
66
+ headers = {
67
+ "Content-Type": "application/json",
68
+ "Accept": "application/json, text/event-stream",
69
+ "User-Agent": f"helve-mcp-py/{VERSION}",
70
+ }
71
+ if api_key:
72
+ headers["Authorization"] = f"Bearer {api_key}"
73
+ if session_id:
74
+ headers["mcp-session-id"] = session_id
75
+
76
+ data = json.dumps(message).encode("utf-8")
77
+ req = urllib.request.Request(endpoint, data=data, headers=headers, method="POST")
78
+
79
+ try:
80
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
81
+ status = resp.status
82
+ next_session_id = resp.headers.get("mcp-session-id") or session_id
83
+ content_type = resp.headers.get("content-type", "")
84
+ text = resp.read().decode("utf-8", errors="replace")
85
+ except urllib.error.HTTPError as exc:
86
+ next_session_id = exc.headers.get("mcp-session-id") if exc.headers else session_id
87
+ body = exc.read().decode("utf-8", errors="replace")
88
+ if "id" in message:
89
+ return (
90
+ [
91
+ {
92
+ "jsonrpc": "2.0",
93
+ "id": message["id"],
94
+ "error": {
95
+ "code": -32000,
96
+ "message": f"HTTP {exc.code}: {body[:500]}",
97
+ },
98
+ }
99
+ ],
100
+ next_session_id or session_id,
101
+ )
102
+ return [], next_session_id or session_id
103
+
104
+ if not text or status in (202, 204):
105
+ return [], next_session_id
106
+
107
+ if "text/event-stream" in content_type or text.lstrip().startswith("event:") or text.lstrip().startswith("data:"):
108
+ return extract_json_from_sse(text), next_session_id
109
+
110
+ parsed = json.loads(text)
111
+ if isinstance(parsed, list):
112
+ return parsed, next_session_id
113
+ return [parsed], next_session_id
114
+
115
+
116
+ def main(argv: Optional[List[str]] = None) -> int:
117
+ opts = parse_args(sys.argv[1:] if argv is None else argv)
118
+ if opts["version"]:
119
+ sys.stdout.write(f"helve-mcp {VERSION}\n")
120
+ return 0
121
+ if opts["help"]:
122
+ sys.stdout.write(
123
+ "helve-mcp - stdio-to-Streamable-HTTP MCP bridge for Helve (https://helve.dev/mcp)\n\n"
124
+ "Usage:\n"
125
+ " HELVE_API_KEY=sk_live_... helve-mcp [--url https://helve.dev/mcp] [--api-key KEY]\n\n"
126
+ "Options:\n"
127
+ " --url URL Remote MCP endpoint (default: https://helve.dev/mcp)\n"
128
+ " --api-key KEY Helve API key (default: $HELVE_API_KEY)\n"
129
+ " -v, --version Show version and exit\n"
130
+ " -h, --help Show this help message and exit\n"
131
+ )
132
+ return 0
133
+
134
+ endpoint = opts["endpoint"]
135
+ api_key = opts["api_key"]
136
+ session_id = ""
137
+
138
+ for raw_line in sys.stdin:
139
+ line = raw_line.strip()
140
+ if not line:
141
+ continue
142
+ try:
143
+ message = json.loads(line)
144
+ except json.JSONDecodeError as exc:
145
+ sys.stderr.write(f"helve-mcp: invalid JSON on stdin: {exc}\n")
146
+ continue
147
+
148
+ try:
149
+ responses, session_id = forward_jsonrpc(
150
+ message,
151
+ endpoint=endpoint,
152
+ api_key=api_key,
153
+ session_id=session_id,
154
+ )
155
+ for response in responses:
156
+ sys.stdout.write(json.dumps(response) + "\n")
157
+ sys.stdout.flush()
158
+ except Exception as exc: # noqa: BLE001
159
+ if isinstance(message, dict) and "id" in message:
160
+ err = {
161
+ "jsonrpc": "2.0",
162
+ "id": message["id"],
163
+ "error": {"code": -32603, "message": str(exc)},
164
+ }
165
+ sys.stdout.write(json.dumps(err) + "\n")
166
+ sys.stdout.flush()
167
+ else:
168
+ sys.stderr.write(f"helve-mcp: bridge error: {exc}\n")
169
+ return 0
170
+
171
+
172
+ if __name__ == "__main__":
173
+ raise SystemExit(main())
@@ -0,0 +1,107 @@
1
+ """Zero-dependency REST client for Helve's v2 tool gateway (https://helve.dev)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import urllib.parse
8
+ import urllib.request
9
+ from typing import Any, Dict, Optional
10
+
11
+ DEFAULT_BASE_URL = "https://helve.dev"
12
+
13
+
14
+ class HelveClient:
15
+ """Minimal Python client for Helve's v2 tool discovery and invocation API."""
16
+
17
+ def __init__(
18
+ self,
19
+ api_key: Optional[str] = None,
20
+ *,
21
+ base_url: str = DEFAULT_BASE_URL,
22
+ timeout: float = 120.0,
23
+ ) -> None:
24
+ self.api_key = api_key if api_key is not None else os.environ.get("HELVE_API_KEY", "")
25
+ self.base_url = base_url.rstrip("/")
26
+ self.timeout = timeout
27
+
28
+ def _request(
29
+ self,
30
+ method: str,
31
+ path: str,
32
+ *,
33
+ params: Optional[Dict[str, Any]] = None,
34
+ payload: Optional[Dict[str, Any]] = None,
35
+ ) -> Dict[str, Any]:
36
+ url = f"{self.base_url}{path}"
37
+ if params:
38
+ filtered = {k: v for k, v in params.items() if v is not None}
39
+ if filtered:
40
+ url = f"{url}?{urllib.parse.urlencode(filtered)}"
41
+
42
+ headers = {
43
+ "Accept": "application/json",
44
+ "User-Agent": "helve-mcp-py/2.0.2",
45
+ }
46
+ if self.api_key:
47
+ headers["Authorization"] = f"Bearer {self.api_key}"
48
+
49
+ data = None
50
+ if payload is not None:
51
+ headers["Content-Type"] = "application/json"
52
+ data = json.dumps(payload).encode("utf-8")
53
+
54
+ req = urllib.request.Request(url, data=data, headers=headers, method=method)
55
+ with urllib.request.urlopen(req, timeout=self.timeout) as resp:
56
+ return json.loads(resp.read().decode("utf-8"))
57
+
58
+ def list_tools(self) -> Dict[str, Any]:
59
+ """List Helve's full live tool catalog via GET /v1/tools (no auth required)."""
60
+ return self._request("GET", "/v1/tools")
61
+
62
+ def search_tools(
63
+ self,
64
+ query: Optional[str] = None,
65
+ *,
66
+ category: Optional[str] = None,
67
+ limit: int = 10,
68
+ ) -> Dict[str, Any]:
69
+ """Search or browse Helve's live tool catalog via POST /v1/tools/search (no auth required)."""
70
+ payload: Dict[str, Any] = {"limit": limit}
71
+ if query is not None:
72
+ payload["query"] = query
73
+ if category is not None:
74
+ payload["category"] = category
75
+ return self._request("POST", "/v1/tools/search", payload=payload)
76
+
77
+ def call_tool(
78
+ self,
79
+ tool_id: str,
80
+ arguments: Optional[Dict[str, Any]] = None,
81
+ ) -> Dict[str, Any]:
82
+ """Invoke any Helve tool by tool_id via POST /v1/tools/call."""
83
+ return self._request(
84
+ "POST",
85
+ "/v1/tools/call",
86
+ payload={"tool_id": tool_id, "arguments": arguments or {}},
87
+ )
88
+
89
+ def get_job(self, job_id: str) -> Dict[str, Any]:
90
+ """Poll an async job (such as audio transcription) via GET /v1/jobs/{id}."""
91
+ return self._request("GET", f"/v1/jobs/{urllib.parse.quote(job_id, safe='')}")
92
+
93
+ def request_tool(
94
+ self,
95
+ tool_name: str,
96
+ use_case: str,
97
+ *,
98
+ category: Optional[str] = None,
99
+ provider_url: Optional[str] = None,
100
+ ) -> Dict[str, Any]:
101
+ """Log a missing third-party tool or API via POST /v1/tools/request."""
102
+ payload: Dict[str, Any] = {"tool_name": tool_name, "use_case": use_case}
103
+ if category:
104
+ payload["category"] = category
105
+ if provider_url:
106
+ payload["provider_url"] = provider_url
107
+ return self._request("POST", "/v1/tools/request", payload=payload)
@@ -0,0 +1,90 @@
1
+ Metadata-Version: 2.4
2
+ Name: helve-mcp
3
+ Version: 2.0.2
4
+ Summary: Zero-dependency stdio-to-Streamable-HTTP MCP bridge and Python client for Helve (313 tools, 255 providers, spend_limit_usd caps, $0 failed-call escrow).
5
+ Author-email: Helve <daniel.foster@helve.dev>
6
+ License: MIT
7
+ Project-URL: Homepage, https://helve.dev
8
+ Project-URL: Documentation, https://docs.helve.dev/mcp-server
9
+ Project-URL: Repository, https://github.com/helve-dev/helve-mcp
10
+ Project-URL: Issues, https://github.com/helve-dev/helve-mcp/issues
11
+ Keywords: mcp,model-context-protocol,ai-agents,tools,gateway,helve,stdio
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # helve-mcp (Python)
27
+
28
+ Zero-dependency stdio-to-Streamable-HTTP MCP bridge and lightweight Python client for **[Helve](https://helve.dev)** — one pay-per-call API & MCP gateway for **313 live tools across 255 providers** (web search, crawl/extract, deep research, audio transcription, LLMs, SEC filings, GitHub, PDFs, finance, and utilities).
29
+
30
+ - **No monthly subscriptions:** $0/mo base with non-expiring $10 / $25 / $100 credit packs ($0.50 free signup credit).
31
+ - **Deterministic budget caps:** Per-key `spend_limit_usd` hard ceiling (`402 spend_limit_exceeded`).
32
+ - **$0 failed-call escrow:** Failed upstream calls automatically debit $0.
33
+ - **MCP + REST / Code Mode ready:** Works over Streamable HTTP MCP, stdio MCP via `uvx helve-mcp`, or direct Python/REST calls.
34
+
35
+ ## Quickstart (MCP stdio bridge)
36
+
37
+ Run directly with `uvx` (no global install):
38
+
39
+ ```bash
40
+ HELVE_API_KEY=sk_live_... uvx helve-mcp
41
+ ```
42
+
43
+ Or install with `pip`:
44
+
45
+ ```bash
46
+ pip install helve-mcp
47
+ HELVE_API_KEY=sk_live_... helve-mcp
48
+ ```
49
+
50
+ ### Claude Desktop / Cursor / Windsurf MCP config
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "helve": {
56
+ "command": "uvx",
57
+ "args": ["helve-mcp"],
58
+ "env": {
59
+ "HELVE_API_KEY": "sk_live_..."
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ > If your MCP client supports remote Streamable HTTP directly, you can also connect to `https://helve.dev/mcp` with `Authorization: Bearer sk_live_...` (or OAuth 2.1).
67
+
68
+ ## Quickstart (Python REST client)
69
+
70
+ ```python
71
+ from helve_mcp import HelveClient
72
+
73
+ client = HelveClient() # reads HELVE_API_KEY from environment
74
+
75
+ # 1. Discover tools (no API key required)
76
+ tools = client.search_tools("web extract", limit=5)
77
+
78
+ # 2. Invoke any tool by tool_id (requires HELVE_API_KEY)
79
+ result = client.call_tool(
80
+ "helve.web_extract",
81
+ {"urls": ["https://docs.helve.dev"], "content": {"max_chars": 4000}},
82
+ )
83
+ print(result)
84
+ ```
85
+
86
+ ## Links
87
+
88
+ - Website: https://helve.dev
89
+ - MCP Guide: https://docs.helve.dev/mcp-server
90
+ - Source & Agent Skills: https://github.com/helve-dev/helve-mcp
@@ -0,0 +1,12 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/helve_mcp/__init__.py
5
+ src/helve_mcp/cli.py
6
+ src/helve_mcp/client.py
7
+ src/helve_mcp.egg-info/PKG-INFO
8
+ src/helve_mcp.egg-info/SOURCES.txt
9
+ src/helve_mcp.egg-info/dependency_links.txt
10
+ src/helve_mcp.egg-info/entry_points.txt
11
+ src/helve_mcp.egg-info/top_level.txt
12
+ tests/test_helve_mcp.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ helve-mcp = helve_mcp.cli:main
@@ -0,0 +1 @@
1
+ helve_mcp
@@ -0,0 +1,53 @@
1
+ import unittest
2
+ from helve_mcp import HelveClient, extract_json_from_sse, forward_jsonrpc, parse_args
3
+
4
+
5
+ class TestHelveMcp(unittest.TestCase):
6
+ def test_parse_args(self):
7
+ opts = parse_args(["--url", "https://example.com/mcp", "--api-key", "sk_test"])
8
+ self.assertEqual(opts["endpoint"], "https://example.com/mcp")
9
+ self.assertEqual(opts["api_key"], "sk_test")
10
+ self.assertFalse(opts["help"])
11
+
12
+ def test_extract_json_from_sse(self):
13
+ sse = 'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"ok":true}}\n\ndata: [DONE]\n'
14
+ msgs = extract_json_from_sse(sse)
15
+ self.assertEqual(len(msgs), 1)
16
+ self.assertEqual(msgs[0]["id"], 1)
17
+
18
+ def test_live_mcp_initialize_and_tools_list(self):
19
+ res, sid = forward_jsonrpc(
20
+ {
21
+ "jsonrpc": "2.0",
22
+ "id": 1,
23
+ "method": "initialize",
24
+ "params": {
25
+ "protocolVersion": "2025-03-26",
26
+ "capabilities": {},
27
+ "clientInfo": {"name": "helve-mcp-py-test", "version": "2.0.2"},
28
+ },
29
+ }
30
+ )
31
+ self.assertTrue(len(res) >= 1)
32
+ self.assertIn("result", res[0])
33
+
34
+ tools_res, _ = forward_jsonrpc(
35
+ {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
36
+ session_id=sid,
37
+ )
38
+ self.assertTrue(len(tools_res) >= 1)
39
+ tools = tools_res[0]["result"]["tools"]
40
+ names = {t["name"] for t in tools}
41
+ self.assertIn("search_tools", names)
42
+ self.assertIn("call_tool", names)
43
+ self.assertIn("list_categories", names)
44
+
45
+ def test_live_rest_search_tools(self):
46
+ client = HelveClient(api_key="")
47
+ data = client.search_tools("web extract", limit=3)
48
+ self.assertIn("tools", data)
49
+ self.assertTrue(len(data["tools"]) >= 1)
50
+
51
+
52
+ if __name__ == "__main__":
53
+ unittest.main()