mirofish-mcp-server

MCP (Model Context Protocol) server for MiroFish — the AI-powered multi-agent prediction engine. Connect Claude Code (or any MCP-compatible AI client) directly to your local MiroFish instance.

---

What this does

MiroFish lets you upload documents, build a knowledge graph, spin up thousands of autonomous AI agents, and simulate future scenarios. This MCP server exposes all of that as tools Claude can call directly from a conversation.

┌─────────────┐     stdio      ┌───────────────────┐     HTTP      ┌──────────────────┐
│ Claude Code  │ ◄────────────► │ mirofish-mcp-     │ ────────────► │ MiroFish Backend │
│              │                │ server (Node.js)  │               │ (Flask on :5001) │
└─────────────┘                └───────────────────┘               └──────────────────┘

---

Prerequisites

1. Node.js 18+
2. MiroFish running locally — clone and start it first:

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
npm run setup:all
npm run dev            # starts backend at http://localhost:5001

Using Claude as MiroFish's LLM — MiroFish accepts any OpenAI-compatible API. To use Claude, set these in your MiroFish .env:

LLM_API_KEY=sk-ant-api03-...          # your Anthropic API key
LLM_BASE_URL=https://api.anthropic.com/v1
LLM_MODEL_NAME=claude-sonnet-4-6
ZEP_API_KEY=...                        # still required for the knowledge graph

MiroFish's LLM client passes base_url directly to the OpenAI SDK, so Claude handles all internal AI work — ontology extraction, agent profiling, simulation decisions, report generation — with no code changes.

---

Installation

git clone https://github.com/thisisaman408/mirofish-mcp-server.git
cd mirofish-mcp-server
npm install
npm run build

---

Connect to Claude Code

Create a .mcp.json file in the directory where you run Claude Code (or your project root):

{
  "mcpServers": {
    "mirofish": {
      "command": "node",
      "args": ["/absolute/path/to/mirofish-mcp-server/dist/index.js"],
      "env": {
        "MIROFISH_BASE_URL": "http://localhost:5001"
      }
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned this repo. Then restart Claude Code — the MiroFish tools will appear automatically.

Custom backend URL

If MiroFish runs on a different host or port, change MIROFISH_BASE_URL:

"env": {
  "MIROFISH_BASE_URL": "http://192.168.1.10:5001"
}

---

Available Tools (40 total)

Health

Tool	Description
mirofish_health_check	Check if the MiroFish backend is running

Projects

Tool	Description
mirofish_list_projects	List all projects
mirofish_get_project	Get project details by ID
mirofish_delete_project	Delete a project
mirofish_reset_project	Reset project state to rebuild graph

Knowledge Graph

Tool	Description
mirofish_generate_ontology	Upload documents and generate entity/edge ontology
mirofish_build_graph	Build a Zep knowledge graph from a project (async)
mirofish_get_graph_data	Get all nodes and edges from a graph
mirofish_delete_graph	Delete a graph

Tasks

Tool	Description
mirofish_get_task	Poll an async task's progress
mirofish_list_tasks	List all background tasks

Simulation

Tool	Description
mirofish_create_simulation	Create a new simulation from a project
mirofish_prepare_simulation	Generate agent profiles + config (async)
mirofish_prepare_status	Check preparation progress
mirofish_start_simulation	Start running the simulation
mirofish_stop_simulation	Stop a running simulation
mirofish_get_simulation	Get simulation details and status
mirofish_list_simulations	List all simulations
mirofish_simulation_run_status	Get real-time run status
mirofish_simulation_run_status_detail	Get detailed round/agent progress
mirofish_get_simulation_profiles	Get generated agent profiles
mirofish_get_simulation_config	Get simulation config
mirofish_simulation_history	Get history of all simulations

Simulation Results

Tool	Description
mirofish_get_entities	Get all entities from the knowledge graph
mirofish_get_entity_detail	Get a specific entity's context
mirofish_get_entities_by_type	Get entities filtered by type
mirofish_get_simulation_actions	Get all agent actions during the run
mirofish_get_simulation_timeline	Get chronological event timeline
mirofish_get_agent_stats	Get agent behavior statistics
mirofish_get_simulation_posts	Get posts generated by agents
mirofish_get_simulation_comments	Get comments/replies generated by agents

Interview

Tool	Description
mirofish_interview_agent	Chat with a specific simulated agent
mirofish_interview_batch	Ask multiple agents the same question
mirofish_interview_all	Ask all agents a question
mirofish_interview_history	Get conversation history with an agent

Reports

Tool	Description
mirofish_generate_report	Generate prediction report (async)
mirofish_report_generate_status	Check report generation progress
mirofish_get_report	Get full report content
mirofish_get_report_by_simulation	Get report by simulation ID
mirofish_list_reports	List all reports
mirofish_delete_report	Delete a report
mirofish_get_report_progress	Real-time section-by-section progress
mirofish_get_report_sections	Get all completed sections
mirofish_get_report_section	Get a single section by index
mirofish_check_report_status	Check if a simulation has a report
mirofish_chat_with_report_agent	Chat with the AI Report Agent about results

Debug Tools

Tool	Description
mirofish_search_graph	Semantic search over the knowledge graph
mirofish_graph_statistics	Get node/edge counts and entity distribution
mirofish_env_status	Check simulation environment status
mirofish_close_env	Shut down a simulation environment

---

Example conversation with Claude

Once connected, you can talk to Claude naturally:

"List my MiroFish projects"

"Create a simulation about public opinion on climate policy using project proj_abc123"

"Interview agent Li Wei — ask her what she thinks about the new carbon tax"

"Generate a prediction report for simulation sim_xyz789 and show me the executive summary"

"Search the knowledge graph for anything about social media sentiment"

---

Workflow

The typical end-to-end flow in MiroFish:

1. Generate ontology   →  mirofish_generate_ontology  (upload docs)
2. Build graph         →  mirofish_build_graph         (async, poll with get_task)
3. Create simulation   →  mirofish_create_simulation
4. Prepare simulation  →  mirofish_prepare_simulation  (async, generates agent profiles)
5. Start simulation    →  mirofish_start_simulation
6. Monitor / results   →  get_posts, get_actions, get_timeline
7. Generate report     →  mirofish_generate_report     (async)
8. Interview agents    →  mirofish_interview_agent
9. Chat about results  →  mirofish_chat_with_report_agent

---

Development

# Edit src/index.ts, then rebuild
npm run build

# Run directly (requires MiroFish backend)
node dist/index.js

The server uses stdio transport — Claude Code launches it as a subprocess and communicates over stdin/stdout.

---

License

MIT