MiroFish MCP
by umar551869
README.md
<div align="center">
<img src="./static/image/MiroFish_logo_compressed.jpeg" alt="MiroFish Logo" width="75%"/>
<a href="https://trendshift.io/repositories/16144" target="_blank"><img src="https://trendshift.io/api/badge/repositories/16144" alt="666ghj%2FMiroFish | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
简洁通用的群体智能引擎，预测万物
</br>
<em>A Simple and Universal Swarm Intelligence Engine, Predicting Anything</em>
<a href="https://www.shanda.com/" target="_blank"><img src="./static/image/shanda_logo.png" alt="666ghj%2FMiroFish | Shanda" height="40"/></a>
[](https://github.com/666ghj/MiroFish/stargazers)
[](https://github.com/666ghj/MiroFish/watchers)
[](https://github.com/666ghj/MiroFish/network)
[](https://hub.docker.com/)
[](https://deepwiki.com/666ghj/MiroFish)
[](http://discord.gg/ePf5aPaHnA)
[](https://x.com/mirofish_ai)
[](https://www.instagram.com/mirofish_ai/)
[English](./README.md) | [中文文档](./README-ZH.md)
</div>
---
## 🔌 This is a fork: MiroFish as an agent-native MCP server
This repository is a fork of **[666ghj/MiroFish](https://github.com/666ghj/MiroFish)**.
The simulation engine, backend, frontend and research behind it are the work of
the original MiroFish team — this fork does not change any of it.
What this fork adds is an **integration layer** that turns MiroFish from a web
application you operate by hand into an engine your AI assistant can drive
directly, running entirely on your own machine.
### What it unlocks
| Upstream MiroFish | This fork |
|---|---|
| Drive the engine through its web UI | Also drive it in plain language from Claude, Codex, Cursor, Grok, or any MCP client |
| Start the Flask backend, click through four stages | Ask once — the agent sequences ontology → graph → simulation → report for you |
| Read the report in the browser | Interrogate the running simulation and the finished report conversationally |
| Set up Python, deps and keys by hand | `python scripts/bootstrap.py` provisions everything, including a correct Python |
Concretely, you can now say *"simulate how students react to this tuition
policy, then tell me the three most likely outcomes"* and have an agent carry
out the whole pipeline.
### How to use it
**Give [START_HERE.md](./START_HERE.md) to your AI agent.** It contains a single
prompt to paste; the agent sets everything up and tells you what it needs from
you.
Then read **[user_guide.md](./user_guide.md)** — what to ask for, how to
interview agents mid-run, how to control cost, and the process-lifetime
behaviour that catches people out. [`docs/AGENT_SETUP.md`](./docs/AGENT_SETUP.md)
has the per-client configuration details.
### What was added
| Addition | Purpose |
|---|---|
| [`scripts/mirofish_mcp.py`](./scripts/mirofish_mcp.py) | MCP server exposing the engine as 9 tools |
| [`scripts/bootstrap.py`](./scripts/bootstrap.py) | One-command setup; `--doctor` tests your LLM and Zep keys for real |
| [`scripts/cli_client.py`](./scripts/cli_client.py) | Command-line client for the same pipeline |
| [`user_guide.md`](./user_guide.md) | How to use the tools day to day |
| [`skills/mirofish-simulator/`](./skills/mirofish-simulator/) | Agent skill: stage ordering, cost control, failure modes |
| [`START_HERE.md`](./START_HERE.md) · [`AGENTS.md`](./AGENTS.md) · [`docs/`](./docs/) | Setup prompt and per-client documentation |
The nine MCP tools cover project and ontology creation, graph building, task
polling, persona synthesis and simulation launch, live status, mid-run agent
interviews, stopping a run, report generation, and follow-up Q&A against the
simulation graph.
### Notes
- **Requires Python 3.11 or 3.12** (`backend/pyproject.toml` pins `>=3.11,<3.13`).
The bootstrap fetches a suitable interpreter via [`uv`](https://docs.astral.sh/uv/)
if you do not have one — no admin rights needed.
- **You supply your own API keys.** An OpenAI-compatible LLM endpoint and a
[Zep](https://app.getzep.com/) key, both in `.env`. Nothing is bundled.
- **Simulations cost money.** Every agent makes LLM calls every round, so cost
scales with personas × rounds. Start small.
- **Licence:** MiroFish is AGPL-3.0 and this fork remains so. If you run a
modified version as a network service, you must offer its source.
Everything below this point is the original project's documentation.
---
## ⚡ Overview
**MiroFish** is a next-generation AI prediction engine powered by multi-agent technology. By extracting seed information from the real world (such as breaking news, policy drafts, or financial signals), it automatically constructs a high-fidelity parallel digital world. Within this space, thousands of intelligent agents with independent personalities, long-term memory, and behavioral logic freely interact and undergo social evolution. You can inject variables dynamically from a "God's-eye view" to precisely deduce future trajectories — **rehearse the future in a digital sandbox, and win decisions after countless simulations**.
> You only need to: Upload seed materials (data analysis reports or interesting novel stories) and describe your prediction requirements in natural language</br>
> MiroFish will return: A detailed prediction report and a deeply interactive high-fidelity digital world
### Our Vision
MiroFish is dedicated to creating a swarm intelligence mirror that maps reality. By capturing the collective emergence triggered by individual interactions, we break through the limitations of traditional prediction:
- **At the Macro Level**: We are a rehearsal laboratory for decision-makers, allowing policies and public relations to be tested at zero risk
- **At the Micro Level**: We are a creative sandbox for individual users — whether deducing novel endings or exploring imaginative scenarios, everything can be fun, playful, and accessible
From serious predictions to playful simulations, we let every "what if" see its outcome, making it possible to predict anything.
## 🌐 Live Demo
Welcome to visit our online demo environment and experience a prediction simulation on trending public opinion events we've prepared for you: [mirofish-live-demo](https://666ghj.github.io/mirofish-demo/)
## 📸 Screenshots
<div align="center">
<table>
<tr>
<td><img src="./static/image/Screenshot/运行截图1.png" alt="Screenshot 1" width="100%"/></td>
<td><img src="./static/image/Screenshot/运行截图2.png" alt="Screenshot 2" width="100%"/></td>
</tr>
<tr>
<td><img src="./static/image/Screenshot/运行截图3.png" alt="Screenshot 3" width="100%"/></td>
<td><img src="./static/image/Screenshot/运行截图4.png" alt="Screenshot 4" width="100%"/></td>
</tr>
<tr>
<td><img src="./static/image/Screenshot/运行截图5.png" alt="Screenshot 5" width="100%"/></td>
<td><img src="./static/image/Screenshot/运行截图6.png" alt="Screenshot 6" width="100%"/></td>
</tr>
</table>
</div>
## 🎬 Demo Videos
### 1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction
<div align="center">
<a href="https://www.bilibili.com/video/BV1VYBsBHEMY/" target="_blank"><img src="./static/image/武大模拟演示封面.png" alt="MiroFish Demo Video" width="75%"/></a>
Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"
</div>
### 2. Dream of the Red Chamber Lost Ending Simulation
<div align="center">
<a href="https://www.bilibili.com/video/BV1cPk3BBExq" target="_blank"><img src="./static/image/红楼梦模拟推演封面.jpg" alt="MiroFish Demo Video" width="75%"/></a>
Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"
</div>
> **Financial Prediction**, **Political News Prediction** and more examples coming soon...
## 🔄 Workflow
1. **Graph Building**: Seed extraction & Individual/collective memory injection & GraphRAG construction
2. **Environment Setup**: Entity relationship extraction & Persona generation & Agent configuration injection
3. **Simulation**: Dual-platform parallel simulation & Auto-parse prediction requirements & Dynamic temporal memory updates
4. **Report Generation**: ReportAgent with rich toolset for deep interaction with post-simulation environment
5. **Deep Interaction**: Chat with any agent in the simulated world & Interact with ReportAgent
## 🚀 Quick Start
### Option 1: Source Code Deployment (Recommended)
#### Prerequisites
| Tool | Version | Description | Check Installation |
|------|---------|-------------|-------------------|
| **Node.js** | 18+ | Frontend runtime, includes npm | `node -v` |
| **Python** | ≥3.11, ≤3.12 | Backend runtime | `python --version` |
| **uv** | Latest | Python package manager | `uv --version` |
#### 1. Configure Environment Variables
```bash
# Copy the example configuration file
cp .env.example .env
# Edit the .env file and fill in the required API keys
```
**Required Environment Variables:**
```env
# LLM API Configuration (supports any LLM API with OpenAI SDK format)
# Recommended: Alibaba Qwen-plus model via Bailian Platform: https://bailian.console.aliyun.com/
# High consumption, try simulations with fewer than 40 rounds first
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud Configuration
# Free monthly quota is sufficient for simple usage: https://app.getzep.com/
ZEP_API_KEY=your_zep_api_key
```
#### 2. Install Dependencies
```bash
# One-click installation of all dependencies (root + frontend + backend)
npm run setup:all
```
Or install step by step:
```bash
# Install Node dependencies (root + frontend)
npm run setup
# Install Python dependencies (backend, auto-creates virtual environment)
npm run setup:backend
```
#### 3. Start Services
```bash
# Start both frontend and backend (run from project root)
npm run dev
```
**Service URLs:**
- Frontend: `http://localhost:3000`
- Backend API: `http://localhost:5001`
**Start Individually:**
```bash
npm run backend # Start backend only
npm run frontend # Start frontend only
```
### Option 2: Docker Deployment
```bash
# 1. Configure environment variables (same as source deployment)
cp .env.example .env
# 2. Pull image and start
docker compose up -d
```
Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001 (backend)`
> Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
## 📬 Join the Conversation
<div align="center">
<img src="./static/image/QQ群.png" alt="QQ Group" width="60%"/>
</div>
The MiroFish team is recruiting full-time/internship positions. If you're interested in multi-agent simulation and LLM applications, feel free to send your resume to: **mirofish@shanda.com**
## 📄 Acknowledgments
**MiroFish has received strategic support and incubation from Shanda Group!**
MiroFish's simulation engine is powered by **[OASIS (Open Agent Social Interaction Simulations)](https://github.com/camel-ai/oasis)**, We sincerely thank the CAMEL-AI team for their open-source contributions!
## 📈 Project Statistics
<a href="https://github.com/666ghj/MiroFish">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="static/image/star-history-dark.svg" />
<source media="(prefers-color-scheme: light)" srcset="static/image/star-history-light.svg" />
<img alt="666ghj/MiroFish Star History Chart" src="static/image/star-history-light.svg" />
</picture>
</a>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues