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.
- helve_mcp-2.0.2/LICENSE +21 -0
- helve_mcp-2.0.2/PKG-INFO +90 -0
- helve_mcp-2.0.2/README.md +65 -0
- helve_mcp-2.0.2/pyproject.toml +39 -0
- helve_mcp-2.0.2/setup.cfg +4 -0
- helve_mcp-2.0.2/src/helve_mcp/__init__.py +14 -0
- helve_mcp-2.0.2/src/helve_mcp/cli.py +173 -0
- helve_mcp-2.0.2/src/helve_mcp/client.py +107 -0
- helve_mcp-2.0.2/src/helve_mcp.egg-info/PKG-INFO +90 -0
- helve_mcp-2.0.2/src/helve_mcp.egg-info/SOURCES.txt +12 -0
- helve_mcp-2.0.2/src/helve_mcp.egg-info/dependency_links.txt +1 -0
- helve_mcp-2.0.2/src/helve_mcp.egg-info/entry_points.txt +2 -0
- helve_mcp-2.0.2/src/helve_mcp.egg-info/top_level.txt +1 -0
- helve_mcp-2.0.2/tests/test_helve_mcp.py +53 -0
helve_mcp-2.0.2/LICENSE
ADDED
|
@@ -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.
|
helve_mcp-2.0.2/PKG-INFO
ADDED
|
@@ -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,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 @@
|
|
|
1
|
+
|
|
@@ -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()
|