Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (68 loc) · 3.45 KB

AGENTS.md

File metadata and controls

97 lines (68 loc) · 3.45 KB
Error in user YAML: (<unknown>): did not find expected alphabetic or numeric character while scanning an alias at line 2 column 8
---
description: Instructions building apps with MCP
globs: *
alwaysApply: true
---

InsForge SDK Documentation - Overview

What is InsForge?

Backend-as-a-service (BaaS) platform providing:

  • Database: PostgreSQL with PostgREST API
  • Authentication: Email/password + OAuth (Google, GitHub)
  • Storage: File upload/download
  • AI: Chat completions and image generation (OpenAI-compatible)
  • Functions: Serverless function deployment

Installation

🚨 CRITICAL: Follow these steps in order

Step 1: Download Template

Use the download-template MCP tool to create a new project with your backend URL and anon key pre-configured.

Step 2: Install SDK

npm install @insforge/sdk@latest

Step 3: Create SDK Client

You must create a client instance using createClient() with your base URL and anon key:

import { createClient } from '@insforge/sdk';

const client = createClient({
  baseUrl: 'https://your-app.region.insforge.app',  // Your InsForge backend URL
  anonKey: 'your-anon-key-here'       // Get this from backend metadata
});

API BASE URL: Your API base URL is https://your-app.region.insforge.app.

Getting Detailed Documentation

🚨 CRITICAL: Always Fetch Documentation Before Writing Code

Before writing or editing any InsForge integration code, you MUST call the fetch-docs MCP tool to get the latest SDK documentation. This ensures you have accurate, up-to-date implementation patterns.

Use the InsForge fetch-docs MCP tool to get specific SDK documentation:

Available documentation types:

  • "instructions" - Essential backend setup (START HERE)
  • "db-sdk" - Database operations with SDK
  • Authentication - Choose based on implementation:
    • "auth-sdk" - Direct SDK methods for custom auth flows
    • "auth-components-react" - Pre-built auth UI for React+Vite (singlepage App)
    • "auth-components-react-router" - Pre-built auth UI for React(Vite+React Router) (Multipage App)
    • "auth-components-nextjs" - Pre-built auth UI for Nextjs (SSR App)
  • "storage-sdk" - File storage operations
  • "functions-sdk" - Serverless functions invocation
  • "ai-integration-sdk" - AI chat and image generation
  • "real-time" - Real-time pub/sub (database + client events) via WebSockets

When to Use SDK vs MCP Tools

Always SDK for Application Logic:

  • Authentication (register, login, logout, profiles)
  • Database CRUD (select, insert, update, delete)
  • Storage operations (upload, download files)
  • AI operations (chat, image generation)
  • Serverless function invocation

Use MCP Tools for Infrastructure:

  • Project scaffolding (download-template) - Download starter templates with InsForge integration
  • Backend setup and metadata (get-backend-metadata)
  • Database schema management (run-raw-sql, get-table-schema)
  • Storage bucket creation (create-bucket, list-buckets, delete-bucket)
  • Serverless function deployment (create-function, update-function, delete-function)

Important Notes

  • For auth: use auth-sdk for custom UI, or framework-specific components for pre-built UI
  • SDK returns {data, error} structure for all operations
  • Database inserts require array format: [{...}]
  • Serverless functions have single endpoint (no subpaths)
  • Storage: Upload files to buckets, store URLs in database
  • AI operations are OpenAI-compatible
  • EXTRA IMPORTANT: Use Tailwind CSS 3.4 (do not upgrade to v4). Lock these dependencies in package.json