Skip to main content
Glama

Hype Dash

npm version npm downloads License: MIT TypeScript GitHub Stars GitHub Issues Node Version Package Size Build Status MCP Compatible

Production-ready TypeScript SDK for creating and managing Lark/Feishu dashboards via REST API with Model Context Protocol (MCP) server support.

Features

  • Type-Safe: Full TypeScript support with comprehensive type definitions

  • Fluent API: Intuitive builder pattern for creating dashboard blocks

  • 7 Block Types: Charts, Metrics, Views, Text, Lists, Tab Pages, and Filters

  • MCP Server: Native Claude Code integration via Model Context Protocol

  • Production Ready: Error handling, retries, logging, and validation

  • Batch Operations: Efficiently create multiple blocks at once

  • 2025 Dashboard Features: Latest Lark dashboard capabilities

  • Python SDK: Comprehensive Python SDK for Lark Base data management

Related MCP server: mcp-boilerplate

Installation

TypeScript/JavaScript

npm install @hypelab/hype-dash

Python

cd python
pip install -r requirements.txt

See Python SDK Documentation for detailed setup and usage.

Quick Start

Basic Usage

import { LarkDashboardClient, ChartBlockBuilder, AggregationType } from '@hypelab/hype-dash';

const client = new LarkDashboardClient({
  apiKey: process.env.LARK_API_KEY!,
  region: 'sg', // 'sg' | 'cn' | 'us'
  logging: true,
});

// Create a dashboard
const dashboardId = await client.createDashboard({
  name: 'Sales Dashboard',
  appToken: 'YOUR_APP_TOKEN',
});

// Add a bar chart
const chartBlock = ChartBlockBuilder.bar()
  .dataSource('YOUR_APP_TOKEN', 'YOUR_TABLE_ID')
  .xAxis({ fieldName: 'Category' })
  .yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
  .title('Revenue by Category')
  .colors(['#3b82f6', '#10b981', '#f59e0b'])
  .build();

await client.addBlock('YOUR_APP_TOKEN', dashboardId, chartBlock);

Available Block Types

1. Chart Blocks

import { ChartBlockBuilder, ChartType, AggregationType } from '@hypelab/hype-dash';

// Bar Chart
const barChart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .xAxis({ fieldName: 'Month' })
  .yAxis([
    { fieldName: 'Sales', aggregation: AggregationType.SUM, label: 'Total Sales' },
    { fieldName: 'Orders', aggregation: AggregationType.COUNT, label: 'Order Count' }
  ])
  .title('Monthly Sales Performance')
  .showLegend(true)
  .build();

// Line Chart
const lineChart = ChartBlockBuilder.line()
  .dataSource(appToken, tableId)
  .xAxis({ fieldName: 'Date' })
  .yAxis([{ fieldName: 'Revenue', aggregation: AggregationType.SUM }])
  .build();

// Pie Chart
const pieChart = ChartBlockBuilder.pie()
  .dataSource(appToken, tableId)
  .series({ fieldName: 'Category' })
  .yAxis([{ fieldName: 'Amount', aggregation: AggregationType.SUM }])
  .build();

2. Metrics Blocks

import { MetricsBlockBuilder, AggregationType } from '@hypelab/hype-dash';

const metrics = new MetricsBlockBuilder()
  .dataSource(appToken, tableId)
  .fieldName('Revenue')
  .aggregation(AggregationType.SUM)
  .title('Total Revenue')
  .prefix('$')
  .decimals(2)
  .trendComparison(30, 'days')
  .build();

3. View Blocks

import { ViewBlockBuilder, ViewType } from '@hypelab/hype-dash';

const tableView = ViewBlockBuilder.table()
  .dataSource(appToken, tableId, viewId)
  .title('Customer List')
  .showToolbar(true)
  .height(400)
  .build();

const kanbanView = ViewBlockBuilder.kanban()
  .dataSource(appToken, tableId, viewId)
  .build();

4. Text Blocks

import { TextBlockBuilder } from '@hypelab/hype-dash';

const heading = new TextBlockBuilder()
  .heading('Dashboard Overview')
  .alignment('center')
  .build();

const paragraph = new TextBlockBuilder()
  .paragraph('Welcome to the sales dashboard.')
  .build();

MCP Server Usage

The SDK includes a Model Context Protocol server for Claude Code integration.

Setup

Add to your ~/.claude.json or Claude Code configuration:

{
  "mcpServers": {
    "hype-dash": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hypelab/hype-dash"],
      "env": {
        "LARK_API_KEY": "your-api-key-here",
        "LARK_REGION": "sg"
      }
    }
  }
}

Available MCP Tools

  • create_dashboard - Create a new dashboard

  • create_chart_block - Add chart visualizations

  • create_metrics_block - Add KPI metrics

  • create_view_block - Add table/kanban views

  • create_text_block - Add text content

  • list_dashboards - List all dashboards

  • delete_dashboard - Remove dashboards

Usage with Claude Code

Create a sales dashboard with:
- Bar chart showing revenue by month
- KPI card for total revenue
- Table view of recent orders

Claude will use the MCP tools to create the dashboard automatically.

Python SDK

The project includes a comprehensive Python SDK for managing Lark Base data. This allows you to:

  • Sync External Data: Import data from TikTok Ads, databases, APIs, etc.

  • Batch Operations: Efficiently create/update thousands of records

  • Data Transformation: Transform and validate data before loading

  • Automatic Dashboard Updates: Dashboards automatically reflect data changes

Quick Example

from lark_client import LarkBaseClient, LarkConfig
from data_manager import DataManager

# Initialize client
config = LarkConfig(
    app_id=os.getenv('LARK_APP_ID'),
    app_secret=os.getenv('LARK_APP_SECRET')
)
client = LarkBaseClient(config)
data_manager = DataManager(client)

# Sync TikTok campaign data
tiktok_data = fetch_tiktok_campaigns()  # Your data source
result = data_manager.batch_upsert_records(
    app_token='YOUR_APP_TOKEN',
    table_id='YOUR_TABLE_ID',
    records=tiktok_data,
    key_field='campaign_id'
)

print(f"Synced {result['total']} campaigns")
# Your dashboards now show updated data automatically!

Python SDK Features

  • Full CRUD operations for tables, fields, and records

  • Batch operations with automatic pagination

  • Data validation and transformation utilities

  • Incremental sync with timestamp tracking

  • Field mapping for external data sources

  • Rate limiting and error handling

  • Comprehensive logging

See Python SDK Documentation for complete guide.

Workflow: Python + TypeScript

  1. Python: Manage data (create tables, sync external sources, batch updates)

  2. TypeScript: Create beautiful dashboards to visualize the data

  3. Automatic: Dashboards update automatically when data changes

# 1. Python: Sync data
data_manager.batch_upsert_records(...)
// 2. TypeScript: Create dashboard
const chart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .build();

Configuration

Client Options

const client = new LarkDashboardClient({
  apiKey: string;          // Required: Lark API key
  region?: 'sg' | 'cn' | 'us';  // Default: 'sg'
  apiUrl?: string;         // Optional: Custom API URL
  logging?: boolean;       // Default: false
  timeout?: number;        // Default: 30000ms
  maxRetries?: number;     // Default: 3
  retryDelay?: number;     // Default: 1000ms
});

Environment Variables

LARK_API_KEY=your-api-key
LARK_REGION=sg
LARK_LOGGING=true

Advanced Features

Batch Operations

const blocks = [
  ChartBlockBuilder.bar().dataSource(appToken, tableId).build(),
  MetricsBlockBuilder.sum('Revenue').dataSource(appToken, tableId).build(),
  ViewBlockBuilder.table().dataSource(appToken, tableId, viewId).build(),
];

const results = await client.batchCreateBlocks(appToken, blocks);

Filtering

import { FilterOperator, FilterConjunction } from '@hypelab/hype-dash';

const chart = ChartBlockBuilder.bar()
  .dataSource(appToken, tableId)
  .filters(FilterConjunction.AND, [
    { fieldName: 'Status', operator: FilterOperator.IS, value: 'Active' },
    { fieldName: 'Revenue', operator: FilterOperator.GT, value: 1000 }
  ])
  .build();

Error Handling

import { ValidationError } from '@hypelab/hype-dash';

try {
  await client.addBlock(appToken, dashboardId, block);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else {
    console.error('API error:', error);
  }
}

API Reference

LarkDashboardClient

  • createDashboard(dashboard: Dashboard): Promise<string>

  • addBlock(appToken: string, dashboardId: string, block: DashboardBlock): Promise<string>

  • updateBlock(appToken: string, blockId: string, block: Partial<DashboardBlock>): Promise<void>

  • deleteBlock(appToken: string, blockId: string): Promise<void>

  • listBlocks(appToken: string): Promise<DashboardBlock[]>

  • batchCreateBlocks(appToken: string, blocks: DashboardBlock[]): Promise<BatchOperationResult[]>

Builders

  • ChartBlockBuilder - Create chart visualizations

  • MetricsBlockBuilder - Create KPI metrics

  • ViewBlockBuilder - Create data views

  • TextBlockBuilder - Create text blocks

  • ListBlockBuilder - Create list blocks (2025)

  • TabPageBlockBuilder - Create tab pages (2025)

Examples

See the /examples directory for complete examples:

  • basic-dashboard.ts - Simple dashboard creation

  • complete-dashboard.ts - Full-featured dashboard

  • multi-source-dashboard.ts - Multiple data sources

  • realtime-dashboard.ts - Real-time data updates

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

import type {
  DashboardBlock,
  ChartConfig,
  MetricsConfig,
  ViewConfig,
  ChartType,
  ViewType,
  AggregationType,
} from '@hypelab/hype-dash';

Requirements

TypeScript/JavaScript

  • Node.js >= 16.0.0

  • TypeScript >= 5.0.0 (for TypeScript projects)

Python

Troubleshooting

Common Issues

Authentication Errors

  • Verify your LARK_API_KEY is correct

  • Check API key permissions in Lark admin console

  • Ensure region matches your Lark workspace ('sg', 'cn', or 'us')

Network Errors

  • Check firewall settings

  • Verify network connectivity to Lark API

  • Try increasing timeout in client config

Validation Errors

  • Ensure required fields are provided

  • Check data types match API expectations

  • Verify field names exist in your Lark tables

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Support

Changelog

See CHANGELOG.md for version history and updates.

Available Tools

7 tools
create_chart_blockB

Create a chart block (bar, line, pie, scatter, area, column, funnel, radar, table) and add it to a dashboard

Inputs: app_token (required), dashboard_id (required), chart_type (required), table_id (required), +6 more.

create_dashboardA

Create a new dashboard in a Lark Base by copying an existing one. Note: Lark API does not support creating dashboards from scratch - this copies an existing dashboard. If no source_block_id is provided, it will automatically copy the first available dashboard. Returns the new dashboard ID.

Inputs: app_token (required), name (required), source_block_id.

create_metrics_blockB

Create a metrics/KPI block showing aggregated values

Inputs: app_token (required), dashboard_id (required), table_id (required), field_name (required), +5 more.

create_text_blockB

Create a text/markdown block with formatted content

Inputs: app_token (required), dashboard_id (required), content (required), is_heading, +1 more.

create_view_blockB

Create a view block (grid, kanban, gallery, gantt, form) showing table data

Inputs: app_token (required), dashboard_id (required), view_type (required), table_id (required), +3 more.

delete_dashboardC

Delete a dashboard from a base

Inputs: app_token (required), dashboard_id (required).

list_dashboardsB

List all dashboards in a base

Inputs: app_token (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct dashboard element or action: blocks (chart, metrics, text, view) and dashboard CRUD. No overlaps or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (create_*, delete_*, list_*) using snake_case, making the API predictable.

    Tool Count5/5

    7 tools is well-scoped for a dashboard builder, covering essential block types and dashboard management without unnecessary bloat.

    Completeness4/5

    Covers creation of main block types and basic dashboard lifecycle but lacks update and delete operations for blocks, which may force agents to recreate items.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An extensible TypeScript-based MCP server designed for Claude Code with a modular architecture for easily adding custom tools. It includes built-in examples like a calculator and echo tool, utilizing Zod for robust input validation and error handling.
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Production-ready template for building MCP servers with TypeScript, featuring example tools and resources, and Claude Desktop integration.
      1
      10 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A TypeScript/Node.js MCP server that wraps the Metabase REST API, enabling AI agents to execute queries, explore schemas, and build dashboards through structured tool calls.
      167 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      TypeScript AI SDK with a built-in MCP client: 58+ MCP servers over 4 transports (stdio, HTTP, SSE, WebSocket), 24+ LLM providers behind one interface, streaming, tool calling, RAG, voice (TTS/STT/realtime), and task scheduling.
      10,617 npm
      167
      MIT