[KLC-2170/KLC-2171] Add on-chain tools for Klever blockchain interaction#28
Conversation
Add KleverChainClient (zero-dependency, native fetch) with 11 methods for querying the Klever blockchain. Expose 7 read-only MCP tools (get_balance, get_account, get_asset_info, query_sc, get_transaction, get_block, list_validators) available in all profiles, plus 4 write tools (send_transfer, deploy_sc, invoke_sc, freeze_klv) gated to local profile only. Includes 26 unit tests for the chain client and 14 integration tests for MCP tool handlers.
There was a problem hiding this comment.
Pull request overview
This PR adds a Klever on-chain HTTP client and exposes new MCP tools for querying chain state in all profiles, plus local-only tools that build unsigned transactions for external signing. It also updates knowledge-base references to the newer klever-sc crate version and documents the new chain client/env vars.
Changes:
- Introduces
src/chain/(KleverChainClient) with typed helpers for node + API proxy endpoints, plus unit tests. - Extends MCP server tool definitions/handlers to add 7 read tools (public+local) and 4 write tools (local-only), with integration tests around exposure/blocking.
- Bumps
klever-sc/klever-sc-scenarioversion references in knowledge content and updatesCLAUDE.mddocs.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| src/mcp/server.ts | Adds chain tool definitions, profile gating, and tool handlers using KleverChainClient. |
| src/mcp/server.test.ts | Adds integration tests for chain tool listing/behavior in public vs local mode. |
| src/index.ts | Wires KleverChainClient into MCP server startup via env vars. |
| src/chain/client.ts | Implements the zero-dependency fetch-based Klever chain client. |
| src/chain/types.ts | Adds typed interfaces for Klever node/API proxy responses and request bodies. |
| src/chain/index.ts | Exposes chain client + types from a single module entrypoint. |
| src/chain/client.test.ts | Adds unit tests for the chain client (fetch mocking). |
| src/knowledge/tools/ksc.ts | Updates embedded Cargo.toml snippet to klever-sc 0.45.0. |
| src/knowledge/modules/pause.ts | Updates klever-sc-modules version references to 0.45.0. |
| src/knowledge/modules/admin.ts | Updates klever-sc-modules version references to 0.45.0. |
| CLAUDE.md | Documents chain client architecture and new env vars/tool availability. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add enum constraint to all network properties in tool schemas - Validate KLEVER_NETWORK env var with fallback and warning - Truncate large string args in debug logging (prevents wasmHex flooding) - Save/restore global.fetch in test files for proper isolation - Add deploy_sc and invoke_sc local-mode integration tests - Add getKDAInfo unit tests (happy path, URL encoding, error)
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Set idempotentHint to false on chain write tools (nonce-dependent) - Fix getKDAInfo test mock to match KDAData interface shape
RomuloSiebra
left a comment
RomuloSiebra
left a comment
There was a problem hiding this comment.
The current TransactionBuildRequest has a field contracts, and from what I saw, it seems to not match the actual node API body request. With that in mind, I think we will need to review the body requests from src/mcp/server.ts after the changes
- Fix SmartContract type from 9 to 63 (transaction.proto)
- Fix SC sub-types: deploy=scType:1, invoke=scType:0 (were swapped)
- Fix callValue format to map of token ID to amount ({KLV: amount})
- Fix Freeze type from 2 to 4 (FreezeContractType)
- Fix TransactionBuildRequest to use flat contracts array
- Add builder methods to KleverChainClient (buildTransfer, buildDeploy,
buildInvoke, buildFreeze) to move chain logic out of server.ts
- Extract fetchWithTimeout to reduce duplication in fetchJson/postJson
- Add wasmPath option to deploy_sc (reads file server-side)
- Add caller field to query_sc and VMQueryRequest
- Add log() alias for console.error with comment explaining MCP stderr
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Validate .wasm extension and enforce 10 MB max file size for wasmPath - Fix misleading JSDoc on getTransaction (uses API proxy, not node)
Summary
get_balance,get_account,get_asset_info,query_sc,get_transaction,get_block,list_validators— available in all profiles (including public MCP)send_transfer,deploy_sc,invoke_sc,freeze_klv— local profile only, builds unsigned transactions for external signingsrc/chain/): zero-dependency HTTP client using nativefetch(), supports mainnet/testnet/devnet/local with per-call network overrideklever-sccrate version from 0.44.0 to 0.45.0 across all referencesDetails
Chain Client Architecture
KleverChainClientwith 11 methods wrapping Klever Node and Indexer REST APIsKLEVER_NETWORK,KLEVER_NODE_URL,KLEVER_API_URL,KLEVER_TIMEOUT)MCP Tool Security
readOnlyHint,idempotentHint) for safe auto-approvalthis.profile !== 'public')networkparameter (validated against enum)Tests
Test plan
pnpm testpasses all existing + new testspnpm run lintcleanpnpm run buildsucceedsMODE=mcp(public profile)