Heurist Mesh Agent MCP Server Smart Contract Security

Overview

The Heurist Mesh Agent MCP Server provides a local or hosted endpoint for running Heurist Mesh AI agents that assist with smart contract security, blockchain analysis, token metrics, and automated on‑chain interactions. It implements the Model Context Protocol (MCP) to let clients supply context, select agent tools, and receive structured responses from models that are augmented with on‑chain data and analysis tools.

This server is useful when you want repeatable, tool‑enabled analyses of blockchain assets and smart contracts — for example, running automated vulnerability scans, producing token health reports, or orchestrating multi‑step on‑chain investigations. It is designed for developers who need to integrate AI agents into tooling pipelines, dashboards, or monitoring systems while retaining control over API keys, node endpoints, and agent tooling.

Features

• MCP-compatible server for hosting Heurist Mesh AI agents
• Built-in tools for smart contract analysis, transaction tracing, token metrics, and on‑chain queries
• Extensible tool/plugin model so you can add custom connectors (e.g., specialized RPCs, forensic tools)
• Support for both HTTP and WebSocket MCP transports
• Works with major LLM providers via standard API keys (configured in env)
• Dockerfile and standard Node.js start workflow for local and production deployment
• Simple JSON API for programmatic integration into CI/CD, monitoring, and analytics pipelines

Installation / Configuration

Prerequisites: Node.js (16+), Git, and an RPC provider (Infura/Alchemy/Ankr) or self‑hosted node. Optional: Docker.

Clone and install:

git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server
npm ci

Create a .env file with required configuration (example below). Then start:

# start in development
npm start

# production build & start
npm run build
npm run start:prod

Run with Docker:

docker build -t heurist-mesh-mcp-server .
docker run -d --name heurist-mcp \
  --env-file .env \
  -p 3000:3000 \
  heurist-mesh-mcp-server

Example .env:

PORT=3000
HOST=0.0.0.0
OPENAI_API_KEY=sk-...
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/your-key
MONGO_URL=mongodb://localhost:27017/heurist
LOG_LEVEL=info

Configuration table

Available Tools / Resources

The server comes with an extensible toolset oriented to blockchain and smart contract work. Typical built-in tools include:

• solidity_static_analysis — static code scanning and vulnerability detection
• trace_transactions — trace and decode transaction execution and internal calls
• token_scoring — compute token metrics (liquidity, holder distribution, rug risk)
• onchain_query — generic RPC helper for balance, logs, events
• price_history — fetch historical price series from integrated pricing sources
• tx_executor (optional) — helper to assemble and sign transactions (use with caution)

You can add or modify tools in the repository’s tools/ directory. Each tool exposes a small manifest describing name, inputs, outputs and required permissions. Restart the server after adding tools.

API Usage Examples

Simple HTTP POST to the MCP endpoint (example for a solidity audit request):

curl -X POST "http://localhost:3000/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-123",
    "type": "mcp.request",
    "payload": {
      "agent": "heurist-smart-audit",
      "context": {
        "source": "https://raw.githubusercontent.com/example/contract.sol",
        "chain": "ethereum:mainnet"
      },
      "tools": ["solidity_static_analysis", "trace_transactions"]
    }
  }'

WebSocket example (Node.js) to open an MCP session:

import WebSocket from "ws";

const ws = new WebSocket("ws://localhost:3000/mcp/ws");

ws.on("open", () => {
  const msg = {
    id: "ws-1",
    type: "mcp.session.start",
    payload: { agent: "heurist-smart-audit" }
  };
  ws.send(JSON.stringify(msg));
});

ws.on("message", (data) => {
  console.log("mcp:", data.toString());
});

Responses follow MCP message shapes (status updates, tool calls, final answer). Inspect logs when debugging tool failures.

Use Cases

• Smart contract audit automation: Given a contract source or bytecode, run static analysis, fetch related transactions, and produce a vulnerability report with severity and remediation steps.
• Token health and monitoring: Periodically compute token metrics (liquidity, holder concentration, recent large transfers) and surface alerts if thresholds are crossed.
• On‑chain forensic investigation: Trace suspicious transfers across contracts and wallets, decode method calls, and assemble a narrative of funds flow with linked evidence.
• Assisted developer workflows: Integrate the MCP server into CI so pull requests that change smart contracts automatically run agent‑driven checks and attach results to PRs.
• Transaction orchestration: Use a guarded tx_executor tool to build and simulate multi‑step interactions (e.g., batch swaps) before signing and broadcasting.

Extending and Security Notes

• Add tools under tools/ and declare input/output contracts; the server will call tools as subprocesses or internal modules depending on configuration.
• Keep sensitive keys (RPC, LLM) in protected secret stores; avoid committing .env to VCS.
• Review and restrict any tx_executor or signing tools — automatic signing should be limited and audited.
• Use rate limiting and network isolation when exposing the MCP server in production.

For source, issues, and contribution guidelines, see the repository: https://github.com/heurist-network/heurist-mesh-mcp-server.