Workflow Gap: Add stage-based `inject_mode` for MCP tools to control chat integration

[Hackshaven]

🚀 Workflow Gap

Currently, MCP tool results (src/zyra/api/mcp_tools) are returned only as HTTP responses via mcp.py.
They do not integrate cleanly into active LLM chat sessions (ws.py). This causes two issues:

• Some results flood chat with irrelevant details (e.g., FTP file listings).
• Other results should be visible in chat (e.g., visualizations, narrations), but are not injected.

---

🔎 Proposed Solution

Introduce stage-based inject_mode defaults so that MCP results are automatically surfaced into chat in a way that matches their role in the workflow.

Defaults by Stage

• acquire → summary (counts, status updates)
• process → summary (steps completed, row counts)
• simulate → link (job ID, result reference)
• visualize → full (plots, structured visual output)
• narrate → full (plain-language text, explanations)
• disseminate → link (URL of published artifacts/reports)

---

📐 Implementation Plan

1. Define Stage Registry

# src/zyra/api/mcp_tools/registry.py

STAGE_INJECT_MODES = {
    "acquire": "summary",
    "process": "summary",
    "simulate": "link",
    "visualize": "full",
    "narrate": "full",
    "disseminate": "link",
}

---

2. Modify mcp.py (Router)

Inside src/zyra/api/routers/mcp.py, results are currently returned directly from handlers such as:

@router.post("/mcp/{tool_name}")
async def run_tool(...):
    result = await execute_tool(...)
    return result

🔧 Proposed change:

• Wrap the result with inject_mode logic before returning.
• Use a helper like handle_mcp_result(stage, tool_name, result, session_id) to both return HTTP response and publish to WebSocket.

result = await execute_tool(...)
handle_mcp_result(stage, tool_name, result, session_id)
return result

---

3. Update ws.py (WebSocket Router)

Inside src/zyra/api/routers/ws.py, WebSocket event handlers already process messages like job status updates.

Relevant functions include:

• async def websocket_endpoint(...) → main connection loop.
• async def handle_job_message(...) → handles job messages from Redis/pubsub.

🔧 Proposed change:

• Add a new handle_mcp_message alongside handle_job_message.
• Subscribe ws.py to the mcp:{session_id} Redis channel (published by mcp.py).
• Inject messages into the chat loop based on inject_mode.

async def handle_mcp_message(websocket, message):
    if message["mode"] == "summary":
        await websocket.send_text(f"[{message['stage']}/{message['tool']}] {message['content']}")
    elif message["mode"] == "full":
        await websocket.send_json(message)
    elif message["mode"] == "link":
        await websocket.send_text(f"[{message['stage']}/{message['tool']}] {message['content']}")

---

✅ UX Examples

• Acquire (FTP) → [acquire/ftp_acquire] Completed: 257 files retrieved.
• Process (regrid) → [process/regrid] Reduced dataset from 2.4M → 1.2M rows.
• Simulate (climate) → [simulate/climate] Job running (ETA 3m). Results: /results/session123/simulate/climate
• Visualize (timeseries) → Inline plot in chat.
• Narrate (summary) → “The model projects a 1.5°C warming trend by 2050, concentrated in coastal regions.”
• Disseminate (report) → [disseminate/report] Published at https://example.org/reports/2025-01

---

✅ Benefits

• Aligns with Zyra’s domain workflow stages.
• Prevents chat flooding from bulk results.
• Ensures visualizations and narrations appear inline where useful.
• Extensible: tools can override defaults later if needed.

---

🧪 Future Extensions

• Add auto mode → decide injection style dynamically based on result size/type.
• Allow per-session overrides (developer/debug mode vs end-user mode).
• Promote registry (mcp_registry.json) for central metadata management.

---

Labels: workflow-gap, enhancement