{"_id":"@bunland/somnia-mpc","_rev":"8-f241ee3fca2af90f92d1a02b98719b99","name":"@bunland/somnia-mpc","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.2":{"name":"@bunland/somnia-mpc","version":"1.0.2","license":"MIT","_id":"@bunland/somnia-mpc@1.0.2","maintainers":[{"name":"bunland","email":"vitalcode2022+bunland@gmail.com"}],"homepage":"https://github.com/vitalspace/somnia-mcp#readme","bugs":{"url":"https://github.com/vitalspace/somnia-mcp/issues"},"dist":{"shasum":"f620d81a2fb9a390055f2b23727d41d70db57231","tarball":"https://registry.npmjs.org/@bunland/somnia-mpc/-/somnia-mpc-1.0.2.tgz","fileCount":4,"integrity":"sha512-RUe6YrWM0TsXo2Gy2dLsiuqFXAnmoz7yr5AT7oDIZQQbf8bnblxcOU1UXxKRI2mHMwcj+vnZn8hyJOXif3qvrQ==","signatures":[{"sig":"MEUCIQDlPEoXBFFtuvCiDULtpDjXj9T2QfWgVtjGWdZKd3h16AIgEppUhQZrpk9g6ZRsdhCkx4Uh16Dqk4+FdT+O+FRQdMU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1172454},"main":"./dist/index.js","type":"module","module":"index.ts","gitHead":"6b1b04613359e3d2a53eb52216ee25ef505fe2ea","scripts":{"dev":"bun --watch run src/index.ts","test":"bun test","build":"bun build src/index.ts --outdir ./dist --target bun","start":"bun run src/index.ts"},"_npmUser":{"name":"bunland","email":"vitalcode2022+bunland@gmail.com"},"repository":{"url":"git+https://github.com/vitalspace/somnia-mcp.git","type":"git"},"_npmVersion":"11.5.2","description":"MCP Server for Somnia Blockchain","directories":{},"_nodeVersion":"23.3.0","dependencies":{"zod":"^3.24.1","viem":"^2.37.2","@modelcontextprotocol/sdk":"^1.17.5"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/somnia-mpc_1.0.2_1758154029467_0.5352616667302714","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@bunland/somnia-mpc","module":"index.ts","type":"module","version":"1.0.3","license":"MIT","repository":{"type":"git","url":"git+https://github.com/vitalspace/somnia-mcp.git"},"description":"MCP Server for Somnia Blockchain","main":"./dist/index.js","bin":{"somnia-mpc":"dist/index.js"},"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.5","viem":"^2.37.2","zod":"^3.24.1"},"scripts":{"start":"bun run src/index.ts","dev":"bun --watch run src/index.ts","build":"bun build src/index.ts --outdir ./dist --target bun","test":"bun test"},"_id":"@bunland/somnia-mpc@1.0.3","gitHead":"6b1b04613359e3d2a53eb52216ee25ef505fe2ea","bugs":{"url":"https://github.com/vitalspace/somnia-mcp/issues"},"homepage":"https://github.com/vitalspace/somnia-mcp#readme","_nodeVersion":"23.3.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-erExw8tVzA+nXWUoRU0y/iuskvJxPswbWNdl/HMib0Y9sWGL2n/pcgxxPKmxwI/7F/3CI2kWyXfi1JScehIY9w==","shasum":"ff060e0bb3d471f67befb75b1e8389d023be7a03","tarball":"https://registry.npmjs.org/@bunland/somnia-mpc/-/somnia-mpc-1.0.3.tgz","fileCount":4,"unpackedSize":1172506,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGebkh65SOILLPM/baVoYv49s3KcGhJM5d0fra9Hbey1AiEA0UbfWO6W17bbgTxUi3kSpcG63wW+oWfJJ1sepHiiaw0="}]},"_npmUser":{"name":"bunland","email":"vitalcode2022+bunland@gmail.com"},"directories":{},"maintainers":[{"name":"bunland","email":"vitalcode2022+bunland@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/somnia-mpc_1.0.3_1758154410686_0.7300285304548975"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-18T00:07:09.371Z","modified":"2025-09-18T00:13:31.193Z","1.0.0":"2025-09-17T23:57:19.478Z","1.0.1":"2025-09-18T00:06:06.250Z","1.0.2":"2025-09-18T00:07:09.783Z","1.0.3":"2025-09-18T00:13:30.950Z"},"bugs":{"url":"https://github.com/vitalspace/somnia-mcp/issues"},"license":"MIT","homepage":"https://github.com/vitalspace/somnia-mcp#readme","repository":{"type":"git","url":"git+https://github.com/vitalspace/somnia-mcp.git"},"description":"MCP Server for Somnia Blockchain","maintainers":[{"name":"bunland","email":"vitalcode2022+bunland@gmail.com"}],"readme":"# Somnia MCP Server\n\nA comprehensive Model Context Protocol (MCP) server for interacting with the Somnia blockchain network. This server provides a wide range of tools for blockchain operations including token transfers, contract interactions, transaction monitoring, and more.\n\n## Features\n\n- **Blockchain Information**: Get chain info, gas prices, fee data, and block information\n- **Token Operations**: Native token (SST/SOMI) and ERC20 token transfers and balance queries\n- **NFT Support**: ERC721 token information, ownership checking, and balance queries\n- **Contract Interactions**: Read/write smart contracts, deploy contracts, estimate gas\n- **Transaction Management**: Get transaction details, monitor confirmations, decode input data\n- **Batch Operations**: Multi-transfer capabilities for both native and ERC20 tokens\n- **Contract Verification**: Submit contracts for verification on blockchain explorers\n- **Analytics**: Transaction volume analysis, top holders identification\n- **Multicall Support**: Efficient batch contract calls using multicall3\n- **Network Support**: Somnia Mainnet and Testnet\n\n## Installation\n\n### Prerequisites\n\n- [Bun](https://bun.sh) runtime (v1.2.21 or later)\n- Node.js (for TypeScript compilation)\n- Private key for transaction operations (set as `PRIVATE_KEY` environment variable)\n\n### Install Dependencies\n\n```bash\nbun install\n```\n\n### Environment Setup\n\nCreate a `.env` file in the root directory:\n\n```env\nPRIVATE_KEY=your_private_key_here\n```\n\n**⚠️ Security Warning**: Never commit your private key to version control. Use environment variables or secure key management.\n\n## Usage\n\n### Development\n\n```bash\nbun run dev\n```\n\n### Production\n\n```bash\nbun run start\n```\n\n### Build\n\n```bash\nbun run build\n```\n\n### Testing\n\n```bash\nbun test\n```\n\n## Project Structure\n\n```\nsrc/\n├── index.ts              # Main entry point, MCP server initialization\n├── tools/\n│   └── tools.ts          # MCP tool definitions and handlers\n├── services/\n│   └── services.ts       # Core blockchain interaction logic\n├── lib/\n│   └── lib.ts            # Viem client creation utilities\n├── utils/\n│   └── utils.ts          # Utility functions (JSON formatting)\n└── constants/\n    └── constants.ts      # Chain configurations, ABIs, network constants\n```\n\n## Available Tools\n\n### Network & Chain Information\n- `get_chain_info` - Get information about Somnia networks\n- `get_gas_price` - Get current gas price\n- `get_fee_data` - Get complete fee data including base fee\n- `get_block_number` - Get block number by number or latest\n- `get_latest_block` - Get the most recent block\n\n### Account & Balance Operations\n- `get_balance` - Get SST/SOMI balance for an address\n- `get_erc20_balance` - Get ERC20 token balance\n- `get_nft_balance` - Get ERC721 token balance\n- `get_transaction_count` - Get transaction count (nonce) for an address\n\n### Token Operations\n- `transfer_native_token` - Transfer SST/SOMI tokens\n- `transfer_erc20_token` - Transfer ERC20 tokens\n- `get_token_info` - Get ERC20 token metadata\n- `batch_transfer_native` - Transfer SST/SOMI to multiple addresses\n- `batch_transfer_erc20` - Transfer ERC20 tokens to multiple addresses\n\n### NFT Operations\n- `get_nft_info` - Get ERC721 token information\n- `check_nft_ownership` - Verify NFT ownership\n- `get_nft_balance` - Get NFT balance for an address\n\n### Transaction Operations\n- `get_transaction` - Get transaction details by hash\n- `get_transaction_receipt` - Get transaction receipt\n- `get_address_transactions` - Get transaction history for an address\n- `get_pending_transactions` - Get pending transactions from mempool\n- `monitor_transaction` - Monitor transaction until confirmed\n- `send_raw_transaction` - Send signed raw transaction\n- `decode_transaction_input` - Decode transaction input data\n- `get_transaction_fee` - Calculate actual transaction fee\n\n### Contract Operations\n- `read_contract` - Read from smart contracts (view/pure functions)\n- `write_contract` - Write to smart contracts (state-changing functions)\n- `deploy_contract` - Deploy new smart contracts\n- `simulate_contract_call` - Simulate contract calls without execution\n- `estimate_gas` - Estimate gas for transactions\n- `estimate_contract_gas` - Estimate gas for contract function calls\n- `verify_contract` - Submit contracts for verification\n- `get_contract_source` - Get verified contract source code\n- `get_contract_bytecode` - Get contract bytecode\n- `get_contract_abi` - Get contract ABI\n- `get_contract_events` - Get historical contract events\n\n### Advanced Operations\n- `multicall_contract` - Execute multiple contract calls in one transaction\n- `multicall_contract_3` - Execute multiple calls with individual success status\n- `batch_write_contract` - Execute multiple contract write operations\n- `get_transaction_volume` - Calculate SST transaction volume for block range\n- `get_erc20_transaction_volume` - Calculate ERC20 transaction volume\n- `get_top_holders` - Get top SST/SOMI holders\n- `get_erc20_top_holders` - Get top ERC20 token holders\n- `is_contract` - Check if address is a smart contract\n\n## Network Support\n\n### Somnia Mainnet\n- Chain ID: 5031\n- Native Token: SOMI\n- RPC: https://api.infra.mainnet.somnia.network\n- Explorer: https://explorer.somnia.network\n\n### Somnia Testnet\n- Chain ID: 50312\n- Native Token: STT\n- RPC: https://dream-rpc.somnia.network\n- Explorer: https://shannon-explorer.somnia.network\n\n## Requirements\n\n- **Runtime**: Bun v1.2.21+\n- **TypeScript**: ^5.0.0\n- **Dependencies**:\n  - `@modelcontextprotocol/sdk`: ^1.17.5\n  - `viem`: ^2.37.2\n  - `zod`: ^3.24.1\n\n## Development\n\n### Code Style\n\n- TypeScript with strict type checking\n- ES modules\n- Async/await patterns\n- Error handling with try/catch blocks\n- Zod for input validation\n\n### Architecture\n\nThe server follows a layered architecture:\n\n1. **Tools Layer** (`tools.ts`): MCP tool definitions and request handling\n2. **Services Layer** (`services.ts`): Business logic and blockchain interactions\n3. **Library Layer** (`lib.ts`): Low-level client creation and utilities\n4. **Constants Layer** (`constants.ts`): Configuration and contract ABIs\n\n### Adding New Tools\n\n1. Define the tool in `tools.ts` using the MCP SDK\n2. Implement the business logic in `services.ts`\n3. Add any required constants or ABIs to `constants.ts`\n4. Update this README with the new tool description\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n```\nMIT License\n\nCopyright (c) 2025 Somnia MCP Project\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n---\n\n*This project was created using `bun init` in bun v1.2.21. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.*\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Disclaimer\n\nThis software is provided as-is. Always test thoroughly on testnet before mainnet deployment. Keep your private keys secure and never expose them in your code or logs.\n","readmeFilename":"README.md"}