# mirofish-mcp-server

MCP (Model Context Protocol) server for [MiroFish](https://github.com/666ghj/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:

```bash
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`:

```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

```bash
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):

```json
{
  "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`:

```json
"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

```bash
# 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