heurist-agent-framework

The Heurist Agent Framework is a modular platform designed to run AI agents that can operate across multiple interfaces (Telegram, Discord, Twitter, Farcaster, REST API, and MCP). It provides a core agent architecture with pluggable interfaces, a knowledge base backed by PostgreSQL or SQLite, and a suite of tools and workflows that enable RAG, chain-of-thought reasoning, and external tool integration. The MCP integration allows you to expose agent capabilities as MCP endpoints so clients like Claude, ChatGPT, or LangChain can orchestrate complex agent workflows through a consistent MCP protocol. You can connect to the mesh ecosystem to access 30+ specialized Web3 agents and compose them into powerful MCP-powered workflows.

Prerequisites:

• Node.js and npm installed (for MCP client/server tooling).
• Optional Python environment if you plan to use Python-based components.
• Docker (optional) if you prefer containerized deployment.

1. Clone the repository (or prepare your environment referencing the MCP server for Heurist agents): git clone https://github.com/heurist-network/heurist-agent-framework.git cd heurist-agent-framework

2. Install dependencies (Node.js-based components): npm install

3. Configure environment variables (example):

   • HEURIST_API_KEY: your Heurist API key
   • DATABASE_URL: your Postgres or SQLite connection string
   • LOG_LEVEL: info|debug|warn|error

4. Run the development server (Node.js-based interface): npm run dev

5. If you plan to expose MCP endpoints via npx-based tooling, ensure your environment has access to the MCP server tooling and run the configured command from mcp_config (see the repository's MCP integration guide for exact usage). Source code and MCP server references are available under the Heurist Mesh ecosystem if you want to deploy dedicated MCP servers for specific mesh agents.

6. Optional: Docker deployment

   • Build and run a container with your environment variables and database URL. See Dockerfile and docker-compose configuration in the repository (adjust image names as needed).

7. Verify connectivity

   • Access the REST/MCP endpoints as defined by your configuration and test with a simple prompt to validate workflow execution.

Tips and common considerations:

• The framework supports multiple interfaces; ensure your chosen interfaces are wired up in the configuration and have the necessary credentials (e.g., Telegram/Discord tokens).
• For MCP usage, keep track of rate limits and API keys used by mesh agents to avoid throttling.
• Use the provided KnowledgeProvider and Vector Storage options (PostgreSQL or SQLite) to enable fast retrieval during RAG workflows.
• If you encounter environment variable issues, verify the runtime user has permission to access the database and any external APIs.
• When integrating external tools through MCP, ensure tool schemas and endpoint contracts match the expected MCP tool interface definitions.
• Review the Mesh documentation for best practices on composing agents and reusing MCP endpoints across projects.