128 lines
3.5 KiB
Markdown
128 lines
3.5 KiB
Markdown
# MiroFish Integration Stack
|
|
|
|
## Goal
|
|
|
|
Use **MiroFish** as the prediction engine and simulation brain, with:
|
|
|
|
- **Codex** as the builder and operator
|
|
- **Claude** as the reasoning and synthesis layer
|
|
- **n8n** as the automation layer
|
|
- **MCP** as the shared tool access layer
|
|
|
|
## Recommended Architecture
|
|
|
|
```text
|
|
Codex / Claude
|
|
|
|
|
v
|
|
MCP tools
|
|
|
|
|
v
|
|
MiroFish backend API
|
|
|
|
|
+--> graph build
|
|
+--> simulation lifecycle
|
|
+--> interviews with agents
|
|
+--> report generation and chat
|
|
|
|
|
v
|
|
MiroFish frontend
|
|
|
|
n8n
|
|
|
|
|
+--> calls MiroFish backend directly over HTTP
|
|
+--> or invokes the same lifecycle through the MCP server
|
|
```
|
|
|
|
## Roles
|
|
|
|
### Codex
|
|
|
|
- builds workflow glue, prompts, and wrappers
|
|
- drives MiroFish through MCP tools
|
|
- prepares projects, simulations, and reports
|
|
|
|
### Claude
|
|
|
|
- consumes simulation outputs and reports
|
|
- performs deeper reasoning on what the simulation means
|
|
- uses the same MCP tools so it sees the same state as Codex
|
|
|
|
### n8n
|
|
|
|
- schedules or triggers prediction runs
|
|
- polls preparation/report task status
|
|
- routes outputs to Slack, email, dashboards, or databases
|
|
|
|
### MCP
|
|
|
|
- standardizes access to MiroFish
|
|
- gives Codex and Claude a stable tool layer
|
|
- avoids coupling every agent directly to raw REST details
|
|
|
|
## Added in This Setup
|
|
|
|
- MCP server: [`integrations/mcp/mirofish_mcp_server.py`](/Users/al/Documents/CODEX/MiroFish/integrations/mcp/mirofish_mcp_server.py)
|
|
- start scripts:
|
|
- [`scripts/start_mirofish_mcp_stdio.sh`](/Users/al/Documents/CODEX/MiroFish/scripts/start_mirofish_mcp_stdio.sh)
|
|
- [`scripts/start_mirofish_mcp_http.sh`](/Users/al/Documents/CODEX/MiroFish/scripts/start_mirofish_mcp_http.sh)
|
|
- Codex and Claude setup guide:
|
|
- [`docs/codex-claude-mcp-setup.md`](/Users/al/Documents/CODEX/MiroFish/docs/codex-claude-mcp-setup.md)
|
|
- n8n workflow template:
|
|
- [`integrations/n8n/mirofish_prediction_pipeline.json`](/Users/al/Documents/CODEX/MiroFish/integrations/n8n/mirofish_prediction_pipeline.json)
|
|
- npm scripts:
|
|
- `npm run mcp:stdio`
|
|
- `npm run mcp:http`
|
|
|
|
## MCP Tools Exposed
|
|
|
|
- health
|
|
- project list
|
|
- project detail
|
|
- graph build
|
|
- graph task status
|
|
- simulation create
|
|
- simulation prepare
|
|
- simulation prepare status
|
|
- simulation start
|
|
- simulation stop
|
|
- simulation run status
|
|
- simulation timeline
|
|
- batch interviews
|
|
- report generate
|
|
- report generate status
|
|
- report fetch
|
|
- report fetch by simulation
|
|
- report chat
|
|
|
|
## n8n Automation Pattern
|
|
|
|
Use HTTP Request nodes against the backend:
|
|
|
|
1. `POST /api/graph/build`
|
|
2. poll `GET /api/graph/task/{task_id}`
|
|
3. `POST /api/simulation/create`
|
|
4. `POST /api/simulation/prepare`
|
|
5. poll `POST /api/simulation/prepare/status`
|
|
6. `POST /api/simulation/start`
|
|
7. poll `GET /api/simulation/{simulation_id}/run-status`
|
|
8. `POST /api/report/generate`
|
|
9. poll `POST /api/report/generate/status`
|
|
10. `GET /api/report/by-simulation/{simulation_id}`
|
|
|
|
An importable starter workflow is included at
|
|
[`integrations/n8n/mirofish_prediction_pipeline.json`](/Users/al/Documents/CODEX/MiroFish/integrations/n8n/mirofish_prediction_pipeline.json).
|
|
|
|
## Suggested Operating Mode
|
|
|
|
- Let Codex build and evolve the simulation workflow.
|
|
- Let Claude reason over the generated report and interview outputs.
|
|
- Let n8n handle timed or event-driven execution.
|
|
- Treat MiroFish as the core prediction substrate, not the orchestration system.
|
|
|
|
## Notes
|
|
|
|
- Real simulation quality depends on valid `LLM_API_KEY` and `ZEP_API_KEY`.
|
|
- Local boot verification can use placeholder values, but real runs cannot.
|
|
- Python 3.12 is required for this repo on this Mac.
|