Hyperledger Fabric Agent Suite

What is hlf-fabric-agent?

hlf-fabric-agent is a modular toolkit designed for managing Hyperledger Fabric test networks and their chaincode lifecycle. It comprises two main components: hlf-controller, a Go-based REST API for network and chaincode operations, and hlf-mcp, a Python-based MCP tool for automation, scripting, and integration with AI models like those in Cursor or Claude Desktop.

How to use hlf-fabric-agent?

To use hlf-fabric-agent, first clone the repository. Then, set up and run the hlf-controller (Go REST API) by navigating to its directory and executing go run main.go. The first run will automatically download and configure Hyperledger Fabric binaries and samples. The API will be available at http://localhost:8081. Next, set up hlf-mcp (Python MCP Tool) by navigating to its directory and installing dependencies with pip install httpx. For integration with AI tools like Cursor or Claude Desktop, you need to add specific JSON configurations to their respective configuration files, pointing to the hlf-mcp tool.

Key Features of hlf-fabric-agent

• Automated Fabric Setup: The hlf-controller automatically downloads and configures Hyperledger Fabric binaries and samples on first run.
• Dynamic Configuration: Easily configure the entire Fabric network topology via a central config.yaml file.
• Full Lifecycle Management: Bring up/down the network, create channels, deploy, invoke, and query chaincode via a simple REST API.
• Agent-Ready: The hlf-mcp tool allows LLMs (like those in Cursor or Claude Desktop) to interact with your Fabric network seamlessly.

Use Cases of hlf-fabric-agent

• Automated Testing: Setting up and tearing down Hyperledger Fabric test networks for automated testing of chaincode.
• Development Environments: Quickly provisioning and managing local Hyperledger Fabric development environments.
• AI-driven Blockchain Interaction: Enabling AI models to interact with and manage Hyperledger Fabric networks for various applications.
• Scripting and Automation: Automating complex Hyperledger Fabric operations through scripting with hlf-mcp.

FAQ about hlf-fabric-agent

Q: What are the prerequisites for running hlf-fabric-agent? A: You need Go (1.18+), Python (3.9+), and pip (for Python dependencies).

Q: How do I configure the hlf-controller? A: The hlf-controller is configured via the hlf-controller/config.yaml file, where you define your network topology.

Q: Can I integrate hlf-fabric-agent with AI models? A: Yes, the hlf-mcp tool is designed to allow LLMs like those in Cursor or Claude Desktop to interact with your Fabric network seamlessly through specific JSON configurations.

Q: Where does the hlf-controller download Fabric samples? A: The hlf-controller downloads fabric-samples to your home directory if they are missing during the first run.

Q: What is the default API base URL for the hlf-controller? A: The default API base URL for the hlf-controller is http://localhost:8081.

Hyperledger Fabric Agent Suite

https://github.com/user-attachments/assets/75c3414a-3901-42ff-bf33-8f57b0ca96b4

Works for test-network.

A modular toolkit for managing Hyperledger Fabric test networks and chaincode lifecycle, featuring:

• hlf-controller: A Go-based REST API for network and chaincode operations.
• hlf-mcp: A Python-based MCP tool for automation, scripting, and agent integration.

---

Features

• Automated Fabric Setup: The hlf-controller automatically downloads and configures Hyperledger Fabric binaries and samples on first run.
• Dynamic Configuration: Easily configure the entire Fabric network topology via a central config.yaml file.
• Full Lifecycle Management: Bring up/down the network, create channels, deploy, invoke, and query chaincode via a simple REST API.
• Agent-Ready: The hlf-mcp tool allows LLMs (like those in Cursor or Claude Desktop) to interact with your Fabric network seamlessly.

---

Prerequisites

• Go (1.18+)
• Python (3.9+)
• pip (for Python dependencies)

---

Setup Instructions

1. Clone the Repo

git clone <your-repo-url>
cd <repo-root>

2. Set Up and Run hlf-controller (Go REST API)

The controller handles its own prerequisites.

cd hlf-controller
go run main.go

• The first time you run this, it will check for fabric-samples and download them to your home directory if they are missing. The server will not start until this process is complete.
• The API will then be available at http://localhost:8081.

3. Set Up hlf-mcp (Python MCP Tool)

cd ../hlf-mcp
pip install httpx
# (Optional) Install any other agent/MCP dependencies

---

Configuration

hlf-controller

The Go controller is configured via the hlf-controller/config.yaml file. This is the primary way to define your network topology, including peer/orderer details, certificate paths, and timeouts.

Environment Variables

• HLF_CONFIG_PATH: Path to a custom config.yaml file for the controller.
• HLF_NETWORK_SCRIPT_PATH: Overrides the path to your Fabric network.sh. If not set, the path from config.yaml is used, which in turn defaults to ~/fabric-samples/test-network/network.sh.
• HLF_API_BASE: Base URL for the hlf-controller API (used by hlf-mcp, defaults to http://localhost:8081).

---

How to Use

Integration

• Cursor: Add the hlf-mcp tool to your ~/.cursor/mcp.json (see hlf-mcp/README.md).
• Claude Desktop: Add to claude_desktop_config.json (see hlf-mcp/README.md).

---

Example JSON Configurations for Integration

Cursor (~/.cursor/mcp.json)

Add the following entry to your ~/.cursor/mcp.json file to integrate the MCP tool with Cursor:

"hlf-controller": {
    "command": "uv",
    "args": [
        "--directory",
        "/Users/padamarajkore/Desktop/hlf-mcp", //change it to your local path for hlf-mcp folder
        "run",
        "mcp_hlf_tool.py"
    ]
}

Claude Desktop (claude_desktop_config.json)

Add the following entry to your claude_desktop_config.json file (usually found in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

"hlf-controller": {
    "command": "/Users/padamarajkore/.local/bin/uv", //change it to your local path for uv binary
    "args": [
        "--directory",
        "/Users/padamarajkore/Desktop/hlf-mcp", //change it to your local path for hlf-mcp folder
        "run",
        "mcp_hlf_tool.py"
    ]
}

Note:

• Adjust the --directory and script name to match the actual location and filename of your MCP tool.
• Adjust the path to the uv command if it is installed elsewhere on your system.
• Place these entries inside the top-level JSON object, alongside your other tool definitions.

---

Project Structure

.
├── hlf-controller/        # Go REST API server with its own config.yaml
├── hlf-mcp/               # Python MCP tool
├── README.md              # This file

---

License

MIT