# pipedreamhq/mcp architecture

> Architecture diagram of the GitHub repository pipedreamhq/mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pipedreamhq/mcp
- Repository: https://github.com/pipedreamhq/mcp

## Overview

##### Project type and purpose
- This is a monorepo containing three examples of integrating with Pipedream’s dynamic Model Context Protocol (MCP) server:
- A full-stack Next.js “Chat App” under examples/chat
- A CLI “AI SDK” example under examples/ai-sdk
- A CLI “OpenAI SDK” example under examples/openai-sdk
- The primary focus is the Chat App Example, a production-ready Next.js web application demonstrating real-time chat, authentication, persistence, and dynamic tool discovery via Pipedream’s MCP server.

##### File structure
- Top-level uses pnpm workspaces; shared libs and configs reside under examples/shared.
- examples/chat directory follows Next.js 13+ App Router structure:
- app/… contains React server/client components and API routes (/api/chat, /api/history, /api/files, /api/suggestions, /api/vote, /auth)
- components/… houses UI primitives, higher-level widgets, and shared hooks
- lib/… holds domain logic: AI providers, tool definitions, DB schema and migrations (Drizzle ORM), auth utils
- middleware.ts for edge logic
- tests/ cover integration and unit tests
- config files: next.config.ts, tailwind.config.ts, drizzle.config.ts, Docker-compose.yml
- docs/ guide on setup, models, artifacts, migrations
- examples/ai-sdk and examples/openai-sdk are small TS CLI apps demonstrating MCP calls in a single Node process.

##### README for additional insights
- Emphasizes dynamic tool discovery per MCP spec
- Shows environment variables for auth, persistence, and LLM keys
- Describes three example entrypoints: pnpm chat, pnpm ai-sdk, pnpm openai-sdk

##### Main components
a. Frontend (Browser)
- Next.js React pages & components
- Authentication UI (NextAuth sign-in/register)
- Chat interface, file upload, document preview, code editor widgets
b. Backend (Next.js Server)
- Server-side rendering & API routes
- NextAuth OAuth callbacks to Pipedream Connect
- API endpoints for chat streaming, document management, file uploads, suggestions, vote tracking, healthcheck
- Middleware for session handling
c. Data Layer
- Postgres (or compatible) via Drizzle ORM
- Tables: users, chats, messages, artifacts, migrations metadata
d. MCP Service Integration
- Pipedream MCP Server (external) for dynamic tool discovery & execution
- Wrapper in lib/ai/providers.ts and lib/pd-backend-client.ts
e. External Services invoked via MCP
- OpenAI API (LLM provider)
- Third-party APIs (Slack, Weather, custom Pipedream integrations)
f. CLI Examples
- ai-sdk and openai-sdk processes that invoke MCP calls directly

##### Relationships and data flow
- Browser → Next.js API → Drizzle DB (for persistence)
- Browser → Next.js API → Pipedream MCP Server → External APIs/LLMs → Next.js API → Browser
- NextAuth flow: Browser ↔ NextAuth API ↔ Pipedream Connect OAuth endpoints
- Shared code: examples/shared is imported by both CLI examples and chat back end
- CLI flow: Node process → MCP Server → external APIs → STDOUT

##### Architectural patterns and design principles
- Layered architecture: UI layer, API layer, service/integration layer, data layer
- Separation of concerns: UI components vs. business logic in lib/ vs. data access in lib/db
- Dynamic service discovery: MCP server acts as a registry and executor of tools at runtime
- Serverless-style API routes: each /api/… route is its own handler
- Test coverage: integration tests for API routes and prompts

- Browser UI → Next.js Server (API + SSR) → Drizzle/Postgres
- Next.js Server → Pipedream MCP Server → External APIs/LLMs
- NextAuth OAuth flow → Pipedream Connect
- CLI examples flow separate from Chat App
- Notes on dynamic tool discovery as central pattern

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Presentation Layer
  subgraph "Presentation Layer" 
    direction TB
    Browser["Browser UI"]:::ui
    ReactApp["Next.js App Router"]:::ui
    AuthUI["Authentication UI"]:::ui
    ChatUI["Chat Interface"]:::ui
    GlobalLayout["Global Layout & Assets"]:::ui
  end

  %% API Layer
  subgraph "API Layer (Next.js Server)" 
    direction TB
    SSR["Server-Side Rendering"]:::api
    APIChat["Chat API Routes"]:::api
    APIAuth["Auth API Route"]:::api
    APIOther["Other API Routes"]:::api
    Middleware["Middleware (Session)"]:::api
  end

  %% Services Layer
  subgraph "Services & Integrations"
    direction TB
    NextAuthService["NextAuth / Pipedream Connect"]:::ext
    MCPServer["Pipedream MCP Server"]:::ext
    ExternalAPIs["External APIs / LLMs"]:::ext
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    Postgres["Postgres Database"]:::db
  end

  %% CLI Examples
  subgraph "CLI Examples"
    direction TB
    CLIAISDK["AI SDK CLI"]:::cli
    CLIOpenAI["OpenAI SDK CLI"]:::cli
  end

  %% Shared Workspace
  Shared["Shared Workspace Utilities"]:::shared

  %% Main Chat App Group
  subgraph "Full-stack Chat App (examples/chat)"
    direction TB
    PresentationLayer---APILayer
    APILayer---ServicesLayer
    APILayer---DataLayer
    Shared
  end

  %% Flows
  Browser -->|"HTTP/WebSocket"| SSR
  SSR -->|"renders pages"| Browser
  Browser -->|"API calls"| APIChat
  Browser -->|"Auth requests"| APIAuth
  APIChat -->|"CRUD & streaming"| Postgres
  APIChat -->|"tool discovery"| MCPServer
  APIChat -->|"auth callbacks"| NextAuthService
  APIAuth --> NextAuthService
  MCPServer -->|"executes tools"| ExternalAPIs
  APIChat --> SSR
  Middleware --> APIChat
  Middleware --> APIAuth
  SSR --> Postgres

  CLIAISDK -->|"MCP calls"| MCPServer
  CLIOpenAI -->|"MCP calls"| MCPServer
  CLIAISDK --> Shared
  CLIOpenAI --> Shared

  Shared --> MCPServer

  %% Click Events
  click Browser "https://github.com/pipedreamhq/mcp/tree/main/examples/chat/app"
  click ReactApp "https://github.com/pipedreamhq/mcp/tree/main/examples/chat/app"
  click AuthUI "https://github.com/pipedreamhq/mcp/tree/main/examples/chat/app/(auth)"
  click ChatUI "https://github.com/pipedreamhq/mcp/tree/main/examples/chat/app/(chat)"
  click GlobalLayout "https://github.com/pipedreamhq/mcp/blob/main/examples/chat/app/globals.css"
  click Middleware "https://github.com/pipedreamhq/mcp/blob/main/examples/chat/middleware.ts"
  click Postgres "https://github.com/pipedreamhq/mcp/blob/main/examples/chat/lib/db/schema.ts"
  click MCPServer "https://github.com/pipedreamhq/mcp/blob/main/examples/chat/mods/mcp-client.ts"
  click Shared "https://github.com/pipedreamhq/mcp/tree/main/examples/shared"
  click CLIAISDK "https://github.com/pipedreamhq/mcp/tree/main/examples/ai-sdk"
  click CLIOpenAI "https://github.com/pipedreamhq/mcp/tree/main/examples/openai-sdk"

  %% Styles
  classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
  classDef api fill:#DFFFE0,stroke:#28A745,color:#28A745
  classDef ext fill:#FFE8D0,stroke:#D97706,color:#D97706
  classDef db fill:#E8D0FF,stroke:#6F42C1,color:#6F42C1
  classDef cli fill:#F0F0F0,stroke:#666,color:#666
  classDef shared fill:#FFF3D0,stroke:#C69500,color:#C69500
```
