starkshield-mcp

Starkzap-powered Model Context Protocol server: Starknet wallet operations, deterministic quantum risk scanning, Vesu lending, staking, swaps (AVNU), and Tongo confidential transfers.

Install

npm install -g starkshield-mcp

Or run from source:

cd starkshield-mcp
npm install
npm run build
node dist/index.js

Configure

See repository root .env.example (or set variables in your MCP host).

• Dev signer: STARKNET_PRIVATE_KEY
• Privy: PRIVY_WALLET_ID, PRIVY_PUBLIC_KEY, PRIVY_SIGN_URL
• Network: STARKNET_NETWORK=mainnet|sepolia
• Paymaster (optional): AVNU_API_KEY
• Tongo (optional): TONGO_PRIVATE_KEY, TONGO_CONTRACT
• Automation (dangerous): STARKSHIELD_AUTO_CONFIRM=1 skips preview/confirm for destructive tools
• HTTP transport (optional): STARKSHIELD_HTTP_PORT=8787 — serves MCP on POST /mcp and GET /status

Claude Desktop

{
  "mcpServers": {
    "starkshield": {
      "command": "npx",
      "args": ["-y", "starkshield-mcp"],
      "env": {
        "STARKNET_NETWORK": "mainnet",
        "STARKNET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Quantum safety

quantum_risk_scan combines fixed cryptographic architecture facts (no LLM inference inside the tool) with optional Starknet JSON-RPC checks (contract deployment, address nonce). The assistant should explain the structured JSON, not invent new risk levels.

Core health tools

• server_health: returns runtime readiness (network, signer mode, confidential feature flags, transport mode).
• wallet_health: validates wallet connectivity and can optionally run deployment readiness checks.
• server_capabilities: returns full tool/resource catalog + environment guide.

These are useful first calls before destructive tools in both stdio and HTTP transport modes.

Capability resource

• URI: starkshield://meta/capabilities
• Includes:
  • runtime mode (network, signerMode, confidentialConfigured)
  • full tool catalog
  • resource catalog
  • env setup guide

Build phases (implementation checklist)

1. Phase 1 - Runtime health
   • Add server and wallet health tools.
   • Extend HTTP /status with runtime configuration signals.
2. Phase 2 - Capability discovery
   • Add server_capabilities tool.
   • Add starkshield://meta/capabilities resource.
   • Keep centralized tool/resource/env catalog.
3. Phase 3 - Packaging readiness
   • Ensure clean build scripts (build, check, clean).
   • Verify package files include only dist + docs.
   • Validate both stdio and HTTP modes before publish.
4. Phase 4 - Functional verification
   • Run MCP unit tests (npm run test:run).
   • Run full check (npm run check) before packaging.

Publish to npm

Run these steps from starkshield-mcp:

1. Authenticate npm
   • npm login
2. Clean + build
   • npm run clean
   • npm run build
   • npm run test:run
3. Sanity check package contents
   • npm pack --dry-run
4. Version bump
   • npm version patch (or minor / major)
5. Publish
   • npm publish --access public
6. Verify
   • npm view starkshield-mcp version
   • npx -y starkshield-mcp --help (or run in MCP host)

License

MIT