kinetic-mcp 1.3.1 → 1.3.2

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 (4) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +138 -138
  3. package/package.json +53 -53
  4. package/scripts/setup.mjs +779 -760
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Kinetic
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.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kinetic
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,138 +1,138 @@
1
- # Kinetic MCP — Solana Trading for Claude Desktop
2
-
3
- [![npm](https://img.shields.io/npm/v/kinetic-mcp)](https://www.npmjs.com/package/kinetic-mcp)
4
-
5
- An MCP server that lets you check balances and swap tokens on Solana through natural language in Claude Desktop. Runs locally on your machine, powered by the [Kinetic](https://kinetic.xyz) trading platform.
6
-
7
- **Prerequisites:** [Node.js 20+](https://nodejs.org)
8
-
9
- ## Quick Start
10
-
11
- ### Option A: Setup Wizard (Recommended)
12
-
13
- The setup wizard walks you through keypair import and Claude Desktop configuration:
14
-
15
- ```bash
16
- npx kinetic-mcp setup
17
- ```
18
-
19
- ### Option B: Manual Configuration
20
-
21
- Add this to your Claude Desktop config file and restart Claude Desktop:
22
-
23
- | Platform | Config file path |
24
- | -------- | ----------------------------------------------------------------- |
25
- | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
26
- | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
27
- | Linux | `~/.config/Claude/claude_desktop_config.json` |
28
-
29
- ```json
30
- {
31
- "mcpServers": {
32
- "solana-trading": {
33
- "command": "npx",
34
- "args": ["-y", "kinetic-mcp"],
35
- "env": {
36
- "SOLANA_KEYPAIR_PATH": "/absolute/path/to/your/keypair.json"
37
- }
38
- }
39
- }
40
- }
41
- ```
42
-
43
- If you have a Kinetic API key, add `"API_KEY": "your_key"` to the `env` block.
44
-
45
- Restart Claude Desktop (fully quit and reopen — not just close the window). Look for the hammer icon in the chat input.
46
-
47
- ## Creating a Keypair
48
-
49
- You need a Solana keypair file — a JSON array of 64 integers in [Solana CLI format](https://docs.solanalabs.com/cli/wallets/file-system).
50
-
51
- ### Exporting from Phantom
52
-
53
- Open Phantom > Settings > Manage Accounts > [Your Account] > Show Private Key. Copy the base58 string.
54
-
55
- ### Converting to Keypair File
56
-
57
- Run from any directory:
58
-
59
- ```bash
60
- npx -y -p bs58 node --input-type=module -e "
61
- import bs58 from 'bs58';
62
- import { writeFileSync, mkdirSync } from 'fs';
63
- import { join } from 'path';
64
- import { homedir } from 'os';
65
- const dir = join(homedir(), '.config', 'solana');
66
- mkdirSync(dir, { recursive: true });
67
- const out = join(dir, 'trading-keypair.json');
68
- writeFileSync(out, JSON.stringify(Array.from(bs58.decode('YOUR_PRIVATE_KEY_HERE'))) + '\n');
69
- console.log('Saved to', out);
70
- "
71
- ```
72
-
73
- On macOS/Linux, lock down permissions: `chmod 600 ~/.config/solana/trading-keypair.json`
74
-
75
- Update `SOLANA_KEYPAIR_PATH` in your Claude Desktop config to point to the keypair file, then restart Claude Desktop.
76
-
77
- **Never share your private key, paste it into websites, or commit it to git.**
78
-
79
- ## Usage
80
-
81
- Try these prompts in Claude Desktop:
82
-
83
- - "What's my SOL balance?"
84
- - "Show me all my token holdings"
85
- - "Swap 0.01 SOL for USDC" — Claude shows a quote preview and asks for confirmation
86
- - "Swap 100 USDC for SOL with 1% slippage" — specify custom slippage
87
- - "Send 0.1 SOL to Abc123..." — previews transfer details, then confirms
88
- - "What's the price of BONK?" — get current token prices in USDC
89
- - "Show my recent transactions" — view last 10 transactions
90
-
91
- Claude will ask for permission the first time it uses a tool. Click "Allow for This Chat" or "Allow Always".
92
-
93
- ## Available Tools
94
-
95
- | Tool | Description | Inputs |
96
- | ------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
97
- | `get_wallet_balance` | Get SOL balance and all token holdings | None |
98
- | `swap_tokens` | Swap one token for another | `from_token`, `to_token`, `amount`, `slippage_bps` (optional), `confirm` |
99
- | `send_sol` | Send SOL to another wallet | `recipient`, `amount`, `confirm` |
100
- | `get_token_price` | Get current token prices in USDC | `tokens` (array of symbols or mints) |
101
- | `get_transaction_history` | Get 10 most recent wallet transactions | None |
102
-
103
- ## Safety Guardrails
104
-
105
- - **Two-step confirmation** — swaps and transfers always show a preview first; you must confirm before execution
106
- - **Max trade size** — `MAX_TRADE_SOL` limits swap size in SOL-equivalent (default: 10 SOL)
107
- - **Slippage cap** — maximum 10% (1000 bps) enforced by input validation
108
- - **No private key exposure** — keypair is loaded from a local file only, never accepted as tool input
109
-
110
- ## Troubleshooting
111
-
112
- | Problem | Solution |
113
- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
114
- | No hammer icon appears | Check that your config JSON is valid and the path is absolute. Fully restart Claude Desktop. |
115
- | "Unable to connect to MCP server" | Check Claude Desktop logs for errors. Verify Node.js 20+ is installed. |
116
- | Tools appear but return errors | Verify `SOLANA_KEYPAIR_PATH` points to a valid 64-byte keypair file. Test network access. |
117
- | "Cannot find module" errors | Run `npm install && npm run build` (if running from source). Make sure you're using Node.js 20+. |
118
- | Balance shows mint addresses | Token not in well-known table. Use the mint address directly for swaps. |
119
-
120
- **Where to find Claude Desktop logs:**
121
-
122
- - **macOS**: `~/Library/Logs/Claude/`
123
- - **Windows**: `%APPDATA%\Claude\logs\`
124
- - **Linux**: `~/.config/Claude/logs/`
125
-
126
- ## Configuration
127
-
128
- The only required environment variable is `SOLANA_KEYPAIR_PATH`. All others have sensible defaults.
129
-
130
- See [docs/development.md](docs/development.md#environment-variables) for the full configuration reference.
131
-
132
- ## Contributing
133
-
134
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
135
-
136
- ## License
137
-
138
- MIT
1
+ # Kinetic MCP — Solana Trading for Claude Desktop
2
+
3
+ [![npm](https://img.shields.io/npm/v/kinetic-mcp)](https://www.npmjs.com/package/kinetic-mcp)
4
+
5
+ An MCP server that lets you check balances and swap tokens on Solana through natural language in Claude Desktop. Runs locally on your machine, powered by the [Kinetic](https://kinetic.xyz) trading platform.
6
+
7
+ **Prerequisites:** [Node.js 20+](https://nodejs.org)
8
+
9
+ ## Quick Start
10
+
11
+ ### Option A: Setup Wizard (Recommended)
12
+
13
+ The setup wizard walks you through keypair import and Claude Desktop configuration:
14
+
15
+ ```bash
16
+ npx kinetic-mcp setup
17
+ ```
18
+
19
+ ### Option B: Manual Configuration
20
+
21
+ Add this to your Claude Desktop config file and restart Claude Desktop:
22
+
23
+ | Platform | Config file path |
24
+ | -------- | ----------------------------------------------------------------- |
25
+ | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
26
+ | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
27
+ | Linux | `~/.config/Claude/claude_desktop_config.json` |
28
+
29
+ ```json
30
+ {
31
+ "mcpServers": {
32
+ "solana-trading": {
33
+ "command": "npx",
34
+ "args": ["-y", "kinetic-mcp"],
35
+ "env": {
36
+ "SOLANA_KEYPAIR_PATH": "/absolute/path/to/your/keypair.json"
37
+ }
38
+ }
39
+ }
40
+ }
41
+ ```
42
+
43
+ If you have a Kinetic API key, add `"API_KEY": "your_key"` to the `env` block.
44
+
45
+ Restart Claude Desktop (fully quit and reopen — not just close the window). Look for the hammer icon in the chat input.
46
+
47
+ ## Creating a Keypair
48
+
49
+ You need a Solana keypair file — a JSON array of 64 integers in [Solana CLI format](https://docs.solanalabs.com/cli/wallets/file-system).
50
+
51
+ ### Exporting from Phantom
52
+
53
+ Open Phantom > Settings > Manage Accounts > [Your Account] > Show Private Key. Copy the base58 string.
54
+
55
+ ### Converting to Keypair File
56
+
57
+ Run from any directory:
58
+
59
+ ```bash
60
+ npx -y -p bs58 node --input-type=module -e "
61
+ import bs58 from 'bs58';
62
+ import { writeFileSync, mkdirSync } from 'fs';
63
+ import { join } from 'path';
64
+ import { homedir } from 'os';
65
+ const dir = join(homedir(), '.config', 'solana');
66
+ mkdirSync(dir, { recursive: true });
67
+ const out = join(dir, 'trading-keypair.json');
68
+ writeFileSync(out, JSON.stringify(Array.from(bs58.decode('YOUR_PRIVATE_KEY_HERE'))) + '\n');
69
+ console.log('Saved to', out);
70
+ "
71
+ ```
72
+
73
+ On macOS/Linux, lock down permissions: `chmod 600 ~/.config/solana/trading-keypair.json`
74
+
75
+ Update `SOLANA_KEYPAIR_PATH` in your Claude Desktop config to point to the keypair file, then restart Claude Desktop.
76
+
77
+ **Never share your private key, paste it into websites, or commit it to git.**
78
+
79
+ ## Usage
80
+
81
+ Try these prompts in Claude Desktop:
82
+
83
+ - "What's my SOL balance?"
84
+ - "Show me all my token holdings"
85
+ - "Swap 0.01 SOL for USDC" — Claude shows a quote preview and asks for confirmation
86
+ - "Swap 100 USDC for SOL with 1% slippage" — specify custom slippage
87
+ - "Send 0.1 SOL to Abc123..." — previews transfer details, then confirms
88
+ - "What's the price of BONK?" — get current token prices in USDC
89
+ - "Show my recent transactions" — view last 10 transactions
90
+
91
+ Claude will ask for permission the first time it uses a tool. Click "Allow for This Chat" or "Allow Always".
92
+
93
+ ## Available Tools
94
+
95
+ | Tool | Description | Inputs |
96
+ | ------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
97
+ | `get_wallet_balance` | Get SOL balance and all token holdings | None |
98
+ | `swap_tokens` | Swap one token for another | `from_token`, `to_token`, `amount`, `slippage_bps` (optional), `confirm` |
99
+ | `send_sol` | Send SOL to another wallet | `recipient`, `amount`, `confirm` |
100
+ | `get_token_price` | Get current token prices in USDC | `tokens` (array of symbols or mints) |
101
+ | `get_transaction_history` | Get 10 most recent wallet transactions | None |
102
+
103
+ ## Safety Guardrails
104
+
105
+ - **Two-step confirmation** — swaps and transfers always show a preview first; you must confirm before execution
106
+ - **Max trade size** — `MAX_TRADE_SOL` limits swap size in SOL-equivalent (default: 10 SOL)
107
+ - **Slippage cap** — maximum 10% (1000 bps) enforced by input validation
108
+ - **No private key exposure** — keypair is loaded from a local file only, never accepted as tool input
109
+
110
+ ## Troubleshooting
111
+
112
+ | Problem | Solution |
113
+ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
114
+ | No hammer icon appears | Check that your config JSON is valid and the path is absolute. Fully restart Claude Desktop. |
115
+ | "Unable to connect to MCP server" | Check Claude Desktop logs for errors. Verify Node.js 20+ is installed. |
116
+ | Tools appear but return errors | Verify `SOLANA_KEYPAIR_PATH` points to a valid 64-byte keypair file. Test network access. |
117
+ | "Cannot find module" errors | Run `npm install && npm run build` (if running from source). Make sure you're using Node.js 20+. |
118
+ | Balance shows mint addresses | Token not in well-known table. Use the mint address directly for swaps. |
119
+
120
+ **Where to find Claude Desktop logs:**
121
+
122
+ - **macOS**: `~/Library/Logs/Claude/`
123
+ - **Windows**: `%APPDATA%\Claude\logs\`
124
+ - **Linux**: `~/.config/Claude/logs/`
125
+
126
+ ## Configuration
127
+
128
+ The only required environment variable is `SOLANA_KEYPAIR_PATH`. All others have sensible defaults.
129
+
130
+ See [docs/development.md](docs/development.md#environment-variables) for the full configuration reference.
131
+
132
+ ## Contributing
133
+
134
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
135
+
136
+ ## License
137
+
138
+ MIT
package/package.json CHANGED
@@ -1,53 +1,53 @@
1
- {
2
- "name": "kinetic-mcp",
3
- "version": "1.3.1",
4
- "description": "MCP server for Solana trading via Kinetic API",
5
- "type": "module",
6
- "main": "build/index.js",
7
- "bin": {
8
- "kinetic-mcp": "build/index.js"
9
- },
10
- "files": [
11
- "build/",
12
- "scripts/setup.mjs"
13
- ],
14
- "engines": {
15
- "node": ">=20"
16
- },
17
- "scripts": {
18
- "build": "tsc",
19
- "dev": "tsc --watch",
20
- "start": "node build/index.js",
21
- "clean": "rm -rf build/",
22
- "typecheck": "tsc --noEmit",
23
- "lint": "eslint src/",
24
- "lint:fix": "eslint src/ --fix",
25
- "format": "prettier --write \"src/**/*.ts\"",
26
- "format:check": "prettier --check \"src/**/*.ts\"",
27
- "test": "vitest run",
28
- "test:watch": "vitest",
29
- "setup": "node scripts/setup.mjs"
30
- },
31
- "dependencies": {
32
- "@clack/prompts": "^1.0.1",
33
- "@modelcontextprotocol/sdk": "^1.27.0",
34
- "@solana/spl-token": "^0.4.9",
35
- "@solana/web3.js": "^1.95.0",
36
- "bs58": "^6.0.0",
37
- "gradient-string": "^3.0.0",
38
- "picocolors": "^1.1.1",
39
- "pino": "^10.3.1",
40
- "zod": "^3.23.0"
41
- },
42
- "devDependencies": {
43
- "@eslint/js": "^10.0.1",
44
- "@types/node": "^20.19.35",
45
- "eslint": "^10.0.2",
46
- "eslint-config-prettier": "^10.1.8",
47
- "globals": "^17.3.0",
48
- "prettier": "^3.8.1",
49
- "typescript": "^5.7.0",
50
- "typescript-eslint": "^8.56.1",
51
- "vitest": "^4.0.18"
52
- }
53
- }
1
+ {
2
+ "name": "kinetic-mcp",
3
+ "version": "1.3.2",
4
+ "description": "MCP server for Solana trading via Kinetic API",
5
+ "type": "module",
6
+ "main": "build/index.js",
7
+ "bin": {
8
+ "kinetic-mcp": "build/index.js"
9
+ },
10
+ "files": [
11
+ "build/",
12
+ "scripts/setup.mjs"
13
+ ],
14
+ "engines": {
15
+ "node": ">=20"
16
+ },
17
+ "scripts": {
18
+ "build": "tsc",
19
+ "dev": "tsc --watch",
20
+ "start": "node build/index.js",
21
+ "clean": "rm -rf build/",
22
+ "typecheck": "tsc --noEmit",
23
+ "lint": "eslint src/",
24
+ "lint:fix": "eslint src/ --fix",
25
+ "format": "prettier --write \"src/**/*.ts\"",
26
+ "format:check": "prettier --check \"src/**/*.ts\"",
27
+ "test": "vitest run",
28
+ "test:watch": "vitest",
29
+ "setup": "node scripts/setup.mjs"
30
+ },
31
+ "dependencies": {
32
+ "@clack/prompts": "^1.0.1",
33
+ "@modelcontextprotocol/sdk": "^1.27.0",
34
+ "@solana/spl-token": "^0.4.9",
35
+ "@solana/web3.js": "^1.95.0",
36
+ "bs58": "^6.0.0",
37
+ "gradient-string": "^3.0.0",
38
+ "picocolors": "^1.1.1",
39
+ "pino": "^10.3.1",
40
+ "zod": "^3.23.0"
41
+ },
42
+ "devDependencies": {
43
+ "@eslint/js": "^10.0.1",
44
+ "@types/node": "^20.19.35",
45
+ "eslint": "^10.0.2",
46
+ "eslint-config-prettier": "^10.1.8",
47
+ "globals": "^17.3.0",
48
+ "prettier": "^3.8.1",
49
+ "typescript": "^5.7.0",
50
+ "typescript-eslint": "^8.56.1",
51
+ "vitest": "^4.0.18"
52
+ }
53
+ }