[Feature Request] Markdown Output Support and File Reference Architecture for Large-Scale Agent Workflows

[dirkenglund]

Feature Requests for Agent Workflow Visualizations

I've been using mcp-mermaid successfully to generate sequence diagrams for multi-agent simulations, and it works great! However, I'd like to propose a few enhancements that would make it even more powerful for large-scale agent workflows.

---

1. 🎯 Markdown Output Support (High Priority)

Current Behavior:

• outputType: "svg" returns raw SVG
• outputType: "mermaid" returns Mermaid source code

Desired Enhancement:
Add outputType: "markdown" that returns:

# Diagram Title

```mermaid
sequenceDiagram
    participant A
    participant B
    A->>B: Message

**Use Case**:
When generating documentation programmatically, we want to create `.md` files that render in GitHub/VS Code/GitLab without additional processing.

**Current Workaround**:
```typescript
const result = await generate_mermaid_diagram({
  mermaid: diagramSource,
  outputType: "mermaid"
});
// Manually wrap in markdown fenced code block
const markdown = "```mermaid\n" + result + "\n```";

Would be much cleaner with direct markdown support!

---

2. 📊 File Reference Architecture Support (Medium Priority)

Context:
For large-scale agent simulations with 100+ interactions, embedding all data in visualization files creates huge files (10+ MB) that waste LLM tokens.

Proposed Enhancement:
Add support for metadata-only output that references external data files:

const viz = await generate_mermaid_diagram({
  mermaid: diagramSource,
  outputType: "metadata",
  dataReferences: {
    interactions: "sessions/*.json",
    database: "neo4j+s://...",
    agents: "agents/*.json"
  }
});

// Returns lightweight metadata:
{
  "diagram_type": "sequence",
  "participants": ["Agent1", "Agent2"],
  "data_sources": {
    "interactions": "sessions/*.json",
    "database": "neo4j+s://..."
  },
  "summary_stats": {
    "total_interactions": 12,
    "agents_count": 4
  }
}

Benefits:

• Visualization files stay ~5 KB instead of 10+ MB
• LLMs don't waste tokens reading large datasets
• Scales to any simulation size
• Data stored once, referenced multiple times

Use Case:
Agent marketplace simulations with episodic memory in Neo4j. We want lightweight diagrams that reference session files and database queries, not embed all interaction data.

---

3. 🤖 Agent Workflow Templates (Low Priority)

Proposed Enhancement:
Built-in templates for common agent interaction patterns:

const diagram = await generate_agent_workflow({
  template: "orchestrator_multi_agent",
  orchestrator: "Puppeteer",
  agents: ["Wolf", "Anne", "MarketBot"],
  phases: ["Creation", "Matching", "Decision", "Contract"],
  dataSource: "neo4j://..."
});

Patterns to support:

• Orchestrator → Agent communication
• Agent ↔ Agent peer interactions
• Agent → Database persistence
• Phase-separated workflows
• Autonomous vs. non-autonomous action distinction

---

Reference Implementation

I've successfully used mcp-mermaid to generate a sequence diagram showing:

• 6 participants: Orchestrator, 2 agents, marketplace, admin, Neo4j
• 5 phases: Agent Creation → Job Matching → Decision → Contract → Save
• 12 interactions: All timestamped and logged
• Activation boxes, self-loops, and phase annotations

Working example: agent_simulation_sequence.md (in my project repo)

Current configuration:

{
  "mermaid": "sequenceDiagram\n    participant Orchestrator...",
  "outputType": "mermaid",
  "theme": "default",
  "backgroundColor": "white"
}

---

Implementation Context

• Project: Multi-agent marketplace simulation with episodic memory
• Storage: Neo4j graph database for agent interactions
• Session files: Individual JSON files per agent (~1-10 MB each)
• Visualization goal: Lightweight diagrams with file references
• Author: Implementation by Claude (Anthropic) in collaboration with @dirkenglund

---

Potential Contribution

If helpful, I can:

1. Fork the repository
2. Implement these features in separate branches
3. Submit PRs with:
   • Working code examples
   • Test cases
   • Documentation updates
   • Reference implementations from my project

---

Priority Summary

1. High: Markdown output support (most frequently needed)
2. Medium: File reference architecture (scalability concern)
3. Low: Agent workflow templates (nice-to-have, can be user-side)

---

Thank you for creating this excellent MCP server! It's been invaluable for our agent workflow visualizations. 🙏

Let me know if you'd like any clarifications or if I can help with implementation!

[hustcc]

I think Markdown Output Support (High Priority) is not necessary; it belongs to an external output format encapsulation. Similar examples include:

• base64 output as CSS string
• file outputs as markdown image string
• mermaid output as template code based on Mermaid library

Additionally, outputting as Markdown also relies on the user incorporating a Mermaid plugin during rendering. If users customize their Markdown plugins, there is a high likelihood that the code type of markdown output will not use mermaid.