5.3 KiB

Raw Blame History

MiroFish MCP Server

The MCP server exposes MiroFish lifecycle tools, not a Graphiti proxy.

Start:

cd /Users/leaf/Documents/future/MiroFish/backend
uv run mirofish-mcp

Tools:

mirofish_create_run
mirofish_run
mirofish_resume_run
mirofish_get_status
mirofish_get_current_stage
mirofish_update_simulation_settings
mirofish_approve_stage
mirofish_reject_stage
mirofish_rerun_stage
mirofish_list_requests
mirofish_get_request
mirofish_submit_response
mirofish_validate_response
mirofish_build_graph
mirofish_search_graph
mirofish_export_graph
mirofish_start_simulation
mirofish_resume_simulation
mirofish_generate_report
mirofish_get_report
mirofish_ask_followup_question
mirofish_get_followup_answer
mirofish_list_artifacts
mirofish_doctor

Interaction Tools

After a run completes, these tools let you interact with agents through the queue:

mirofish_generate_web_console — generates an interactive HTML console at runs/<run_id>/artifacts/web/index.html.
mirofish_list_agents — lists all agent profiles from a completed run.
mirofish_get_agent — returns a single agent's profile.
mirofish_ask_agent — sends a question to a specific agent via agent_queue. Returns need_agent_response with a request_id.
mirofish_get_agent_answer — after the desktop agent writes the response file, call this to validate, persist, and retrieve the answer.
mirofish_send_questionnaire — sends a batch questionnaire to all agents. questions_json is a JSON string: '[{"question_id":"q1","question":"Biggest risk?"}, ...]'.
mirofish_get_questionnaire_result — retrieves questionnaire answers and summary.
mirofish_ask_report_question — asks a question about the report via agent_queue.
mirofish_get_report_question_answer — retrieves and persists a report question answer.

Web Console

The Web Console is a static HTML page with embedded run data plus live API interaction when the Flask backend is running.

Generate the console:

uv run mirofish-agent web generate --run ../runs/chip-2036 --json

Or via MCP: call mirofish_generate_web_console.

Open the generated file: runs/<run_id>/artifacts/web/index.html

Start the Flask backend for interactive features:

cd /Users/leaf/Documents/future/MiroFish/backend
uv run flask --app app run --port 5001

The console auto-detects the API at http://localhost:5001. You can change the base URL in the sidebar.

When the API is offline, the console falls back to displaying embedded static data from the run artifacts.

Agent Q&A Flow

Call mirofish_ask_agent(run, agent_id, question) — returns request_id.
A desktop agent reads runs/<run_id>/requests/<request_id>.json and writes runs/<run_id>/responses/<request_id>.json.
Call mirofish_get_agent_answer(run, request_id) to validate the response and persist it to artifacts/interactions/agent_questions/.

Questionnaire Flow

Call mirofish_send_questionnaire(run, questions_json) with a JSON array of {question_id, question} objects.
Each agent gets a separate agent_queue request per question.
Call mirofish_get_questionnaire_result(run, questionnaire_id) to collect answers and summary.

Staged Mode

Use staged mode when a desktop agent should mirror the original MiroFish step-by-step UI flow. The simulation round count is a hard MCP field, not text hidden in the requirement.

Typical Qoder/Codex/Claude Code sequence:

Call mirofish_doctor.
Call mirofish_create_run with mode="staged", rounds=10, round_unit="year", and the seed/requirement/output path.
Call mirofish_get_current_stage and show the user the stage summary.
After user confirmation, call mirofish_approve_stage.
Call mirofish_resume_run; staged mode advances only to the next pause point or need_agent_response.
When need_agent_response appears, read request_file, write the response JSON, call mirofish_validate_response, then mirofish_submit_response.
Repeat resume/approve until report.md, verdict.json, timeline.json, and graph_snapshot.json exist.
Use mirofish_ask_followup_question for post-report questions.

Example mirofish_create_run arguments:

{
  "seed": "/Users/leaf/Documents/future/MiroFish/seeds/chip.md",
  "requirement": "预测未来10年全球芯片能力格局变化",
  "output": "/Users/leaf/Documents/future/MiroFish/runs/chip-2036",
  "mode": "staged",
  "rounds": 10,
  "round_unit": "year",
  "minutes_per_round": 525600,
  "pause_each_round": false,
  "agent_count": 5,
  "simulation_name": "chip-2036"
}

If the user changes hard parameters before approval, call mirofish_update_simulation_settings. The engine marks dependent stages stale/pending so old profile/config/simulation/report outputs are not silently reused.

Example MCP server config:

{
  "mcpServers": {
    "mirofish": {
      "command": "uv",
      "args": ["run", "mirofish-mcp"],
      "cwd": "/Users/leaf/Documents/future/MiroFish/backend",
      "env": {
        "MIROFISH_MODE": "agent",
        "MIROFISH_LLM_PROVIDER": "agent_queue",
        "MIROFISH_GRAPH_PROVIDER": "graphiti",
        "MIROFISH_RUNS_DIR": "./runs"
      }
    }
  }
}

Reference: https://modelcontextprotocol.github.io/python-sdk/server/

5.3 KiB Raw Blame History