Noureddine RAMDI / Blueprint MCP: async AI diagram generation for code architecture visualization

Created Mon, 04 May 2026 10:17:20 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
926 Words
github-stars python async mcp ai diagram-generation cursor-ide

ArcadeAI/blueprint-mcp

Blueprint MCP tackles a real pain point for developers working with AI-assisted visualization: how to handle long-running AI image generation tasks without blocking the client or server. It uses an asynchronous job pattern to generate architecture and system diagrams from codebases by leveraging Google’s Nano Banana Pro model. This approach enables AI agents, especially within the Cursor IDE, to visualize complex code architecture, API flows, data pipelines, and system designs through natural language prompts.

async AI diagram generation server for code visualization

Blueprint MCP is a Python-based MCP (Model Context Protocol) server designed to generate diagrams representing software architecture and system flows from codebase analysis. It leverages Google’s Nano Banana Pro AI model, which specializes in generating detailed diagrams from textual prompts that describe code modules, API interactions, or data pipelines.

The core architecture follows an async job pattern with three main MCP tools:

  • start_diagram_job: Initiates a diagram generation job asynchronously and returns a job ID immediately.
  • check_job_status: Polls the job status to determine if the diagram generation is complete.
  • download_diagram: Fetches the generated diagram as a base64-encoded PNG once ready.

This pattern avoids blocking both the client and server during the potentially long 30-second wait that Nano Banana Pro requires to generate images. Blueprint MCP integrates tightly with Arcade’s MCP ecosystem, where servers are deployed and registered via Arcade CLI and accessed through a centralized gateway. The repo positions itself primarily as a backend service for Cursor IDE, enabling AI agents there to request and receive visual architecture insights on demand.

Under the hood, the async job handling and prompt engineering to translate codebase contexts into diagram requests are the key technical components. The server acts as a gateway pattern node, connecting AI agents with diagram generation services in a scalable, non-blocking manner.

tradeoffs and code quality in async job management

What distinguishes Blueprint MCP is its clean implementation of the async job pattern to handle AI model processing that can’t be instantaneous. The codebase is Pythonic and focused, with clear separation between job lifecycle management and MCP tool interfaces.

The tradeoff is clear: the user must tolerate a roughly 30-second wait for diagram generation, which is unavoidable given the model’s compute needs. However, by making the job start instantly and allowing polling, it improves UX over synchronous blocking calls.

The code quality is straightforward and pragmatic. The server relies on Arcade CLI for deployment and secret management, which adds an operational dependency but simplifies integration within the Arcade ecosystem. Prompt templates for different diagram types (architecture, flow, data pipelines) are embedded, demonstrating practical prompt engineering to guide the AI model.

The design follows a gateway pattern where multiple MCP servers can be registered and accessed centrally, which is a scalable approach for distributed AI services. The documentation includes example natural language prompts, which is valuable for users to experiment with real use cases.

One limitation is the tight coupling to Arcade MCP and Cursor IDE, which may restrict standalone usage. Also, the reliance on Google AI Studio API keys means users must have access to this platform.

quick start with arcade-mcp CLI

Getting started with Blueprint MCP involves a few straightforward steps using the Arcade CLI, as documented:

# Install Arcade CLI
pip install arcade-mcp

# Login to Arcade
arcade-mcp login

# Store your Google AI Studio API key as a secret
arcade-mcp secret set GOOGLE_API_KEY="your_api_key_here"

# Clone the repo and deploy
cd blueprint-mcp
arcade-mcp deploy

After deployment, you create a gateway from the Arcade dashboard, add your server, and configure Cursor IDE to point at this gateway URL. Cursor then uses the MCP tools to start diagram jobs, poll status, and download images.

Example prompts include:

Analyze the authentication module in src/auth/ and create an
architecture diagram showing the components and their relationships.

Create a data flow diagram for our ETL pipeline showing sources,
transformations, and destinations based on the data/ directory.

These natural language prompts illustrate the server’s ability to turn code context into meaningful visualizations.

verdict: a practical async pattern for AI diagram generation

Blueprint MCP is a solid example of handling long-running AI image generation tasks asynchronously in a production MCP server. Its focus on diagram generation for codebases fills a niche for AI-assisted developer tooling, especially when integrated with Cursor IDE and the Arcade MCP ecosystem.

The async job pattern is well implemented and worth understanding if you build AI services that involve slow model responses. The tradeoff is the inherent wait time, but the design mitigates this with non-blocking jobs and polling.

If you work with AI agents in software architecture visualization or want to explore AI-driven diagramming from code, Blueprint MCP is relevant and practical. The main caveats are the dependencies on Arcade’s platform and Google AI Studio APIs, which may not fit all organizations.

Overall, Blueprint MCP shows how to connect code analysis, AI prompt engineering, and async job management into a cohesive MCP server that enables richer AI developer experiences.

→ GitHub Repo: ArcadeAI/blueprint-mcp ⭐ 609 · Python