@portproof/mcp 0.0.0-stage → 0.2.0

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.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +150 -2
  3. package/dist/index.js +1814 -0
  4. package/llms.txt +42 -0
  5. package/package.json +56 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Portproof
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.
package/README.md CHANGED
@@ -1,3 +1,151 @@
1
- # Temporary Holding Version
1
+ # @portproof/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The [Portproof](https://portproof.org) API as [Model Context Protocol](https://modelcontextprotocol.io) tools, so
4
+ Claude, Cursor and any other MCP client can check your balance, build proxy URLs, test a connection and top up
5
+ proxy traffic.
6
+
7
+ Portproof sells **proxy traffic by the GB**, paid in cryptocurrency. One balance and one credential work on two
8
+ shared pools: **Mobile 4G/5G** (carrier modems) and **Residential** (opt-in peer devices). Pool, country, rotation
9
+ and session are chosen in the proxy username, so an agent can switch between them per request without new
10
+ credentials. The pools are shared: a sticky session keeps the same device, and the carrier may still change its IP.
11
+
12
+ Lawful uses only: price monitoring, ad verification, market research, QA and geo-testing, AI agents and data
13
+ pipelines. See the [acceptable-use policy](https://portproof.org/legal/aup).
14
+
15
+ ## Quick start
16
+
17
+ 1. Buy GB at [portproof.org](https://portproof.org) (cryptocurrency).
18
+ 2. Create an API key in your dashboard under [API keys](https://portproof.org/app/keys). Give it `ports:write` to
19
+ build proxy URLs, test connections and buy traffic; `ports:read` is enough to read the balance.
20
+ 3. Add the server to your MCP client (below). It runs locally over stdio and needs Node.js 20 or newer:
21
+
22
+ ```bash
23
+ npx -y @portproof/mcp --help
24
+ ```
25
+
26
+ There is no sandbox: every key acts on your real balance, whatever its prefix. Keep the key in the client
27
+ configuration or a secret store, never in a prompt.
28
+
29
+ ## Claude Desktop
30
+
31
+ Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
32
+ Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and restart Claude Desktop:
33
+
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "portproof": {
38
+ "command": "npx",
39
+ "args": ["-y", "@portproof/mcp"],
40
+ "env": {
41
+ "PORTPROOF_API_KEY": "pk_live_..."
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ If Claude Desktop cannot find `npx`, use its absolute path (`which npx`).
49
+
50
+ ## Claude Code
51
+
52
+ ```bash
53
+ claude mcp add portproof --env PORTPROOF_API_KEY=pk_live_... -- npx -y @portproof/mcp
54
+ ```
55
+
56
+ Or commit a project-scoped `.mcp.json` and keep the key in your environment:
57
+
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "portproof": {
62
+ "command": "npx",
63
+ "args": ["-y", "@portproof/mcp"],
64
+ "env": {
65
+ "PORTPROOF_API_KEY": "${PORTPROOF_API_KEY}"
66
+ }
67
+ }
68
+ }
69
+ }
70
+ ```
71
+
72
+ Check with `claude mcp list`, or `/mcp` inside a session.
73
+
74
+ ## Cursor
75
+
76
+ Add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "portproof": {
82
+ "command": "npx",
83
+ "args": ["-y", "@portproof/mcp"],
84
+ "env": {
85
+ "PORTPROOF_API_KEY": "pk_live_..."
86
+ }
87
+ }
88
+ }
89
+ }
90
+ ```
91
+
92
+ Any other stdio MCP client takes the same three things: the command `npx`, the arguments `-y @portproof/mcp` and
93
+ the environment variables below.
94
+
95
+ ## Environment variables
96
+
97
+ | Variable | Default | Meaning |
98
+ | ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | `PORTPROOF_API_KEY` | unset | Your API key. Without it only the public tools work: `get_pricing`, `get_status`, `list_countries`, `search_inventory` and `quote`. |
100
+ | `PORTPROOF_API_URL` | `https://api.portproof.org` | API origin; `/v1` is appended (a URL ending in `/v1` is accepted too). Leave it unset unless you run a development copy of the API. |
101
+
102
+ ## Tools
103
+
104
+ ### Proxy traffic
105
+
106
+ | Tool | Input | What it does | Key scope |
107
+ | ----------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
108
+ | `get_traffic` | - | GB total, used and left, expiry, limits and connection details with the password masked. | `ports:read` |
109
+ | `list_countries` | - | Devices online now per pool and country (counts only; exit addresses are never listed). | none |
110
+ | `build_proxy_url` | `pool`, `country`, `rotation`, `session?`, `protocol?`, `reveal_password?` | Proxy username and URL plus curl, Python, Node and Playwright snippets. The password stays masked unless `reveal_password` is true. | `ports:write` |
111
+ | `test_connection` | `pool?`, `country?`, `rotation?` | One request through the gateway: exit IP, latency and an error code on failure. The exit country is not checked: look the exit IP up yourself if the country matters. Uses a few kilobytes of your balance; at most 6 a minute. | `ports:write` |
112
+ | `buy_traffic` | `gb` or `trial: true`, `accept_terms: true`, `confirm: true`, `idempotency_key` | Buys whole GB, or the one-off trial, from your account balance at the current tier price. Returns the GB and `cost_cents` the order recorded. | `ports:write` |
113
+ | `get_pricing` | - | The current per-GB price tiers, packages and trial. | none |
114
+ | `get_status` | - | Service status and public incidents. | none |
115
+
116
+ `pool` is `mobile`, `residential` or `best`; `country` is an ISO 3166-1 alpha-2 code or `any`; `rotation` is
117
+ `auto5`, `auto10`, `auto20`, `auto60` (a new IP every 5, 10, 20 or 60 minutes), `ondemand` or `sticky`; `protocol`
118
+ is `http` or `socks5`. Which countries have devices online changes through the day: ask `list_countries`.
119
+
120
+ `get_traffic` shows connection details only to a key with `ports:write`. A key without the scope a tool needs gets
121
+ `insufficient_scope`.
122
+
123
+ ### Dedicated ports (coming soon, not on sale yet)
124
+
125
+ `search_inventory`, `quote`, `buy_port`, `list_ports`, `get_port`, `rotate`, `set_rotation_schedule`,
126
+ `renew_port` (one more term from your account balance), `set_auto_renew`, `get_passport` (port details),
127
+ `get_receipt` (a rotation record, with its signature checked against the published keys) and `get_usage` work on
128
+ dedicated ports for organisations that already hold one. The server tells the model not to offer them.
129
+
130
+ Every port has a `label` (country, carrier and port id) and a `network`: `own` (Own network) or `partner` (Partner
131
+ network). Partner network ports are bought in the web shop, one SKU per term: `quote` and `buy_port` answer such a
132
+ SKU with its price and `shop_url` and charge nothing. Their HTTP and SOCKS5 connections can differ in host, port,
133
+ login and password, so `get_port` builds `proxy_urls` from each set, and `rotation_url` is the link that rotates the
134
+ IP when fetched.
135
+
136
+ ## Safety
137
+
138
+ - `buy_traffic`, `buy_port`, `renew_port`, `rotate`, `set_rotation_schedule` and `set_auto_renew` are refused,
139
+ without any request to the API, unless the call carries `confirm: true` and an `idempotency_key`. `buy_traffic` also needs `accept_terms: true`,
140
+ which records that you accept the terms, the acceptable-use policy and the immediate start of the service. The
141
+ server instructs the model to ask you before setting either.
142
+ - Retrying with the same `idempotency_key` replays the first answer instead of buying twice; a different purchase
143
+ needs a new key.
144
+ - Responses are compact JSON. Errors are `{"error":{"code","status","title","detail"}}` with the API's problem
145
+ codes (`insufficient_funds`, `trial_already_used`, `insufficient_scope`, `rate_limited`, ...) or a local code such
146
+ as `confirmation_required`, `not_on_sale` or `api_unreachable`.
147
+ - stdout carries only the MCP protocol; logs go to stderr.
148
+
149
+ ## Licence
150
+
151
+ MIT