@jtsang/nettune-mcp 0.0.1

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 (3) hide show
  1. package/README.md +186 -0
  2. package/dist/index.js +2190 -0
  3. package/package.json +49 -0
package/README.md ADDED
@@ -0,0 +1,186 @@
1
+ # @jtsang/nettune-mcp
2
+
3
+ MCP (Model Context Protocol) stdio wrapper for **nettune** - a TCP network optimization tool.
4
+
5
+ ## Overview
6
+
7
+ This package provides an `npx`-compatible entry point for the nettune client. It automatically downloads the appropriate nettune binary for your platform and launches it in MCP stdio mode, enabling integration with Chat GUIs that support MCP.
8
+
9
+ ## Installation
10
+
11
+ ### Using npx (recommended)
12
+
13
+ No installation required - just run:
14
+
15
+ ```bash
16
+ npx @jtsang/nettune-mcp --api-key YOUR_API_KEY --server http://your-server:9876
17
+ ```
18
+
19
+ ### Global Installation
20
+
21
+ ```bash
22
+ npm install -g @jtsang/nettune-mcp
23
+ # or
24
+ bun install -g @jtsang/nettune-mcp
25
+ ```
26
+
27
+ Then run:
28
+
29
+ ```bash
30
+ nettune-mcp --api-key YOUR_API_KEY --server http://your-server:9876
31
+ ```
32
+
33
+ ## Usage
34
+
35
+ ### Command Line Options
36
+
37
+ | Option | Required | Default | Description |
38
+ |--------|----------|---------|-------------|
39
+ | `--api-key`, `-k` | Yes | - | API key for server authentication |
40
+ | `--server`, `-s` | No | `http://127.0.0.1:9876` | Server URL |
41
+ | `--mcp-name` | No | `nettune` | MCP server name identifier |
42
+ | `--version-tag` | No | `latest` | Specific nettune version to use |
43
+ | `--verbose`, `-v` | No | `false` | Enable verbose logging |
44
+
45
+ ### Example
46
+
47
+ ```bash
48
+ # Connect to a remote server
49
+ npx @jtsang/nettune-mcp --api-key my-secret-key --server http://192.168.1.100:9876
50
+
51
+ # Use a specific version
52
+ npx @jtsang/nettune-mcp --api-key my-secret-key --version-tag v0.1.0
53
+
54
+ # Enable verbose logging
55
+ npx @jtsang/nettune-mcp --api-key my-secret-key --verbose
56
+ ```
57
+
58
+ ## Chat GUI Configuration
59
+
60
+ ### Cursor / Windsurf / Claude Desktop
61
+
62
+ Add to your MCP configuration file:
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "nettune": {
68
+ "command": "npx",
69
+ "args": [
70
+ "@jtsang/nettune-mcp",
71
+ "--api-key",
72
+ "YOUR_API_KEY",
73
+ "--server",
74
+ "http://your-server:9876"
75
+ ]
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ ### Using with Bun
82
+
83
+ ```json
84
+ {
85
+ "mcpServers": {
86
+ "nettune": {
87
+ "command": "bunx",
88
+ "args": [
89
+ "@jtsang/nettune-mcp",
90
+ "--api-key",
91
+ "YOUR_API_KEY",
92
+ "--server",
93
+ "http://your-server:9876"
94
+ ]
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ ## Available MCP Tools
101
+
102
+ Once connected, the following tools are available:
103
+
104
+ | Tool | Description |
105
+ |------|-------------|
106
+ | `nettune.test_rtt` | Test RTT/latency to the server |
107
+ | `nettune.test_throughput` | Test download/upload throughput |
108
+ | `nettune.test_latency_under_load` | Test latency during load |
109
+ | `nettune.snapshot_server` | Create a server state snapshot |
110
+ | `nettune.list_profiles` | List available optimization profiles |
111
+ | `nettune.show_profile` | Show details of a specific profile |
112
+ | `nettune.apply_profile` | Apply an optimization profile |
113
+ | `nettune.rollback` | Rollback to a previous snapshot |
114
+ | `nettune.status` | Get current server status |
115
+
116
+ ## Binary Caching
117
+
118
+ The wrapper automatically downloads and caches the nettune binary in:
119
+
120
+ - Linux: `$XDG_CACHE_HOME/nettune/` or `~/.cache/nettune/`
121
+ - macOS: `~/.cache/nettune/`
122
+ - Windows: `~/.cache/nettune/`
123
+
124
+ The binary is verified using SHA256 checksums when available.
125
+
126
+ ## Supported Platforms
127
+
128
+ | OS | Architecture |
129
+ |----|--------------|
130
+ | Linux | x64, arm64 |
131
+ | macOS | x64, arm64 |
132
+ | Windows | x64, arm64 (experimental) |
133
+
134
+ ## Server Setup
135
+
136
+ Before using this client, you need to start a nettune server:
137
+
138
+ ```bash
139
+ # On the server (Linux)
140
+ sudo nettune server --api-key YOUR_API_KEY --listen 0.0.0.0:9876
141
+ ```
142
+
143
+ ## Security Notes
144
+
145
+ - The API key is passed via command line argument. Ensure your shell history is secured.
146
+ - All communication between client and server uses HTTP with Bearer token authentication.
147
+ - Consider using TLS termination (e.g., nginx reverse proxy) for production deployments.
148
+
149
+ ## Troubleshooting
150
+
151
+ ### Binary Download Fails
152
+
153
+ 1. Check your internet connection
154
+ 2. Verify the GitHub releases exist: https://github.com/jtsang4/nettune/releases
155
+ 3. Try specifying a version: `--version-tag v0.1.0`
156
+
157
+ ### Connection Refused
158
+
159
+ 1. Verify the server is running
160
+ 2. Check firewall rules allow traffic on port 9876
161
+ 3. Ensure the server URL is correct (including `http://` prefix)
162
+
163
+ ### Authentication Failed
164
+
165
+ 1. Verify the API key matches between client and server
166
+ 2. Check the server logs for authentication errors
167
+
168
+ ## Development
169
+
170
+ ```bash
171
+ # Install dependencies
172
+ bun install
173
+
174
+ # Build
175
+ bun run build
176
+
177
+ # Type check
178
+ bun run typecheck
179
+
180
+ # Test
181
+ bun test
182
+ ```
183
+
184
+ ## License
185
+
186
+ MIT