@egdesk/next-api-plugin

Next.js plugin for EGDesk database proxy integration. Provides middleware-based CORS-free database access for Next.js applications.

Features

• 🔒 CORS-free database access via Next.js middleware (or proxy.ts on Next.js 16+)
• 🌐 Works in both local and tunneled environments
• 📝 Type-safe table definitions and helper functions (user data, FinanceHub, internal knowledge / business identity / company research, browser recording)
• 🚀 Auto-discovery of database tables
• 🔧 Zero configuration after setup

Installation

npm install @egdesk/next-api-plugin
# or
yarn add @egdesk/next-api-plugin
# or
pnpm add @egdesk/next-api-plugin

Quick Start

1. Run the setup command in your Next.js project:

npx egdesk-next-setup

This will generate:

• middleware.ts - Database proxy middleware
• egdesk.config.ts - Type-safe table definitions
• egdesk-helpers.ts - Helper functions for database access
• .env.local - Environment variables

2. Add .env.local to your .gitignore (if not already there)

3. Restart your Next.js dev server

4. Use the helpers in your components:

import { queryTable } from './egdesk-helpers';
import { TABLES } from './egdesk.config';

export default async function MyPage() {
  const data = await queryTable(TABLES.table1.name, { limit: 10 });

  return (
    <div>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}

Configuration

Environment Variables

The plugin uses Next.js environment variables:

NEXT_PUBLIC_EGDESK_API_URL=http://localhost:8080
NEXT_PUBLIC_EGDESK_API_KEY=your-api-key-here

Custom Setup

You can programmatically run the setup:

import { setupNextApiPlugin } from '@egdesk/next-api-plugin';

await setupNextApiPlugin('/path/to/project', {
  egdeskUrl: 'http://localhost:8080',
  apiKey: 'optional-api-key'
});

How It Works

The plugin generates middleware.ts or proxy.ts that intercepts special paths and forwards them to your EGDesk HTTP MCP server so the browser never talks to another origin directly.

Proxied paths (examples):

| Path | Forwards to | |------|-------------| | __user_data_proxy | POST /user-data/tools/call | | __browser_recording_proxy | POST /browser-recording/tools/call | | __internal_knowledge_proxy | POST /internal-knowledge/tools/call (knowledge docs, business identity snapshots, company research) |

User-data request flow:

1. Your code calls queryTable() or another helper
2. Helper fetches __user_data_proxy
3. Middleware/proxy forwards to http://<EGDESK>/user-data/tools/call
4. Parsed JSON is returned to your component

API Reference

Helper Functions

// Query table data
queryTable(tableName: string, options?: {
  filters?: Record<string, string>;
  limit?: number;
  offset?: number;
  orderBy?: string;
  orderDirection?: 'ASC' | 'DESC';
})

// Search table
searchTable(tableName: string, searchQuery: string, limit?: number)

// Aggregate data
aggregateTable(tableName: string, column: string, aggregateFunction: 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT', options?: {
  filters?: Record<string, string>;
  groupBy?: string;
})

// Execute raw SQL
executeSQL(query: string)

// List all tables
listTables()

// Get table schema
getTableSchema(tableName: string)

// Internal Knowledge / Business Identity / Company Research (MCP)
callInternalKnowledgeTool(toolName: string, args?: Record<string, any>)
listKnowledgeDocuments(snapshotId: string, category?: 'hierarchy' | 'process' | 'policy' | 'note')
getKnowledgeDocument(documentId: string)
searchKnowledgeContent(snapshotId: string, searchText: string, category?: ...)
getKnowledgeByCategory(snapshotId: string, category: ...)
listBusinessIdentitySnapshots(brandKey?: string)
getBusinessIdentitySnapshot(snapshotId: string)
getBusinessIdentityCompanyInfo(snapshotId: string)
getBusinessIdentityServicesProducts(snapshotId: string)
listCompanyResearch(status?: 'completed' | 'failed' | 'in_progress')
getCompanyResearchById(researchId: string)
getCompanyResearchByDomain(domain: string)
searchCompanyResearch(searchText: string)

Configuration Types

interface TableDefinition {
  name: string;
  displayName: string;
  description?: string;
  rowCount: number;
  columnCount: number;
  columns: string[];
}

const TABLES = {
  table1: TableDefinition,
  table2: TableDefinition,
  // ...
}

const TABLE_NAMES = {
  table1: 'actual_table_name',
  table2: 'another_table_name',
  // ...
}

Troubleshooting

Middleware not working

Make sure:

• middleware.ts is in your project root (not in src/ or app/)
• Your Next.js version is 13.0.0 or higher
• You've restarted your dev server after setup

CORS errors

If you're still seeing CORS errors:

• Check that middleware.ts was generated correctly
• Verify environment variables are set in .env.local
• Make sure you're using the relative URL __user_data_proxy (no leading slash)

Table discovery fails

Ensure:

• EGDesk MCP server is running on localhost:8080
• You have tables imported in EGDesk
• API key is correct (if required)

License

MIT