@enfyra/mcp-server 0.0.1

package/README.md

@@ -0,0 +1,115 @@
+# Enfyra MCP Server
+
+MCP (Model Context Protocol) server for managing Enfyra instances via Claude Code.
+
+## Features
+
+- **Auto Token Refresh**: Automatically obtains and refreshes JWT tokens
+- **Metadata Management**: Query tables, columns, relations, routes, hooks
+- **CRUD Operations**: Create, read, update, delete records in any table
+- **Route & Handler Management**: Create routes, handlers, pre/post hooks
+- **Table Management**: Create tables and columns
+- **Cache Control**: Reload metadata, routes, Swagger, GraphQL
+- **Log Access**: View and tail log files
+
+## Add to Claude Code
+
+### Method 1: Global Configuration (Recommended)
+
+Edit `~/.claude.json` and add to the `mcpServers` section:
+
+```json
+{
+  "mcpServers": {
+    "enfyra": {
+      "command": "npx",
+      "args": ["-y", "@enfyra/mcp-server"],
+      "env": {
+        "ENFYRA_API_URL": "http://localhost:3000/api",
+        "ENFYRA_EMAIL": "your-email@example.com",
+        "ENFYRA_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+**Important**:
+- The `-y` flag automatically confirms installation
+- After updating config, restart Claude Code for changes to take effect
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ENFYRA_API_URL` | Base URL of Enfyra API | `http://localhost:3000/api` |
+| `ENFYRA_EMAIL` | Admin email for authentication | - |
+| `ENFYRA_PASSWORD` | Admin password for authentication | - |
+
+## Available Tools
+
+### Authentication
+- `login` - Login and get new access token
+
+### Metadata
+- `get_all_metadata` - Get all system metadata
+- `get_table_metadata` - Get metadata for a specific table
+- `query_table` - Query any table with filters
+- `find_one_record` - Find a single record
+
+### CRUD
+- `create_record` - Create a new record
+- `update_record` - Update a record
+- `delete_record` - Delete a record
+
+### Routes & Handlers
+- `get_all_routes` - Get all route definitions
+- `create_route` - Create a new route
+- `create_handler` - Create a handler for a route
+- `create_pre_hook` - Create a pre-hook
+- `create_post_hook` - Create a post-hook
+
+### Tables
+- `get_all_tables` - Get all table definitions
+- `create_table` - Create a new table
+- `create_column` - Create a column
+- `sync_table_schema` - Sync DB schema with metadata
+
+### System
+- `reload_all` - Reload all caches
+- `reload_metadata` - Reload metadata only
+- `reload_routes` - Reload routes only
+- `reload_swagger` - Reload Swagger spec
+- `reload_graphql` - Reload GraphQL schema
+
+### Logs
+- `get_log_files` - List available log files
+- `get_log_content` - Get log file content
+- `tail_log` - Get last N lines from log
+
+### Auth
+- `get_current_user` - Get current user info
+- `get_all_roles` - Get all roles
+
+## Usage Examples
+
+After configuring in Claude Code:
+
+```
+"Query all users"
+→ Uses query_table with tableName="user_definition"
+
+"Create a new API route for /api/tasks"
+→ Uses create_route, then create_handler
+
+"Debug the error logs"
+→ Uses tail_log with filename="error.log"
+
+"Deploy my metadata changes"
+→ Uses reload_all
+```
+
+## Security Notes
+
+- All operations go through Enfyra's REST API
+- Authentication is required (JWT token with auto-refresh)
+- Permissions are enforced by Enfyra's auth system
+- Pre/Post hooks and RLS are applied to all queries

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@enfyra/mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
+  "type": "module",
+  "license": "MIT",
+  "main": "src/index.mjs",
+  "bin": "src/index.mjs",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.mjs",
+    "dev": "node --watch src/index.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^17.3.1",
+    "zod": "^3.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * Enfyra MCP Server - Main Entry Point
+ *
+ * Provides tools to manage Enfyra instance via Claude Code.
+ * All operations go through Enfyra's REST API.
+ */
+
+import { config } from 'dotenv';
+config();
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+// Configuration
+const ENFYRA_API_URL = process.env.ENFYRA_API_URL || 'http://localhost:3000/api';
+const ENFYRA_EMAIL = process.env.ENFYRA_EMAIL || '';
+const ENFYRA_PASSWORD = process.env.ENFYRA_PASSWORD || '';
+
+// Import modules
+import { login, refreshAccessToken, getValidToken, resetTokens, getTokenExpiry, initAuth } from './lib/auth.js';
+import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
+import { registerTableTools } from './lib/table-tools.js';
+
+// Initialize auth module
+initAuth(ENFYRA_API_URL, ENFYRA_EMAIL, ENFYRA_PASSWORD);
+
+// Create MCP server
+const server = new McpServer({
+  name: 'enfyra-mcp',
+  version: '1.0.0',
+});
+
+// ============================================================================
+// METADATA TOOLS
+// ============================================================================
+
+server.tool('get_all_metadata', 'Get all metadata (tables, columns, relations, routes, hooks, etc.) from Enfyra', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/metadata');
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('get_table_metadata', 'Get metadata for a specific table by name', {
+  tableName: z.string().describe('Table name (e.g., "user_definition", "route_definition")'),
+}, async ({ tableName }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, `/metadata/${tableName}`);
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+// ============================================================================
+// QUERY TOOLS
+// ============================================================================
+
+server.tool('query_table', 'Query any table in Enfyra with filters, sorting, and pagination', {
+  tableName: z.string().describe('Table name to query'),
+  filter: z.string().optional().describe('Filter object as JSON string. Examples: \'{"status": {"_eq": "active"}}\''),
+  sort: z.string().optional().describe('Sort field. Prefix with - for descending (e.g., "createdAt", "-id")'),
+  page: z.number().optional().describe('Page number (default: 1)'),
+  limit: z.number().optional().describe('Items per page (default: 50, max: 500)'),
+  fields: z.array(z.string()).optional().describe('Fields to select'),
+}, async ({ tableName, filter, sort, page, limit, fields }) => {
+  validateTableName(tableName);
+  validateFilter(filter);
+
+  const queryParams = new URLSearchParams();
+  if (filter) queryParams.set('filter', filter);
+  if (sort) queryParams.set('sort', sort);
+  if (page) queryParams.set('page', String(page));
+  if (limit) queryParams.set('limit', String(limit));
+  if (fields) queryParams.set('fields', fields.join(','));
+
+  const query = queryParams.toString();
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}${query ? `?${query}` : ''}`);
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('find_one_record', 'Find a single record by ID or filter', {
+  tableName: z.string().describe('Table name'),
+  id: z.string().optional().describe('Record ID'),
+  filter: z.string().optional().describe('Filter as JSON string to find by'),
+}, async ({ tableName, id, filter }) => {
+  validateTableName(tableName);
+  if (id) {
+    const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  }
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}?filter=${filter}&limit=1`);
+  return { content: [{ type: 'text', text: JSON.stringify(result.data?.[0] || null, null, 2) }] };
+});
+
+// ============================================================================
+// CRUD TOOLS
+// ============================================================================
+
+server.tool('create_record', 'Create a new record in any table', {
+  tableName: z.string().describe('Table name to insert into'),
+  data: z.string().describe('Record data as JSON string'),
+}, async ({ tableName, data }) => {
+  validateTableName(tableName);
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}`, { method: 'POST', body: data });
+  return { content: [{ type: 'text', text: `Record created:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('update_record', 'Update an existing record by ID using PATCH', {
+  tableName: z.string().describe('Table name'),
+  id: z.string().describe('Record ID to update'),
+  data: z.string().describe('Fields to update as JSON string'),
+}, async ({ tableName, id, data }) => {
+  validateTableName(tableName);
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'PATCH', body: data });
+  return { content: [{ type: 'text', text: `Record updated:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('delete_record', 'Delete a record by ID', {
+  tableName: z.string().describe('Table name'),
+  id: z.string().describe('Record ID to delete'),
+}, async ({ tableName, id }) => {
+  validateTableName(tableName);
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'DELETE' });
+  return { content: [{ type: 'text', text: `Record deleted:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+// ============================================================================
+// ROUTE & HANDLER TOOLS
+// ============================================================================
+
+server.tool('get_all_routes', 'Get all route definitions with handlers, hooks, and permissions', {
+  includeDisabled: z.boolean().optional().default(false).describe('Include disabled routes'),
+}, async ({ includeDisabled }) => {
+  const filter = includeDisabled ? {} : { isEnabled: { _eq: true } };
+  const result = await fetchAPI(ENFYRA_API_URL, `/route_definition?filter=${encodeURIComponent(JSON.stringify(filter))}&limit=500`);
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('create_route', 'Create a new route definition', {
+  path: z.string().describe('Route path (e.g., "/api/users")'),
+  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'REST', 'GQL_QUERY', 'GQL_MUTATION']).describe('HTTP method'),
+  tableId: z.string().describe('Main table ID for this route'),
+  isEnabled: z.boolean().optional().default(true).describe('Enable route'),
+  description: z.string().optional().describe('Route description'),
+}, async ({ path, method, tableId, isEnabled, description }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/route_definition', {
+    method: 'POST',
+    body: JSON.stringify({ path, method, tableId, isEnabled, description }),
+  });
+  return { content: [{ type: 'text', text: `Route created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('create_handler', 'Create a handler for a route. Use template syntax: @BODY, @USER, #table_name, @THROW404', {
+  routeId: z.string().describe('Route definition ID'),
+  logic: z.string().describe('Handler logic (JavaScript code)'),
+  timeout: z.number().optional().describe('Handler timeout in ms (default: 30000)'),
+}, async ({ routeId, logic, timeout }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/route_handler_definition', {
+    method: 'POST',
+    body: JSON.stringify({ routeId, logic, timeout: timeout || 30000 }),
+  });
+  return { content: [{ type: 'text', text: `Handler created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('create_pre_hook', 'Create a pre-hook for a route. Use template syntax: @BODY, @QUERY, @USER', {
+  routeId: z.string().describe('Route definition ID'),
+  code: z.string().describe('Hook code (JavaScript)'),
+  methods: z.array(z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])).optional().describe('Methods this hook applies to'),
+  order: z.number().optional().default(0).describe('Hook execution order'),
+}, async ({ routeId, code, methods, order }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/pre_hook_definition', {
+    method: 'POST',
+    body: JSON.stringify({ routeId, code, methods: methods || ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], order }),
+  });
+  return { content: [{ type: 'text', text: `Pre-hook created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('create_post_hook', 'Create a post-hook for a route. Use template syntax: @DATA, @STATUS', {
+  routeId: z.string().describe('Route definition ID'),
+  code: z.string().describe('Hook code (JavaScript)'),
+  methods: z.array(z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])).optional().describe('Methods this hook applies to'),
+  order: z.number().optional().default(0).describe('Hook execution order'),
+}, async ({ routeId, code, methods, order }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/post_hook_definition', {
+    method: 'POST',
+    body: JSON.stringify({ routeId, code, methods: methods || ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], order }),
+  });
+  return { content: [{ type: 'text', text: `Post-hook created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+// Register table tools
+registerTableTools(server, ENFYRA_API_URL);
+
+// ============================================================================
+// CACHE & SYSTEM TOOLS
+// ============================================================================
+
+server.tool('reload_all', 'Reload all caches (metadata, routes, swagger, GraphQL)', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload', { method: 'POST' });
+  return { content: [{ type: 'text', text: `System reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('reload_metadata', 'Reload metadata cache only', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' });
+  return { content: [{ type: 'text', text: `Metadata reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('reload_routes', 'Reload routes cache only', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
+  return { content: [{ type: 'text', text: `Routes reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('reload_swagger', 'Reload Swagger/OpenAPI spec', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/swagger', { method: 'POST' });
+  return { content: [{ type: 'text', text: `Swagger reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('reload_graphql', 'Reload GraphQL schema', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/graphql', { method: 'POST' });
+  return { content: [{ type: 'text', text: `GraphQL reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+// ============================================================================
+// LOGS TOOLS
+// ============================================================================
+
+server.tool('get_log_files', 'List available log files and stats', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/logs');
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('get_log_content', 'Get content of a specific log file', {
+  filename: z.string().describe('Log file name'),
+  page: z.number().optional().default(1).describe('Page number'),
+  pageSize: z.number().optional().default(100).describe('Lines per page'),
+  filter: z.string().optional().describe('Text filter'),
+  level: z.string().optional().describe('Log level filter (INFO, WARN, ERROR)'),
+}, async ({ filename, page, pageSize, filter, level }) => {
+  const queryParams = new URLSearchParams();
+  if (page) queryParams.set('page', String(page));
+  if (pageSize) queryParams.set('pageSize', String(pageSize));
+  if (filter) queryParams.set('filter', filter);
+  if (level) queryParams.set('level', level);
+  const result = await fetchAPI(ENFYRA_API_URL, `/logs/${filename}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`);
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('tail_log', 'Get last N lines from a log file', {
+  filename: z.string().describe('Log file name'),
+  lines: z.number().optional().default(50).describe('Number of lines to retrieve'),
+}, async ({ filename, lines }) => {
+  const result = await fetchAPI(ENFYRA_API_URL, `/logs/${filename}/tail?lines=${lines}`);
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('search_logs', 'Search for ERROR or WARN logs across recent log files', {
+  level: z.enum(['ERROR', 'WARN', 'INFO']).optional().default('ERROR').describe('Log level'),
+  keyword: z.string().optional().describe('Keyword to filter logs'),
+  limit: z.number().optional().default(50).describe('Max results per level'),
+}, async ({ level, keyword, limit }) => {
+  const logFilesResult = await fetchAPI(ENFYRA_API_URL, '/logs');
+  const logFiles = logFilesResult.files || [];
+  const recentFiles = logFiles.filter(f => f.name.includes('app-') || f.name.includes('error-'));
+  const results = [];
+  for (const file of recentFiles.slice(0, 3)) {
+    try {
+      const contentResult = await fetchAPI(ENFYRA_API_URL, `/logs/${file.name}?level=${level}&pageSize=${limit}`);
+      const lines = contentResult.lines || contentResult.data || [];
+      const filteredLines = keyword ? lines.filter(l => JSON.stringify(l).toLowerCase().includes(keyword.toLowerCase())) : lines;
+      if (filteredLines.length > 0) results.push({ file: file.name, level, logs: filteredLines });
+    } catch (e) { /* skip */ }
+  }
+  return { content: [{ type: 'text', text: `Found ${results.length} files:\n${JSON.stringify(results, null, 2)}` }] };
+});
+
+// ============================================================================
+// AUTH & USER TOOLS
+// ============================================================================
+
+server.tool('get_current_user', 'Get current authenticated user info', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/me');
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('get_all_roles', 'Get all role definitions', {}, async () => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/role_definition?limit=100');
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+});
+
+server.tool('login', 'Force login to Enfyra and get new tokens', {
+  email: z.string().email().optional().describe('Admin email'),
+  password: z.string().optional().describe('Password'),
+}, async ({ email, password }) => {
+  const loginEmail = email || ENFYRA_EMAIL;
+  const loginPassword = password || ENFYRA_PASSWORD;
+  if (!loginEmail || !loginPassword) throw new Error('Email and password required');
+  await login(ENFYRA_API_URL, loginEmail, loginPassword);
+  return { content: [{ type: 'text', text: `Logged in successfully!\nToken expires: ${new Date(getTokenExpiry()).toISOString()}` }] };
+});
+
+// ============================================================================
+// MENU & EXTENSION TOOLS
+// ============================================================================
+
+server.tool('create_menu', 'Create a menu item in the navigation', {
+  label: z.string().describe('Menu label'),
+  type: z.enum(['separator', 'link', 'route', 'dropdown', 'widget', 'extension']).describe('Menu type'),
+  icon: z.string().optional().describe('Lucide icon name'),
+  path: z.string().optional().describe('Route path for type=route'),
+  externalUrl: z.string().optional().describe('External URL for type=link'),
+  order: z.number().optional().default(0).describe('Display order'),
+  isEnabled: z.boolean().optional().default(true).describe('Enable menu'),
+  description: z.string().optional().describe('Menu description'),
+}, async (data) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/menu_definition', { method: 'POST', body: JSON.stringify(data) });
+  return { content: [{ type: 'text', text: `Menu created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+server.tool('create_extension', 'Create a code extension (custom UI page or widget)', {
+  name: z.string().describe('Extension name (unique)'),
+  type: z.enum(['page', 'widget']).describe('Extension type'),
+  code: z.string().describe('Component code as string (React/Vue)'),
+  routePath: z.string().optional().describe('Route path for page type'),
+  menuLabel: z.string().optional().describe('Menu label (auto-creates menu)'),
+  menuIcon: z.string().optional().describe('Menu icon'),
+  isEnabled: z.boolean().optional().default(true).describe('Enable extension'),
+  description: z.string().optional().describe('Extension description'),
+}, async (data) => {
+  const result = await fetchAPI(ENFYRA_API_URL, '/extension_definition', { method: 'POST', body: JSON.stringify(data) });
+  return { content: [{ type: 'text', text: `Extension created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+});
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+async function main() {
+  console.error('Starting Enfyra MCP Server...');
+  console.error(`API URL: ${ENFYRA_API_URL}`);
+  console.error(`Auth: ${ENFYRA_EMAIL ? `Configured (${ENFYRA_EMAIL})` : 'Not configured'}`);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('Enfyra MCP Server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/src/lib/auth.js

@@ -0,0 +1,154 @@
+/**
+ * Authentication module for Enfyra MCP Server
+ * Handles login, token refresh, and token validation
+ */
+
+// Token state
+let accessToken = null;
+let refreshToken = null;
+let tokenExpiry = null; // expTime từ server (milliseconds)
+let isRefreshing = false;
+
+// Config
+let API_URL = 'http://localhost:3000/api';
+let EMAIL = '';
+let PASSWORD = '';
+
+// Refresh buffer: refresh token 1 minute before expiry
+const TOKEN_REFRESH_BUFFER = 60000;
+
+/**
+ * Initialize auth module with config
+ */
+export function initAuth(apiUrl, email, password) {
+  API_URL = apiUrl;
+  EMAIL = email;
+  PASSWORD = password;
+}
+
+/**
+ * Check if token needs refresh (expires within 1 minute)
+ */
+export function needsRefresh() {
+  if (!tokenExpiry) return true;
+  const now = Date.now();
+  return now + TOKEN_REFRESH_BUFFER >= tokenExpiry;
+}
+
+/**
+ * Get current access token (does not refresh)
+ */
+export function getAccessToken() {
+  return accessToken;
+}
+
+/**
+ * Get token expiry time
+ */
+export function getTokenExpiry() {
+  return tokenExpiry;
+}
+
+/**
+ * Login and get access + refresh tokens
+ */
+export async function login(url, email, password) {
+  const apiUrl = url || API_URL;
+  const authEmail = email || EMAIL;
+  const authPassword = password || PASSWORD;
+
+  if (!authEmail || !authPassword) {
+    throw new Error('Email and password required');
+  }
+
+  console.error('[Auth] Logging in...');
+  const response = await fetch(`${apiUrl}/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email: authEmail, password: authPassword }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Login failed: ${await response.text()}`);
+  }
+
+  const data = await response.json();
+  accessToken = data.accessToken || data.access_token;
+  refreshToken = data.refreshToken || data.refresh_token;
+  tokenExpiry = data.expTime;
+
+  console.error(`[Auth] Logged in as ${authEmail}, token expires at ${new Date(tokenExpiry).toISOString()}`);
+  return accessToken;
+}
+
+/**
+ * Refresh access token using refresh token
+ */
+export async function refreshAccessToken(url, email, password) {
+  const apiUrl = url || API_URL;
+  const authEmail = email || EMAIL;
+  const authPassword = password || PASSWORD;
+
+  if (isRefreshing) {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    return accessToken;
+  }
+
+  if (!refreshToken) {
+    console.error('[Auth] No refresh token, performing fresh login');
+    return await login(apiUrl, authEmail, authPassword);
+  }
+
+  isRefreshing = true;
+  try {
+    console.error('[Auth] Refreshing token...');
+    const response = await fetch(`${apiUrl}/auth/refresh-token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    });
+
+    if (!response.ok) {
+      console.error('[Auth] Refresh failed, logging in fresh');
+      refreshToken = null;
+      return await login(apiUrl, authEmail, authPassword);
+    }
+
+    const data = await response.json();
+    accessToken = data.accessToken || data.access_token;
+    refreshToken = data.refreshToken || data.refresh_token;
+    tokenExpiry = data.expTime;
+
+    console.error(`[Auth] Token refreshed, expires at ${new Date(tokenExpiry).toISOString()}`);
+    return accessToken;
+  } finally {
+    isRefreshing = false;
+  }
+}
+
+/**
+ * Get valid access token, refreshing if needed
+ */
+export async function getValidToken(url, email, password) {
+  const apiUrl = url || API_URL;
+  const authEmail = email || EMAIL;
+  const authPassword = password || PASSWORD;
+
+  if (!accessToken || needsRefresh()) {
+    if (refreshToken) {
+      return await refreshAccessToken(apiUrl, authEmail, authPassword);
+    }
+    return await login(apiUrl, authEmail, authPassword);
+  }
+  return accessToken;
+}
+
+/**
+ * Reset token state (for logout)
+ */
+export function resetTokens() {
+  accessToken = null;
+  refreshToken = null;
+  tokenExpiry = null;
+  isRefreshing = false;
+}

package/src/lib/fetch.js

@@ -0,0 +1,103 @@
+/**
+ * HTTP client module for Enfyra MCP Server
+ * Handles API requests with auth, timeout, and error handling
+ */
+
+import { getValidToken } from './auth.js';
+
+// Timeout configuration
+const FETCH_TIMEOUT = 30000; // 30 seconds
+
+/**
+ * Make HTTP request to Enfyra API
+ * @param {string} apiUrl - Base API URL
+ * @param {string} path - Request path
+ * @param {object} options - Fetch options
+ * @returns {Promise<any>} Response data
+ */
+export async function fetchAPI(apiUrl, path, options = {}) {
+  const url = `${apiUrl}${path}`;
+  const token = await getValidToken();
+
+  const headersList = [
+    ['Content-Type', 'application/json'],
+    ['Authorization', `Bearer ${token}`],
+  ];
+
+  if (options.headers) {
+    const optHeaders = options.headers;
+    for (const key of Object.keys(optHeaders)) {
+      const existingIdx = headersList.findIndex(h => h[0] === key);
+      if (existingIdx >= 0) {
+        headersList[existingIdx] = [key, optHeaders[key]];
+      } else {
+        headersList.push([key, optHeaders[key]]);
+      }
+    }
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+  try {
+    const res = await fetch(url, {
+      ...options,
+      headers: headersList,
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (!res.ok) {
+      const error = await res.text().catch(() => res.statusText);
+      throw new Error(`API error (${res.status}): ${error}`);
+    }
+
+    return res.json();
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error.name === 'AbortError') {
+      throw new Error(`Request timeout after ${FETCH_TIMEOUT}ms`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validate filter JSON and check for injection patterns
+ * @param {string} filterStr - Filter JSON string
+ * @returns {object|null} Parsed filter object
+ */
+export function validateFilter(filterStr) {
+  if (!filterStr) return null;
+  try {
+    const parsed = JSON.parse(filterStr);
+    // Check depth limit (max 10 levels)
+    function checkDepth(obj, depth = 0) {
+      if (depth > 10) {
+        throw new Error('Filter depth exceeds maximum of 10 levels');
+      }
+      if (obj && typeof obj === 'object') {
+        for (const key of Object.keys(obj)) {
+          checkDepth(obj[key], depth + 1);
+        }
+      }
+    }
+    checkDepth(parsed);
+    return parsed;
+  } catch (e) {
+    if (e.message.includes('depth')) throw e;
+    throw new Error(`Invalid filter JSON: ${e.message}`);
+  }
+}
+
+/**
+ * Validate table name (alphanumeric, underscores only)
+ * @param {string} tableName - Table name to validate
+ * @returns {string} Validated table name
+ */
+export function validateTableName(tableName) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+    throw new Error(`Invalid table name: ${tableName}. Must start with letter/underscore and contain only alphanumeric characters and underscores.`);
+  }
+  return tableName;
+}

package/src/lib/table-tools.js

@@ -0,0 +1,66 @@
+/**
+ * Table & Column tools for Enfyra MCP Server
+ */
+import { z } from 'zod';
+import { fetchAPI, validateTableName } from './fetch.js';
+
+/**
+ * Register table tools with MCP server
+ */
+export function registerTableTools(server, ENFYRA_API_URL) {
+  server.tool(
+    'get_all_tables',
+    'Get all table definitions in the system',
+    {},
+    async () => {
+      const result = await fetchAPI(ENFYRA_API_URL, '/table_definition?limit=500');
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  server.tool(
+    'create_table',
+    'Create a new table definition. After creating a table, use create_column to add columns.',
+    {
+      name: z.string().describe('Table name (e.g., "user_definition", "my_custom_table"). Must be unique, lowercase with underscores.'),
+      alias: z.string().optional().describe('Table alias for API. If not provided, the table name will be used.'),
+      description: z.string().optional().describe('Description of what this table stores.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable table. Set to false to disable.'),
+    },
+    async ({ name, alias, description, isEnabled }) => {
+      const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
+        method: 'POST',
+        body: JSON.stringify({ name, alias, description, isEnabled }),
+      });
+      return {
+        content: [{ type: 'text', text: `Table created successfully with ID: ${result.id}. Next step: use create_column to add columns (tableId: ${result.id}).\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
+      };
+    }
+  );
+
+  server.tool(
+    'create_column',
+    'Create a column for an existing table. Columns cascade through table_definition.',
+    {
+      tableId: z.string().describe('Table definition ID (from get_all_tables or create_table).'),
+      name: z.string().describe('Column name (e.g., "title", "user_id"). Lowercase with underscores.'),
+      type: z.string().describe('Column type: varchar, int, text, boolean, datetime, json, decimal, etc.'),
+      length: z.number().optional().describe('Length for varchar types (e.g., 255).'),
+      isRequired: z.boolean().optional().default(false).describe('Set to true if column cannot be null.'),
+      isUnique: z.boolean().optional().default(false).describe('Set to true for unique constraint.'),
+      defaultValue: z.string().optional().describe('Default value as JSON string.'),
+      description: z.string().optional().describe('Column description.'),
+    },
+    async ({ tableId, name, type, length, isRequired, isUnique, defaultValue, description }) => {
+      const result = await fetchAPI(ENFYRA_API_URL, '/column_definition', {
+        method: 'POST',
+        body: JSON.stringify({ tableId, name, type, length, isRequired, isUnique, defaultValue, description }),
+      });
+      return {
+        content: [{ type: 'text', text: `Column created with ID: ${result.id}.\n\n${JSON.stringify(result, null, 2)}` }],
+      };
+    }
+  );
+}