helius-mcp 1.0.0 → 1.3.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 (33) hide show
  1. package/CHANGELOG.md +79 -52
  2. package/LICENSE +21 -21
  3. package/README.md +132 -132
  4. package/dist/http.d.ts +1 -1
  5. package/dist/index.js +67 -53
  6. package/dist/scripts/test-htmltotext.d.ts +5 -0
  7. package/dist/scripts/test-htmltotext.js +67 -0
  8. package/dist/scripts/test-solana-knowledge.d.ts +9 -0
  9. package/dist/scripts/test-solana-knowledge.js +272 -0
  10. package/dist/scripts/validate-templates.d.ts +12 -0
  11. package/dist/scripts/validate-templates.js +94 -0
  12. package/dist/tools/auth.js +58 -15
  13. package/dist/tools/index.js +38 -0
  14. package/dist/tools/network.js +35 -2
  15. package/dist/tools/shared.js +12 -12
  16. package/dist/utils/errors.js +20 -0
  17. package/dist/utils/feedback.d.ts +2 -0
  18. package/dist/utils/feedback.js +75 -13
  19. package/dist/version.d.ts +1 -1
  20. package/dist/version.js +1 -1
  21. package/package.json +64 -64
  22. package/system-prompts/helius/claude.system.md +170 -169
  23. package/system-prompts/helius/full.md +2869 -2868
  24. package/system-prompts/helius/openai.developer.md +170 -169
  25. package/system-prompts/helius-dflow/claude.system.md +290 -289
  26. package/system-prompts/helius-dflow/full.md +3648 -3647
  27. package/system-prompts/helius-dflow/openai.developer.md +290 -289
  28. package/system-prompts/helius-phantom/claude.system.md +333 -332
  29. package/system-prompts/helius-phantom/full.md +5473 -5472
  30. package/system-prompts/helius-phantom/openai.developer.md +333 -332
  31. package/system-prompts/svm/claude.system.md +160 -159
  32. package/system-prompts/svm/full.md +633 -632
  33. package/system-prompts/svm/openai.developer.md +160 -159
package/CHANGELOG.md CHANGED
@@ -1,52 +1,79 @@
1
- # Changelog
2
-
3
- All notable changes to this project will be documented in this file.
4
-
5
- The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
6
- and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
-
8
- Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
9
-
10
- ## helius-mcp@1.0.0 - 2026-03-03
11
-
12
- ### Merged
13
-
14
- - feat: Cross-platform skill portability for non-Claude developers [`#42`](https://github.com/helius-labs/core-ai/pull/42)
15
- - feat(MCP): Improve Testing Suite [`#41`](https://github.com/helius-labs/core-ai/pull/41)
16
- - feat(MCP): Add Changelog [`#43`](https://github.com/helius-labs/core-ai/pull/43)
17
- - feat(MCP): Prep For 1.0.0 Release [`#40`](https://github.com/helius-labs/core-ai/pull/40)
18
- - release: helius-cli@1.1.0 [`#39`](https://github.com/helius-labs/core-ai/pull/39)
19
- - feat(docs): Better `README.md` Files [`#38`](https://github.com/helius-labs/core-ai/pull/38)
20
- - feat(mcp): add transferSol and transferToken tools [`#35`](https://github.com/helius-labs/core-ai/pull/35)
21
- - Add Helius x Phantom frontend skill [`#33`](https://github.com/helius-labs/core-ai/pull/33)
22
- - Standardize MCP Zod parameter descriptions [`#36`](https://github.com/helius-labs/core-ai/pull/36)
23
- - feat(mcp): reduce token usage across MCP server and SKILL.md [`#34`](https://github.com/helius-labs/core-ai/pull/34)
24
- - feat(skill): Add SVM Skill [`#37`](https://github.com/helius-labs/core-ai/pull/37)
25
- - Fix MCP tool selection ambiguity with BEST FOR/PREFER routing [`#32`](https://github.com/helius-labs/core-ai/pull/32)
26
- - Replace hardcoded billing data with live doc fetches [`#31`](https://github.com/helius-labs/core-ai/pull/31)
27
- - feat(mcp + cli): Add Solana Knowledge Tools [`#30`](https://github.com/helius-labs/core-ai/pull/30)
28
- - fix(cli): Improve Signup UX [`#29`](https://github.com/helius-labs/core-ai/pull/29)
29
- - feat(skill): Add Helius x DFlow Skill [`#27`](https://github.com/helius-labs/core-ai/pull/27)
30
- - Remove vestigial projectType from recommendStack [`#28`](https://github.com/helius-labs/core-ai/pull/28)
31
- - Add recommendStack MCP tool for architecture recommendations [`#25`](https://github.com/helius-labs/core-ai/pull/25)
32
- - feat(docs) Add README [`#11`](https://github.com/helius-labs/core-ai/pull/11)
33
- - feat(plugin): Add Helius Plugin For Claude Code [`#26`](https://github.com/helius-labs/core-ai/pull/26)
34
- - chore(GitHub): Add `.claude` to `.gitignore` [`#24`](https://github.com/helius-labs/core-ai/pull/24)
35
- - feat(mcp): Improve Onboarding [`#23`](https://github.com/helius-labs/core-ai/pull/23)
36
- - Improve MCP tool routing [`#22`](https://github.com/helius-labs/core-ai/pull/22)
37
- - feat(skills): Add Helius Skill [`#20`](https://github.com/helius-labs/core-ai/pull/20)
38
- - feat(cli): Better Errors [`#16`](https://github.com/helius-labs/core-ai/pull/16)
39
- - feat(mcp): Add Credit Cost Annotations [`#18`](https://github.com/helius-labs/core-ai/pull/18)
40
- - feat(mcp): Make All Data-bearing Guide Tools Fetch Directly From the Docs [`#19`](https://github.com/helius-labs/core-ai/pull/19)
41
- - feat(mcp): Add `getAccountStatus` Tool [`#17`](https://github.com/helius-labs/core-ai/pull/17)
42
- - fix: pass customer info through upgradePlan and CLI upgrade [`#15`](https://github.com/helius-labs/core-ai/pull/15)
43
- - feat(cli): Format Snake Case Enums Into Title Case [`#14`](https://github.com/helius-labs/core-ai/pull/14)
44
- - feat(cli): Explicitly Set Project ID on CLI Creation [`#13`](https://github.com/helius-labs/core-ai/pull/13)
45
- - feat: OpenPay integration for CLI and MCP server [`#10`](https://github.com/helius-labs/core-ai/pull/10)
46
- - feat/agent-signup [`#9`](https://github.com/helius-labs/core-ai/pull/9)
47
- - Add docs integration and cleanup [`#6`](https://github.com/helius-labs/core-ai/pull/6)
48
- - fix: migrate to use sdk [`#8`](https://github.com/helius-labs/core-ai/pull/8)
49
- - feat/claude.md and helius-sdk for cli [`#7`](https://github.com/helius-labs/core-ai/pull/7)
50
- - feat: add error handling [`#4`](https://github.com/helius-labs/core-ai/pull/4)
51
- - fix: repair updateWebhook and deleteWebhook MCP tools [`#2`](https://github.com/helius-labs/core-ai/pull/2)
52
- - feat: upgrade helius-mcp data tools with rich formatting and new capa… [`#1`](https://github.com/helius-labs/core-ai/pull/1)
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
9
+
10
+ ## [helius-mcp@1.3.0](https://github.com/helius-labs/core-ai/compare/helius-mcp@1.2.0...helius-mcp@1.3.0) - 2026-03-12
11
+
12
+ ### Merged
13
+
14
+ - feat(skills): Add Skill Versioning [`#61`](https://github.com/helius-labs/core-ai/pull/61)
15
+ - fix(mcp): Add Escalating Retry Guidance For Agents [`#60`](https://github.com/helius-labs/core-ai/pull/60)
16
+ - feat(cli): Unify Error Handling Across Commands [`#57`](https://github.com/helius-labs/core-ai/pull/57)
17
+ - feat(cli): Add `helius plans` Command [`#58`](https://github.com/helius-labs/core-ai/pull/58)
18
+ - feat(cli): Add `status` Command [`#56`](https://github.com/helius-labs/core-ai/pull/56)
19
+ - feat(cli): Add Client-Side Input Validation For Signup, Upgrade, and Webhooks [`#55`](https://github.com/helius-labs/core-ai/pull/55)
20
+ - feat(MCP): Add TPS to `getNetworkStatus` [`#53`](https://github.com/helius-labs/core-ai/pull/53)
21
+ - fix(cli): Silent Exit in non-JSON Mode [`#54`](https://github.com/helius-labs/core-ai/pull/54)
22
+ - feat(cli): Improve Messaging For Interrupted Signups [`#52`](https://github.com/helius-labs/core-ai/pull/52)
23
+ - feat(cli): Implement Better Error Handling With Custom Catch Block [`#51`](https://github.com/helius-labs/core-ai/pull/51)
24
+ - feat(cli): Add `--wait` Flag to `helius signup` [`#50`](https://github.com/helius-labs/core-ai/pull/50)
25
+ - chore: update CHANGELOG.md for helius-mcp@1.2.0 [`#49`](https://github.com/helius-labs/core-ai/pull/49)
26
+
27
+ ## [helius-mcp@1.2.0](https://github.com/helius-labs/core-ai/compare/helius-mcp@1.0.0...helius-mcp@1.2.0) - 2026-03-08
28
+
29
+ ### Merged
30
+
31
+ - Bump helius-mcp and helius-cli to 1.2.0 [`#48`](https://github.com/helius-labs/core-ai/pull/48)
32
+ - feat: agentic feedback loop [`#47`](https://github.com/helius-labs/core-ai/pull/47)
33
+ - feat(plugin): Add Temp Claude Marketplace Workaround [`#46`](https://github.com/helius-labs/core-ai/pull/46)
34
+ - feat(plugin): Make Helius Cursor Plugin [`#45`](https://github.com/helius-labs/core-ai/pull/45)
35
+ - chore: update CHANGELOG.md for helius-mcp@1.0.0 [`#44`](https://github.com/helius-labs/core-ai/pull/44)
36
+
37
+ ## helius-mcp@1.0.0 - 2026-03-03
38
+
39
+ ### Merged
40
+
41
+ - feat: Cross-platform skill portability for non-Claude developers [`#42`](https://github.com/helius-labs/core-ai/pull/42)
42
+ - feat(MCP): Improve Testing Suite [`#41`](https://github.com/helius-labs/core-ai/pull/41)
43
+ - feat(MCP): Add Changelog [`#43`](https://github.com/helius-labs/core-ai/pull/43)
44
+ - feat(MCP): Prep For 1.0.0 Release [`#40`](https://github.com/helius-labs/core-ai/pull/40)
45
+ - release: helius-cli@1.1.0 [`#39`](https://github.com/helius-labs/core-ai/pull/39)
46
+ - feat(docs): Better `README.md` Files [`#38`](https://github.com/helius-labs/core-ai/pull/38)
47
+ - feat(mcp): add transferSol and transferToken tools [`#35`](https://github.com/helius-labs/core-ai/pull/35)
48
+ - Add Helius x Phantom frontend skill [`#33`](https://github.com/helius-labs/core-ai/pull/33)
49
+ - Standardize MCP Zod parameter descriptions [`#36`](https://github.com/helius-labs/core-ai/pull/36)
50
+ - feat(mcp): reduce token usage across MCP server and SKILL.md [`#34`](https://github.com/helius-labs/core-ai/pull/34)
51
+ - feat(skill): Add SVM Skill [`#37`](https://github.com/helius-labs/core-ai/pull/37)
52
+ - Fix MCP tool selection ambiguity with BEST FOR/PREFER routing [`#32`](https://github.com/helius-labs/core-ai/pull/32)
53
+ - Replace hardcoded billing data with live doc fetches [`#31`](https://github.com/helius-labs/core-ai/pull/31)
54
+ - feat(mcp + cli): Add Solana Knowledge Tools [`#30`](https://github.com/helius-labs/core-ai/pull/30)
55
+ - fix(cli): Improve Signup UX [`#29`](https://github.com/helius-labs/core-ai/pull/29)
56
+ - feat(skill): Add Helius x DFlow Skill [`#27`](https://github.com/helius-labs/core-ai/pull/27)
57
+ - Remove vestigial projectType from recommendStack [`#28`](https://github.com/helius-labs/core-ai/pull/28)
58
+ - Add recommendStack MCP tool for architecture recommendations [`#25`](https://github.com/helius-labs/core-ai/pull/25)
59
+ - feat(docs) Add README [`#11`](https://github.com/helius-labs/core-ai/pull/11)
60
+ - feat(plugin): Add Helius Plugin For Claude Code [`#26`](https://github.com/helius-labs/core-ai/pull/26)
61
+ - chore(GitHub): Add `.claude` to `.gitignore` [`#24`](https://github.com/helius-labs/core-ai/pull/24)
62
+ - feat(mcp): Improve Onboarding [`#23`](https://github.com/helius-labs/core-ai/pull/23)
63
+ - Improve MCP tool routing [`#22`](https://github.com/helius-labs/core-ai/pull/22)
64
+ - feat(skills): Add Helius Skill [`#20`](https://github.com/helius-labs/core-ai/pull/20)
65
+ - feat(cli): Better Errors [`#16`](https://github.com/helius-labs/core-ai/pull/16)
66
+ - feat(mcp): Add Credit Cost Annotations [`#18`](https://github.com/helius-labs/core-ai/pull/18)
67
+ - feat(mcp): Make All Data-bearing Guide Tools Fetch Directly From the Docs [`#19`](https://github.com/helius-labs/core-ai/pull/19)
68
+ - feat(mcp): Add `getAccountStatus` Tool [`#17`](https://github.com/helius-labs/core-ai/pull/17)
69
+ - fix: pass customer info through upgradePlan and CLI upgrade [`#15`](https://github.com/helius-labs/core-ai/pull/15)
70
+ - feat(cli): Format Snake Case Enums Into Title Case [`#14`](https://github.com/helius-labs/core-ai/pull/14)
71
+ - feat(cli): Explicitly Set Project ID on CLI Creation [`#13`](https://github.com/helius-labs/core-ai/pull/13)
72
+ - feat: OpenPay integration for CLI and MCP server [`#10`](https://github.com/helius-labs/core-ai/pull/10)
73
+ - feat/agent-signup [`#9`](https://github.com/helius-labs/core-ai/pull/9)
74
+ - Add docs integration and cleanup [`#6`](https://github.com/helius-labs/core-ai/pull/6)
75
+ - fix: migrate to use sdk [`#8`](https://github.com/helius-labs/core-ai/pull/8)
76
+ - feat/claude.md and helius-sdk for cli [`#7`](https://github.com/helius-labs/core-ai/pull/7)
77
+ - feat: add error handling [`#4`](https://github.com/helius-labs/core-ai/pull/4)
78
+ - fix: repair updateWebhook and deleteWebhook MCP tools [`#2`](https://github.com/helius-labs/core-ai/pull/2)
79
+ - feat: upgrade helius-mcp data tools with rich formatting and new capa… [`#1`](https://github.com/helius-labs/core-ai/pull/1)
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Helius Labs
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 Helius Labs
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,132 +1,132 @@
1
- # Helius MCP Server
2
-
3
- MCP server for Helius — Solana blockchain data access for AI assistants, provided by Solana's fastest, most reliable infrastructure provider
4
-
5
- See the [CHANGELOG](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md) for version history and release notes.
6
-
7
- Interested in contributing? Read the [contribution guide](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md) before opening a PR.
8
-
9
- ## Quick Start
10
-
11
- ### 1. Add the MCP server
12
-
13
- Add to your MCP host's config (works with Claude, Cursor, Windsurf, and any MCP-compatible client):
14
-
15
- ```json
16
- {
17
- "mcpServers": {
18
- "helius": {
19
- "command": "npx",
20
- "args": ["helius-mcp@latest"]
21
- }
22
- }
23
- }
24
- ```
25
-
26
- Or if you're using Claude Code:
27
-
28
- ```bash
29
- claude mcp add helius npx helius-mcp@latest
30
- ```
31
-
32
- ### 2. Configure your API key
33
-
34
- **If you already have a Helius API key:**
35
-
36
- ```bash
37
- export HELIUS_API_KEY=your-api-key
38
- ```
39
-
40
- Or set it from your AI assistant by calling the `setHeliusApiKey` tool.
41
-
42
- **If you need a new account:**
43
-
44
- The MCP includes a fully autonomous signup flow — no browser needed:
45
-
46
- 1. Call the `generateKeypair` tool — it creates a Solana wallet and returns the address
47
- 2. Fund the wallet with **~0.001 SOL** (transaction fees) + **1 USDC** (basic plan costs $1)
48
- 3. Call `checkSignupBalance` to verify funds arrived
49
- 4. Call `agenticSignup` to create your account — API key is configured automatically
50
-
51
- > **Paid plans (developer/business/professional):** `agenticSignup` and `upgradePlan` require `email`, `firstName`, and `lastName`. Basic plan does not.
52
-
53
- Or do the same from the terminal:
54
-
55
- ```bash
56
- npx helius-cli@latest keygen # Generate keypair
57
- # Fund the wallet address shown above with ~0.001 SOL + 1 USDC
58
- npx helius-cli@latest signup # Verify balance + create account
59
- ```
60
-
61
- ### 3. Start using tools
62
-
63
- Ask questions in plain English — the right tool is selected automatically:
64
-
65
- - "What NFTs does this wallet own?"
66
- - "Parse this transaction: 5abc..."
67
- - "Get the balance of Gh9ZwEm..."
68
- - "Create a webhook for \<address\>"
69
-
70
- ## Tools
71
-
72
- **Onboarding (6):** getStarted, setHeliusApiKey, generateKeypair, checkSignupBalance, agenticSignup, getAccountStatus
73
-
74
- **DAS API (9):** getAsset (single + batch), getAssetsByOwner, getAssetsByGroup, searchAssets (routes getAssetsByCreator / getAssetsByAuthority), getAssetProof, getAssetProofBatch, getSignaturesForAsset, getNftEditions, getTokenAccounts
75
-
76
- **RPC (5):** getBalance, getTokenBalances, getAccountInfo (single + batch), getNetworkStatus, getBlock
77
-
78
- **Transactions (2):** parseTransactions, getTransactionHistory
79
-
80
- **Transfers (2):** transferSol, transferToken
81
-
82
- **Priority Fees (1):** getPriorityFeeEstimate
83
-
84
- **Tokens (2):** getTokenHolders, getProgramAccounts
85
-
86
- **Webhooks (5):** getAllWebhooks, getWebhookByID, createWebhook, updateWebhook, deleteWebhook
87
-
88
- **Enhanced WebSockets (3):** transactionSubscribe, accountSubscribe, getEnhancedWebSocketInfo
89
-
90
- **Laserstream gRPC (2):** laserstreamSubscribe, getLaserstreamInfo
91
-
92
- **Wallet (6):** getWalletIdentity, batchWalletIdentity, getWalletBalances, getWalletHistory, getWalletTransfers, getWalletFundedBy
93
-
94
- **Plans & Billing (5):** getHeliusPlanInfo, compareHeliusPlans, previewUpgrade, upgradePlan, payRenewal
95
-
96
- **Docs & Guides (10):** lookupHeliusDocs, listHeliusDocTopics, getHeliusCreditsInfo, getRateLimitInfo, troubleshootError, getSenderInfo, getWebhookGuide, getLatencyComparison, getPumpFunGuide, recommendStack
97
-
98
- **Solana Knowledge (5):** getSIMD, listSIMDs, searchSolanaDocs, readSolanaSourceFile, fetchHeliusBlog
99
-
100
- ## System Prompts
101
-
102
- This package ships with pre-built system prompts that teach AI models how to use Helius tools effectively. Find them in `system-prompts/`:
103
-
104
- ```
105
- system-prompts/
106
- ├── helius/ # Core Helius skill
107
- ├── helius-dflow/ # DFlow trading skill
108
- ├── helius-phantom/ # Phantom frontend skill
109
- └── svm/ # SVM architecture skill
110
- ```
111
-
112
- Each contains three variants:
113
- - `openai.developer.md` — for OpenAI Responses/Chat Completions API (`developer` message)
114
- - `claude.system.md` — for Claude API (system prompt)
115
- - `full.md` — self-contained with all references inlined (Cursor Rules, ChatGPT, etc.)
116
-
117
- See [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) for integration guides and code examples.
118
-
119
- ## Networks
120
-
121
- Mainnet Beta (default) and Devnet. Set via `HELIUS_NETWORK` env var or `setNetwork` in the session
122
-
123
- ## Related Resources
124
-
125
- - [Full Documentation](https://www.helius.dev/docs)
126
- - [LLM-Optimized Docs](https://www.helius.dev/docs/llms.txt)
127
- - [API Reference](https://www.helius.dev/docs/api-reference)
128
- - [Billing and Credits](https://www.helius.dev/docs/billing/credits.md)
129
- - [Rate Limits](https://www.helius.dev/docs/billing/rate-limits.md)
130
- - [Dashboard](https://dashboard.helius.dev)
131
- - [Status Page](https://helius.statuspage.io)
132
- - [Full Agent Signup Instructions](https://dashboard.helius.dev/agents.md)
1
+ # Helius MCP Server
2
+
3
+ MCP server for Helius — Solana blockchain data access for AI assistants, provided by Solana's fastest, most reliable infrastructure provider
4
+
5
+ See the [CHANGELOG](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md) for version history and release notes.
6
+
7
+ Interested in contributing? Read the [contribution guide](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md) before opening a PR.
8
+
9
+ ## Quick Start
10
+
11
+ ### 1. Add the MCP server
12
+
13
+ Add to your MCP host's config (works with Claude, Cursor, Windsurf, and any MCP-compatible client):
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "helius": {
19
+ "command": "npx",
20
+ "args": ["helius-mcp@latest"]
21
+ }
22
+ }
23
+ }
24
+ ```
25
+
26
+ Or if you're using Claude Code:
27
+
28
+ ```bash
29
+ claude mcp add helius npx helius-mcp@latest
30
+ ```
31
+
32
+ ### 2. Configure your API key
33
+
34
+ **If you already have a Helius API key:**
35
+
36
+ ```bash
37
+ export HELIUS_API_KEY=your-api-key
38
+ ```
39
+
40
+ Or set it from your AI assistant by calling the `setHeliusApiKey` tool.
41
+
42
+ **If you need a new account:**
43
+
44
+ The MCP includes a fully autonomous signup flow — no browser needed:
45
+
46
+ 1. Call the `generateKeypair` tool — it creates a Solana wallet and returns the address
47
+ 2. Fund the wallet with **~0.001 SOL** (transaction fees) + **1 USDC** (basic plan costs $1)
48
+ 3. Call `checkSignupBalance` to verify funds arrived
49
+ 4. Call `agenticSignup` to create your account — API key is configured automatically
50
+
51
+ > **Paid plans (developer/business/professional):** `agenticSignup` and `upgradePlan` require `email`, `firstName`, and `lastName`. Basic plan does not.
52
+
53
+ Or do the same from the terminal:
54
+
55
+ ```bash
56
+ npx helius-cli@latest keygen # Generate keypair
57
+ # Fund the wallet address shown above with ~0.001 SOL + 1 USDC
58
+ npx helius-cli@latest signup # Verify balance + create account
59
+ ```
60
+
61
+ ### 3. Start using tools
62
+
63
+ Ask questions in plain English — the right tool is selected automatically:
64
+
65
+ - "What NFTs does this wallet own?"
66
+ - "Parse this transaction: 5abc..."
67
+ - "Get the balance of Gh9ZwEm..."
68
+ - "Create a webhook for \<address\>"
69
+
70
+ ## Tools
71
+
72
+ **Onboarding (6):** getStarted, setHeliusApiKey, generateKeypair, checkSignupBalance, agenticSignup, getAccountStatus
73
+
74
+ **DAS API (9):** getAsset (single + batch), getAssetsByOwner, getAssetsByGroup, searchAssets (routes getAssetsByCreator / getAssetsByAuthority), getAssetProof, getAssetProofBatch, getSignaturesForAsset, getNftEditions, getTokenAccounts
75
+
76
+ **RPC (5):** getBalance, getTokenBalances, getAccountInfo (single + batch), getNetworkStatus, getBlock
77
+
78
+ **Transactions (2):** parseTransactions, getTransactionHistory
79
+
80
+ **Transfers (2):** transferSol, transferToken
81
+
82
+ **Priority Fees (1):** getPriorityFeeEstimate
83
+
84
+ **Tokens (2):** getTokenHolders, getProgramAccounts
85
+
86
+ **Webhooks (5):** getAllWebhooks, getWebhookByID, createWebhook, updateWebhook, deleteWebhook
87
+
88
+ **Enhanced WebSockets (3):** transactionSubscribe, accountSubscribe, getEnhancedWebSocketInfo
89
+
90
+ **Laserstream gRPC (2):** laserstreamSubscribe, getLaserstreamInfo
91
+
92
+ **Wallet (6):** getWalletIdentity, batchWalletIdentity, getWalletBalances, getWalletHistory, getWalletTransfers, getWalletFundedBy
93
+
94
+ **Plans & Billing (5):** getHeliusPlanInfo, compareHeliusPlans, previewUpgrade, upgradePlan, payRenewal
95
+
96
+ **Docs & Guides (10):** lookupHeliusDocs, listHeliusDocTopics, getHeliusCreditsInfo, getRateLimitInfo, troubleshootError, getSenderInfo, getWebhookGuide, getLatencyComparison, getPumpFunGuide, recommendStack
97
+
98
+ **Solana Knowledge (5):** getSIMD, listSIMDs, searchSolanaDocs, readSolanaSourceFile, fetchHeliusBlog
99
+
100
+ ## System Prompts
101
+
102
+ This package ships with pre-built system prompts that teach AI models how to use Helius tools effectively. Find them in `system-prompts/`:
103
+
104
+ ```
105
+ system-prompts/
106
+ ├── helius/ # Core Helius skill
107
+ ├── helius-dflow/ # DFlow trading skill
108
+ ├── helius-phantom/ # Phantom frontend skill
109
+ └── svm/ # SVM architecture skill
110
+ ```
111
+
112
+ Each contains three variants:
113
+ - `openai.developer.md` — for OpenAI Responses/Chat Completions API (`developer` message)
114
+ - `claude.system.md` — for Claude API (system prompt)
115
+ - `full.md` — self-contained with all references inlined (Cursor Rules, ChatGPT, etc.)
116
+
117
+ See [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) for integration guides and code examples.
118
+
119
+ ## Networks
120
+
121
+ Mainnet Beta (default) and Devnet. Set via `HELIUS_NETWORK` env var or `setNetwork` in the session
122
+
123
+ ## Related Resources
124
+
125
+ - [Full Documentation](https://www.helius.dev/docs)
126
+ - [LLM-Optimized Docs](https://www.helius.dev/docs/llms.txt)
127
+ - [API Reference](https://www.helius.dev/docs/api-reference)
128
+ - [Billing and Credits](https://www.helius.dev/docs/billing/credits.md)
129
+ - [Rate Limits](https://www.helius.dev/docs/billing/rate-limits.md)
130
+ - [Dashboard](https://dashboard.helius.dev)
131
+ - [Status Page](https://helius.statuspage.io)
132
+ - [Full Agent Signup Instructions](https://dashboard.helius.dev/agents.md)
package/dist/http.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const MCP_USER_AGENT = "helius-mcp/1.0.0";
1
+ export declare const MCP_USER_AGENT = "helius-mcp/1.3.0";
package/dist/index.js CHANGED
@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
4
4
  import { registerTools } from './tools/index.js';
5
5
  import { setApiKey, setSessionSecretKey, setSessionWalletAddress } from './utils/helius.js';
6
6
  import { getSharedApiKey, loadKeypairFromDisk } from './utils/config.js';
7
+ import { captureClientInfo, captureWalletAddress } from './utils/feedback.js';
7
8
  import { loadKeypair } from 'helius-sdk/auth/loadKeypair';
8
9
  import { getAddress } from 'helius-sdk/auth/getAddress';
9
10
  import { version } from './version.js';
@@ -11,61 +12,73 @@ const server = new McpServer({
11
12
  name: 'helius-mcp',
12
13
  version
13
14
  }, {
14
- instructions: `These instructions provide fallback tool selection guidance. If you have more specific routing instructions from a Helius skill or system prompt, prefer those.
15
-
16
- ## Tool Routing
17
-
18
- | Intent | Tool | Credits |
19
- |--------|------|---------|
20
- | SOL balance | getBalance | 1 |
21
- | token balances by wallet | getTokenBalances | 10/pg |
22
- | full portfolio + USD | getWalletBalances | 100 |
23
- | parse tx by signature | parseTransactions | 100 |
24
- | wallet transaction history | getTransactionHistory | ~110 |
25
- | balance deltas/tx | getWalletHistory | 100 |
26
- | sends/receives | getWalletTransfers | 100 |
27
- | asset by mint (single or batch) | getAsset | 10 |
28
- | wallet NFTs | getAssetsByOwner | 10 |
29
- | filtered asset search / by creator or authority | searchAssets | 10 |
30
- | collection NFTs | getAssetsByGroup | 10 |
31
- | asset tx history (by mint) | getSignaturesForAsset | 10 |
32
- | edition prints of master NFT | getNftEditions | 10 |
33
- | cNFT Merkle proof (single or batch) | getAssetProof, getAssetProofBatch | 10 |
34
- | raw account inspection (single or batch) | getAccountInfo | 1 |
35
- | token holders by mint | getTokenHolders | ~20 |
36
- | token accounts by mint or owner | getTokenAccounts | 10 |
37
- | program accounts / protocol state | getProgramAccounts | 10 |
38
- | network status / epoch / block height | getNetworkStatus | 3 |
39
- | block data by slot | getBlock | 1 |
40
- | plans/pricing | getHeliusPlanInfo | 0 |
41
- | plan comparison | compareHeliusPlans | 0 |
42
- | plan upgrade / billing | previewUpgrade, upgradePlan, payRenewal | 0 |
43
- | rate limits/credits | getRateLimitInfo | 0 |
44
- | API docs by topic | lookupHeliusDocs | 0 |
45
- | error diagnosis | troubleshootError | 0 |
46
- | tx sending / Jito / SWQoS | getSenderInfo | 0 |
47
- | webhook setup guide | getWebhookGuide | 0 |
48
- | streaming latency | getLatencyComparison | 0 |
49
- | pump.fun tokens | getPumpFunGuide | 0 |
50
- | project architecture / stack selection | recommendStack | 0 |
51
- | Solana SIMDs / protocol proposals | getSIMD, listSIMDs | 0 |
52
- | Solana source / docs search | searchSolanaDocs, readSolanaSourceFile | 0 |
53
- | Helius blog posts | fetchHeliusBlog | 0 |
54
- | wallet identity | getWalletIdentity | 100 |
55
- | batch wallet identity | batchWalletIdentity | 100 |
56
- | funding source | getWalletFundedBy | 100 |
57
- | event notifications (any plan) | createWebhook | 100 |
58
- | live streaming (WS, Business+) | transactionSubscribe, accountSubscribe | — |
59
- | production streaming (gRPC, Pro) | laserstreamSubscribe | — |
60
- | Account setup | getStarted → generateKeypair → agenticSignup | — |
61
-
62
- Rules:
63
- - For pricing, start with getHeliusPlanInfo — NOT lookupHeliusDocs.
64
- - For errors, use troubleshootError first.
65
- - When a user describes ANY project they want to build ("I want to build/make/create...", "help me build...", "I need a..."), call recommendStack immediately with their description — do not ask clarifying questions first. After recommendations, use getHeliusPlanInfo for pricing and lookupHeliusDocs for API details.
66
- - "send SOL" / "transfer SOL" → transferSol (~3 credits). "send tokens" / "transfer USDC/BONK/etc" → transferToken (~13 credits). Both require a configured keypair (generateKeypair) and use Helius Sender.`
15
+ instructions: `These instructions provide fallback tool selection guidance. If you have more specific routing instructions from a Helius skill or system prompt, prefer those.
16
+
17
+ ## Tool Routing
18
+
19
+ | Intent | Tool | Credits |
20
+ |--------|------|---------|
21
+ | SOL balance | getBalance | 1 |
22
+ | token balances by wallet | getTokenBalances | 10/pg |
23
+ | full portfolio + USD | getWalletBalances | 100 |
24
+ | parse tx by signature | parseTransactions | 100 |
25
+ | wallet transaction history | getTransactionHistory | ~110 |
26
+ | balance deltas/tx | getWalletHistory | 100 |
27
+ | sends/receives | getWalletTransfers | 100 |
28
+ | asset by mint (single or batch) | getAsset | 10 |
29
+ | wallet NFTs | getAssetsByOwner | 10 |
30
+ | filtered asset search / by creator or authority | searchAssets | 10 |
31
+ | collection NFTs | getAssetsByGroup | 10 |
32
+ | asset tx history (by mint) | getSignaturesForAsset | 10 |
33
+ | edition prints of master NFT | getNftEditions | 10 |
34
+ | cNFT Merkle proof (single or batch) | getAssetProof, getAssetProofBatch | 10 |
35
+ | raw account inspection (single or batch) | getAccountInfo | 1 |
36
+ | token holders by mint | getTokenHolders | ~20 |
37
+ | token accounts by mint or owner | getTokenAccounts | 10 |
38
+ | program accounts / protocol state | getProgramAccounts | 10 |
39
+ | network status / epoch / block height | getNetworkStatus | 3 |
40
+ | block data by slot | getBlock | 1 |
41
+ | plans/pricing | getHeliusPlanInfo | 0 |
42
+ | plan comparison | compareHeliusPlans | 0 |
43
+ | plan upgrade / billing | previewUpgrade, upgradePlan, payRenewal | 0 |
44
+ | rate limits/credits | getRateLimitInfo | 0 |
45
+ | API docs by topic | lookupHeliusDocs | 0 |
46
+ | error diagnosis | troubleshootError | 0 |
47
+ | tx sending / Jito / SWQoS | getSenderInfo | 0 |
48
+ | webhook setup guide | getWebhookGuide | 0 |
49
+ | streaming latency | getLatencyComparison | 0 |
50
+ | pump.fun tokens | getPumpFunGuide | 0 |
51
+ | project architecture / stack selection | recommendStack | 0 |
52
+ | Solana SIMDs / protocol proposals | getSIMD, listSIMDs | 0 |
53
+ | Solana source / docs search | searchSolanaDocs, readSolanaSourceFile | 0 |
54
+ | Helius blog posts | fetchHeliusBlog | 0 |
55
+ | wallet identity | getWalletIdentity | 100 |
56
+ | batch wallet identity | batchWalletIdentity | 100 |
57
+ | funding source | getWalletFundedBy | 100 |
58
+ | event notifications (any plan) | createWebhook | 100 |
59
+ | live streaming (WS, Business+) | transactionSubscribe, accountSubscribe | — |
60
+ | production streaming (gRPC, Pro) | laserstreamSubscribe | — |
61
+ | Account setup | getStarted → generateKeypair → agenticSignup | — |
62
+
63
+ Rules:
64
+ - For pricing, start with getHeliusPlanInfo — NOT lookupHeliusDocs.
65
+ - For errors, use troubleshootError first.
66
+ - When a user describes ANY project they want to build ("I want to build/make/create...", "help me build...", "I need a..."), call recommendStack immediately with their description — do not ask clarifying questions first. After recommendations, use getHeliusPlanInfo for pricing and lookupHeliusDocs for API details.
67
+ - "send SOL" / "transfer SOL" → transferSol (~3 credits). "send tokens" / "transfer USDC/BONK/etc" → transferToken (~13 credits). Both require a configured keypair (generateKeypair) and use Helius Sender.
68
+
69
+ ## Feedback
70
+ Every tool accepts \`_feedback\` and \`_model\` params. Always include \`_model\` with your LLM model identifier (e.g. "claude-sonnet-4-20250514", "gpt-4o"). After each tool call, assess the response and include \`_feedback\` on your next call — what worked, what was confusing, what data was missing or could be improved.`
67
71
  });
68
72
  registerTools(server);
73
+ // Capture MCP client identity (Cursor, Claude Code, etc.) after handshake
74
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
75
+ server.server.oninitialized = () => {
76
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
77
+ const clientVersion = server.server.getClientVersion?.();
78
+ if (clientVersion) {
79
+ captureClientInfo(clientVersion);
80
+ }
81
+ };
69
82
  async function main() {
70
83
  if (process.env.HELIUS_API_KEY) {
71
84
  setApiKey(process.env.HELIUS_API_KEY);
@@ -84,6 +97,7 @@ async function main() {
84
97
  const address = await getAddress(walletKeypair);
85
98
  setSessionSecretKey(diskKey);
86
99
  setSessionWalletAddress(address);
100
+ captureWalletAddress(address);
87
101
  }
88
102
  catch {
89
103
  // Ignore invalid keypair on disk
package/dist/scripts/test-htmltotext.d.ts ADDED
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Quick test: fetch a real blog post and check htmlToText output quality.
3
+ * Run: node dist/scripts/test-htmltotext.js
4
+ */
5
+ export {};