🧠 ForgeMind

MCP-native multi-agent AI platform — tools, approvals, traces, evals

Give it a goal. Planner thinks, Executor acts through MCP tools, Critic verifies — with human approvals and full traces.

Why ForgeMind

2026's AI stack is agents + MCP + evals. ForgeMind is a complete, runnable reference implementation of that stack:

• 🔌 MCP-native — every tool is exposed as MCP (tools/list, tools/call over HTTP + stdio); consume any external MCP server too
• 🤝 Human-in-the-loop — auto, confirm_tools, confirm_all approval modes for risky tools
• 🔍 Execution traces — every run saved as replayable JSON; inspect via CLI, API, or dashboard
• 📊 Eval harness — built-in suite with pass-rate reports; add your own cases in one file
• 🖥️ Live dashboard — run goals, watch WebSocket events, browse tools and traces
• 🧠 Any model — Ollama (free/local), llama.cpp GGUF, or any OpenAI-compatible API

Architecture

Goal → Coordinator (ReAct loop)
         ├── PlannerAgent   → thought + tool_calls (JSON)
         ├── ApprovalGate   → auto / confirm_tools / confirm_all
         ├── ExecutorAgent  → ToolRegistry.execute()
         │                     ├── builtin: calculator, time, echo, word_count
         │                     └── risky: write_file, run_shell, http_request
         ├── CriticAgent    → accept / reject final answer
         └── Tracer         → .forgemind/traces/<run_id>.json

Interfaces: CLI · FastAPI (/v1/runs, /v1/tools, /v1/approvals, /v1/traces)
            MCP endpoint (/v1/mcp) · WebSocket (/v1/stream) · Dashboard (/dashboard)

Quick Start

pip install -e ".[dev]"

# Needs a model backend — Ollama is free and local:
ollama pull qwen2.5-coder:7b

# Run a goal
forgemind run "What is (12 + 8) * 3? Reply with just the number."

# Start the API + dashboard
forgemind serve
# → http://127.0.0.1:8080/dashboard

# Run evals
forgemind evaluate

API Examples

# Start a run
curl -X POST localhost:8080/v1/runs \
  -H "Content-Type: application/json" \
  -d '{"goal": "Echo back exactly: hello-forge", "max_steps": 8}'

# List tools (MCP)
curl localhost:8080/v1/tools

# Call a tool via MCP
curl -X POST localhost:8080/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"calculator","arguments":{"expression":"3*7"}}}'

# Pending approvals for a run
curl localhost:8080/v1/approvals/<run_id>

Docker

docker compose up --build
# API on :8080, data in the forgemind-data volume

CLI Reference

Command	Purpose
forgemind run "<goal>"	Execute one goal end to end
forgemind serve	Start API + dashboard
forgemind evaluate	Run eval suite, print Markdown report
forgemind tools	List registered MCP tools
forgemind trace <run_id>	Print a stored trace

Env vars: FORGEMIND_BACKEND, FORGEMIND_MODEL, FORGEMIND_API_KEY, FORGEMIND_APPROVALS, FORGEMIND_MAX_STEPS, FORGEMIND_PORT.

License

MIT — see LICENSE

Built by Kamalesh