@enfyra/mcp-server 0.0.1 → 0.0.2

package/README.md

@@ -1,22 +1,12 @@
 # Enfyra MCP Server
 
-MCP (Model Context Protocol) server for managing Enfyra instances via Claude Code.
+MCP server for managing Enfyra instances from **Claude Code** (and other MCP clients). All operations go through Enfyra's REST API.
 
-## Features
+**LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`) and tool descriptions in **`src/index.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
 
-- **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
+## Install in Claude Code
 
-## Add to Claude Code
-
-### Method 1: Global Configuration (Recommended)
-
-Edit `~/.claude.json` and add to the `mcpServers` section:
+Edit `~/.claude.json` and add to `mcpServers`:
 
 ```json
 {
@@ -34,82 +24,21 @@ Edit `~/.claude.json` and add to the `mcpServers` section:
 }
 ```
 
-**Important**:
-- The `-y` flag automatically confirms installation
-- After updating config, restart Claude Code for changes to take effect
+- `-y`: auto-confirm package install without prompting.
+- **Restart Claude Code** after updating config.
+
+**Local dev (running this repo):** use `node` with path to `src/index.mjs`; see `.mcp.json` in the project.
 
 | 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
+| `ENFYRA_API_URL` | API base URL (usually includes `/api`) | `http://localhost:3000/api` |
+| `ENFYRA_EMAIL` | Admin email | — |
+| `ENFYRA_PASSWORD` | Admin password | — |
 
-### 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
+## Tools (summary)
 
-### 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
-```
+Metadata, query/CRUD, route/handler/hook, tables/columns, reload cache, logs, user/roles, login, menu/extension, `get_enfyra_api_context`. For full tool list and behavior, see the app after enabling MCP or the source in `src/index.mjs`.
 
-## Security Notes
+## Security
 
-- 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
+API calls use JWT (MCP auto-refreshes). Permissions are enforced by Enfyra.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -21,16 +21,22 @@ 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 { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.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',
-});
+// Create MCP server — `instructions` is sent to the host (e.g. Claude Code) for the LLM; not README
+const server = new McpServer(
+  {
+    name: 'enfyra-mcp',
+    version: '1.0.0',
+  },
+  {
+    instructions: buildMcpServerInstructions(ENFYRA_API_URL),
+  },
+);
 
 // ============================================================================
 // METADATA TOOLS
@@ -52,6 +58,40 @@ server.tool('get_table_metadata', 'Get metadata for a specific table by name', {
 // QUERY TOOLS
 // ============================================================================
 
+server.tool(
+  'get_enfyra_api_context',
+  [
+    'Returns the resolved API base URL for this MCP session (env ENFYRA_API_URL).',
+    'Use when the user asks which HTTP endpoint or full URL applies: combine enfyraApiUrl with paths from server instructions (GET/POST /{table}, PATCH/DELETE /{table}/{id}, no GET /{table}/{id}).',
+    'Auth: publishedMethods on a route can allow a method without Bearer; otherwise JWT + routePermissions — see server instructions.',
+    'If path might differ from table name, use get_all_routes before asserting a URL.',
+    'Same mapping as MCP tool → HTTP: query_table=GET /table?..., create_record=POST /table, update_record=PATCH /table/id, delete_record=DELETE /table/id.',
+    'GraphQL: see graphqlHttpUrl / graphqlSchemaUrl in response; GQL_QUERY vs GQL_MUTATION in publishedMethods — server instructions.',
+  ].join(' '),
+  {},
+  async () => {
+    const base = ENFYRA_API_URL.replace(/\/$/, '');
+    const gql = buildGraphqlUrls(ENFYRA_API_URL);
+    const payload = {
+      enfyraApiUrl: base,
+      graphqlHttpUrl: gql.graphqlHttpUrl,
+      graphqlSchemaUrl: gql.graphqlSchemaUrl,
+      examples: {
+        listOrCreate: `${base}/<table_name>`,
+        updateOrDelete: `${base}/<table_name>/<id>`,
+        oneRowById: `${base}/<table_name>?filter={"id":{"_eq":"<id>"}}&limit=1`,
+      },
+      auth: {
+        publishedMethods: 'If the HTTP method is published for that route, no Bearer required; else Bearer JWT and routePermissions apply.',
+        mcp: 'This server uses admin credentials from env for tools (fetchAPI).',
+      },
+      pathResolution: 'Confirm route path with get_all_routes or metadata — path may not equal table name.',
+      note: 'Full tool→HTTP mapping is in MCP server instructions (shown to the model at connect).',
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  },
+);
+
 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"}}\''),
@@ -75,19 +115,35 @@ server.tool('query_table', 'Query any table in Enfyra with filters, sorting, and
   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) }] };
-});
+server.tool(
+  'find_one_record',
+  'Find a single record by ID or filter. By ID uses GET with filter (Enfyra has no GET /table/:id route).',
+  {
+    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) {
+      // Enfyra route engine does not register GET /<table>/:id (only PATCH/DELETE use /:id). Use list + filter.
+      const filterObj = JSON.stringify({ id: { _eq: id } });
+      const result = await fetchAPI(
+        ENFYRA_API_URL,
+        `/${tableName}?filter=${encodeURIComponent(filterObj)}&limit=1`,
+      );
+      const one = result.data?.[0] ?? null;
+      return { content: [{ type: 'text', text: JSON.stringify(one, null, 2) }] };
+    }
+    if (!filter) throw new Error('Provide id or filter');
+    validateFilter(filter);
+    const result = await fetchAPI(
+      ENFYRA_API_URL,
+      `/${tableName}?filter=${encodeURIComponent(filter)}&limit=1`,
+    );
+    return { content: [{ type: 'text', text: JSON.stringify(result.data?.[0] || null, null, 2) }] };
+  },
+);
 
 // ============================================================================
 // CRUD TOOLS

package/src/lib/mcp-instructions.js

@@ -0,0 +1,73 @@
+/**
+ * MCP server `instructions` — surfaced to the host (e.g. Claude Code) for the LLM.
+ * Single source of truth for API/REST/GraphQL/auth/mutation naming; README does NOT feed the model.
+ * Maintain all assistant-facing rules here (and tool descriptions in index.mjs).
+ */
+
+/** GraphQL shares the same URL prefix as REST: `{ENFYRA_API_URL}/graphql` and `{ENFYRA_API_URL}/graphql-schema`. */
+export function buildGraphqlUrls(apiBaseUrl) {
+  const base = String(apiBaseUrl || '').replace(/\/$/, '');
+  return {
+    graphqlHttpUrl: `${base}/graphql`,
+    graphqlSchemaUrl: `${base}/graphql-schema`,
+  };
+}
+
+export function buildMcpServerInstructions(apiBaseUrl) {
+  const base = String(apiBaseUrl || '').replace(/\/$/, '');
+  const { graphqlHttpUrl, graphqlSchemaUrl } = buildGraphqlUrls(apiBaseUrl);
+  const getList = `${base}/<table_name>`;
+  const getOneById = `${base}/<table_name>?filter={"id":{"_eq":"<id>"}}&limit=1`;
+  const patchOne = `${base}/<table_name>/<id>`;
+  const delOne = `${base}/<table_name>/<id>`;
+  const examplePost = `${base}/post`;
+
+  return [
+    '## Enfyra API endpoints (answer user questions with these rules)',
+    '',
+    `**API base for this session:** \`${base}\` (from env ENFYRA_API_URL, no trailing slash).`,
+    `**Full URL:** base + path segment. Example for table \`post\`: \`${examplePost}\`.`,
+    '',
+    '### After a new table is created',
+    '- Enfyra creates a route at `/{table_name}` using the table **name** from `create_table` (not the alias).',
+    '- **Four REST HTTP operations** on that resource:',
+    `  - **GET** \`${getList}\` — list / filter (query: filter, sort, page, limit, fields, meta).`,
+    `  - **POST** \`${getList}\` — create (JSON body).`,
+    `  - **PATCH** \`${patchOne}\` — update one row.`,
+    `  - **DELETE** \`${delOne}\` — delete one row.`,
+    `- **No** **GET** \`${base}/<table_name>/<id>\`. For one row by id use **GET** \`${getOneById}\` or MCP \`query_table\` / \`find_one_record\`.`,
+    '',
+    '### Auth and publishedMethods (Enfyra server)',
+    '- Each route has **publishedMethods** (which HTTP verbs are “public”) and **routePermissions** (roles/users for protected access).',
+    '- If the **current request method** is listed in **publishedMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
+    '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
+    '- MCP tools that use `fetchAPI` authenticate with the configured admin credentials; explain to users that **direct HTTP** calls need a token unless the route/method is published.',
+    '',
+    '### Resolving the real REST path',
+    '- Do **not** assume `route_definition.path` always equals `table_definition.name`. Paths are data-driven (custom prefixes, renames, multiple routes per table).',
+    '- When unsure of the URL path, use MCP **`get_all_routes`** (or **`get_all_metadata`**) to read each route’s **path** and **mainTable** before stating a full URL.',
+    '',
+    '### MongoDB vs SQL primary key',
+    '- On **SQL**, filters often use **`id`**. On **MongoDB**, documents may use **`_id`** — a filter for one row might be `{"_id":{"_eq":"..."}}` instead of `id`, depending on metadata.',
+    '',
+    '### GraphQL (same prefix as REST / ENFYRA_API_URL)',
+    `- **POST** \`${graphqlHttpUrl}\` — GraphQL endpoint (body: GraphQL query). Example with default base: \`http://localhost:3000/api/graphql\`.`,
+    `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text), e.g. \`.../api/graphql-schema\`.`,
+    '- A table appears in the schema only if its route has **both** `GQL_QUERY` and `GQL_MUTATION` in `availableMethods`, `path` = `/<table_name>`, and `mainTable` set.',
+    '- **Query** field = same string as `table_definition.name`. **Mutations** are literal concat: `create_`+tableName, `update_`+tableName, `delete_`+tableName (e.g. tableName `post` → `create_post`, input type `postInput`). See `generate-type-defs.ts`. No mutations if no non-PK columns for input.',
+    '- **Auth:** `publishedMethods` may include `GQL_QUERY` and/or `GQL_MUTATION` **separately** — each controls anonymous access for queries vs mutations. Otherwise Bearer JWT + `routePermissions` must list the same method key (`GQL_QUERY` / `GQL_MUTATION`).',
+    '- MCP does not wrap GraphQL; use REST tools or tell users the URLs above.',
+    '',
+    '### MCP tool → HTTP',
+    `- \`get_all_metadata\` → GET \`${base}/metadata\``,
+    `- \`get_table_metadata\` → GET \`${base}/metadata/<tableName>\``,
+    `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args)`,
+    `- \`find_one_record\` (by id) → GET \`${base}/<tableName>?filter=…&limit=1\``,
+    `- \`create_record\` → POST \`${base}/<tableName>\``,
+    `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\``,
+    `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\``,
+    `- Other admin paths include \`${base}/route_definition\`, \`${base}/admin/reload\`, etc.`,
+    '',
+    'When asked which endpoint the API calls, respond with **HTTP method + full URL** using this base. Call `get_enfyra_api_context` to confirm the resolved base if needed.',
+  ].join('\n');
+}

package/src/lib/table-tools.js

@@ -8,6 +8,7 @@ import { fetchAPI, validateTableName } from './fetch.js';
  * Register table tools with MCP server
  */
 export function registerTableTools(server, ENFYRA_API_URL) {
+  const apiBase = ENFYRA_API_URL.replace(/\/$/, '');
   server.tool(
     'get_all_tables',
     'Get all table definitions in the system',
@@ -22,7 +23,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
   server.tool(
     'create_table',
-    'Create a new table definition. After creating a table, use create_column to add columns.',
+    [
+      'Create a new table definition. After creating a table, use create_column to add columns.',
+      'Enfyra auto-creates a REST route at path `/<table_name>` (same segment as `name`, not alias).',
+      'REST surface for that route (matches server route engine): 4 HTTP operations — GET `/<table>` (list/filter), POST `/<table>` (create), PATCH `/<table>/:id` (update), DELETE `/<table>/:id` (delete).',
+      'There is NO `GET /<table>/:id`. To fetch one row by id, use GET `/<table>?filter={"id":{"_eq":"<id>"}}&limit=1` or tool query_table / find_one_record.',
+      `Full URLs: ${apiBase}/<table_name> (example table post: ${apiBase}/post).`,
+      'GraphQL (GQL_QUERY / GQL_MUTATION) may also be enabled on the route; that is separate from REST paths above.',
+    ].join(' '),
     {
       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.'),
@@ -34,8 +42,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         method: 'POST',
         body: JSON.stringify({ name, alias, description, isEnabled }),
       });
+      const base = ENFYRA_API_URL.replace(/\/$/, '');
+      const routePath = `/${name}`;
+      const restHint = [
+        `Auto route path: ${routePath} → full base for REST: ${base}${routePath}`,
+        `REST: GET+POST on ${routePath}; PATCH+DELETE on ${routePath}/:id only. No GET ${routePath}/:id.`,
+      ].join('\n');
       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)}` }],
+        content: [{ type: 'text', text: `Table created successfully with ID: ${result.id}. Next step: use create_column to add columns (tableId: ${result.id}).\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
     }
   );