Getting Started for App Developers

Build applications on Taruvi using AI-assisted development with Claude and the Refine template.

Overview

This guide is for App Developers who want to build frontend applications that connect to a Taruvi backend. You'll use:

• Taruvi Refine Template - A pre-configured React + Refine.dev starter
• Claude Code CLI - AI-assisted "vibe coding" for rapid development
• MCP Integration - Direct connection between Claude and your Taruvi data

What you'll achieve:

• Clone and run a ready-to-use Refine application
• Connect Claude to your Taruvi backend via MCP
• Build features by describing what you want in natural language

---

Prerequisites

Before you begin, ensure you have:

• Node.js 20+ - JavaScript runtime
• npm or yarn - Package manager
• GitHub CLI (gh) - For cloning repositories (see installation below)
• Claude Code CLI - Install from Anthropic
• Taruvi Account - Access to Taruvi Console

Installing GitHub CLI

The GitHub CLI (gh) provides a streamlined way to work with GitHub repositories.

Platform	Installation
macOS	brew install gh or Download .pkg
Windows	winget install --id GitHub.cli or Download .msi
Linux (Debian/Ubuntu)	See commands below
Linux (Fedora/RHEL)	sudo dnf install gh

Linux (Debian/Ubuntu) installation:

(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

Official download links:

• GitHub CLI Releases - All platforms
• GitHub CLI Installation Guide - Detailed instructions

After installation, authenticate with GitHub:

gh auth login

---

Quick Start

1. Clone the Template

# Clone the Taruvi Refine template using GitHub CLI
gh repo clone Taruvi-ai/taruvi-refine-template my-app
cd my-app

Alternative (using git):

git clone https://github.com/Taruvi-ai/taruvi-refine-template.git my-app
cd my-app

2. Install Dependencies

npm install

3. Configure Environment

Copy the example environment file and update it with your Taruvi credentials:

cp .env.example .env

Edit .env with your settings:

# Taruvi API Configuration
VITE_API_BASE_URL=https://yoursite.taruvi.cloud/api
VITE_SITE_SCHEMA=your_site_schema

# Optional: App-specific settings
VITE_APP_SLUG=your-app-slug

Where to find these values:

Variable	Location in Taruvi Console
VITE_API_BASE_URL	Your site's base URL + /api
VITE_SITE_SCHEMA	Site Settings > General > Schema Name
VITE_APP_SLUG	Apps > Your App > Slug

4. Configure MCP for Claude

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "taruvi": {
      "type": "http",
      "url": "https://yoursite.taruvi.cloud/mcp/",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY_HERE",
        "X-App-Slug": "your-app-slug"
      }
    }
  }
}

Getting your API Key:

1. Log in to Taruvi Console
2. Navigate to Site Settings > API Keys
3. Click Generate New API Key
4. Copy the key (it won't be shown again!)

For detailed MCP configuration options, see the MCP Integration Guide.

5. Start the Development Server

npm run dev

Your app will be running at http://localhost:5173.

---

Vibe Coding with Claude

Now comes the fun part - building your app with AI assistance.

Start Claude Code

Open a terminal in your project directory and run:

claude

Connect to Taruvi MCP

Once Claude Code starts, connect to your Taruvi backend:

/mcp

This loads the MCP configuration from your .mcp.json file and connects Claude to your Taruvi data.

Verify the Connection

Ask Claude to check the connection:

What tables are available in my Taruvi app?

Claude will use MCP to query your schema and list available data tables.

---

Building Features

With Claude connected to your Taruvi backend, you can describe features in natural language and Claude will help implement them.

Example: Create a Data List Page

Prompt to Claude:

Create a page that displays a list of all products from the products table.
Include columns for name, price, and category. Add sorting and pagination.

Claude will:

1. Query your Taruvi schema to understand the products table structure
2. Generate a Refine-compatible list component
3. Configure proper data hooks (useDataGrid, useList)
4. Add sorting and pagination

Example: Build a Form

Prompt to Claude:

Create a form to add new products. Include fields for name, description,
price, and category. Validate that price is a positive number.

Example: Add Dashboard Analytics

Prompt to Claude:

Create a dashboard showing:
- Total number of products
- Products by category (pie chart)
- Recent products added this week

Claude will use MCP aggregation queries to fetch the analytics data.

---

Project Structure

The template follows Refine.dev v5 conventions:

my-app/
├── src/
│   ├── components/     # Reusable UI components
│   ├── pages/          # Page components (list, show, create, edit)
│   ├── providers/      # Data providers (Taruvi integration)
│   ├── interfaces/     # TypeScript interfaces
│   └── App.tsx         # Main application entry
├── .env                # Environment variables
├── .mcp.json           # MCP configuration for Claude
└── package.json

---

MCP Capabilities

When connected via MCP, Claude can:

Capability	Description
Query Data	Read records with filtering, sorting, pagination
Create Data	Insert new records or bulk create
Update Data	Modify existing records
Delete Data	Remove records
Aggregate	Run COUNT, SUM, AVG, GROUP BY queries
Schema Discovery	List tables and their fields

For the complete MCP reference, see MCP Integration.

---

Common Workflows

Workflow 1: Explore and Build

1. Start Claude Code: claude
2. Connect MCP: /mcp
3. Explore your data: "What tables do I have?"
4. Build features: "Create a CRUD interface for the users table"

Workflow 2: Debug Issues

1. Describe the problem to Claude
2. Claude can query your actual data via MCP to understand the issue
3. Get targeted fixes based on real data structure

Workflow 3: Generate Types

Generate TypeScript interfaces for all my Taruvi tables

Claude will query your schema and create matching TypeScript types.

---

Environment Examples

Local Development

# .env
VITE_API_BASE_URL=http://tenant1.127.0.0.1.nip.io:8000/api
VITE_SITE_SCHEMA=tenant1

// .mcp.json
{
  "mcpServers": {
    "taruvi-local": {
      "type": "http",
      "url": "http://tenant1.127.0.0.1.nip.io:8000/mcp/",
      "headers": {
        "Authorization": "Api-Key your-local-api-key",
        "X-App-Slug": "dev-app"
      }
    }
  }
}

Production

# .env
VITE_API_BASE_URL=https://api.yourcompany.com/api
VITE_SITE_SCHEMA=production

// .mcp.json
{
  "mcpServers": {
    "taruvi": {
      "type": "http",
      "url": "https://api.yourcompany.com/mcp/",
      "headers": {
        "Authorization": "Api-Key your-production-api-key",
        "X-App-Slug": "production-app"
      }
    }
  }
}

---

Troubleshooting

npm install fails

# Clear npm cache and retry
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

MCP connection fails

1. Verify your API key is correct
2. Check the URL ends with /mcp/
3. Ensure X-App-Slug matches your app exactly
4. Test the endpoint:

   curl -X POST https://yoursite.taruvi.cloud/mcp/ \
     -H "Authorization: Api-Key YOUR_API_KEY" \
     -H "X-App-Slug: your-app-slug" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}'

Dev server won't start

1. Check port 5173 isn't in use
2. Verify .env file exists and has correct values
3. Run npm run dev -- --port 3000 to use a different port

Claude can't see my tables

1. Ensure tables are created in Taruvi Console
2. Verify tables are materialized
3. Check API key has read permissions for the app

---

Next Steps

Now that you're set up:

1. Explore the Data Service - Data Service Overview
2. Learn CRUD Operations - CRUD Guide
3. Advanced Querying - Querying Guide
4. Set Up Authorization - Authorization Guide
5. Deep Dive into MCP - MCP Integration

---

Resources

• Taruvi Refine Template - The starter template
• Refine.dev Documentation - Refine framework docs
• Claude Code Documentation - Claude CLI reference
• MCP Specification - Model Context Protocol

---

Support

• Documentation
• Community Forum
• GitHub Issues
• Support Email