@enfyra/mcp-server 0.0.86 → 0.0.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.86",
+  "version": "0.0.87",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -736,6 +736,81 @@ ensure_route_access({
           'Route permissions apply when the method is not public.',
         ],
       },
+      {
+        name: 'Rate limit anonymous requests by IP',
+        code: `create_guard({
+  name: "Public signup IP rate limit",
+  path: "/newsletter_signup",
+  methods: ["POST"],
+  position: "pre_auth",
+  isEnabled: true,
+  description: "Limit anonymous signup attempts by client IP.",
+  rules: JSON.stringify([
+    {
+      type: "rate_limit_by_ip",
+      config: { maxRequests: 10, perSeconds: 60 },
+      description: "10 signup attempts per minute per IP"
+    }
+  ])
+})
+
+inspect_route({ path: "/newsletter_signup" })
+
+test_rest_endpoint({
+  method: "POST",
+  path: "/newsletter_signup",
+  body: { email: "test@example.com" }
+})`,
+        notes: [
+          'Use pre_auth for anonymous/public route protection because no user is available yet.',
+          'Rate-limit configs use maxRequests and perSeconds.',
+          'Inspect and test after creation so the final behavior is verified through the actual REST route.',
+        ],
+      },
+      {
+        name: 'Rate limit authenticated users',
+        code: `create_guard({
+  name: "Project create per-user limit",
+  path: "/projects",
+  methods: ["POST"],
+  position: "post_auth",
+  isEnabled: true,
+  description: "Authenticated users can create at most 3 projects per hour.",
+  rules: JSON.stringify([
+    {
+      type: "rate_limit_by_user",
+      config: { maxRequests: 3, perSeconds: 3600 }
+    }
+  ])
+})`,
+        notes: [
+          'Use post_auth for rate_limit_by_user because the server only has user id after auth and RoleGuard.',
+          'This does not grant access; users still need route permissions or a public method to reach the route.',
+          'Do not put rate_limit_by_user on pre_auth guards; the server drops that rule from pre-auth trees.',
+        ],
+      },
+      {
+        name: 'Restrict an admin-only route to office IPs',
+        code: `create_guard({
+  name: "Admin reports office allowlist",
+  path: "/admin/reports",
+  methods: ["GET", "POST"],
+  position: "pre_auth",
+  isEnabled: false,
+  description: "Only office network IPs can reach admin reports.",
+  rules: JSON.stringify([
+    {
+      type: "ip_whitelist",
+      config: { ips: ["203.0.113.10", "198.51.100.0/24"] }
+    }
+  ])
+})`,
+        notes: [
+          'Create risky allowlists disabled first, then inspect the saved guard before enabling it.',
+          'IP list configs use ips; exact IPv4 addresses and IPv4 CIDR ranges are supported.',
+          'An allowlist is an additional gate, not a replacement for route permissions.',
+        ],
+      },
       {
         name: 'Column rule for email format',
         code: `create_column_rule({

package/src/lib/mcp-instructions.js

@@ -82,6 +82,16 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Right pattern:** **`create_route`** without `mainTableId` → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Handler/hook code must query explicit repos such as `$ctx.$repos.orders`; do not rely on `$repos.main` for custom routes.',
     '- **Handler contract:** `create_handler` takes `routeId`, `method` (or `methods` for batch), `sourceCode`, optional `scriptLanguage`, and optional `timeout`. Do **not** send `logic`, `name`, or `compiledCode`; backend CRUD rejects `logic` and `compiledCode` is generated by the server.',
     '',
+    '### Guards (request gates and rate limits)',
+    '- Guards are metadata-driven request gates stored in `enfyra_guard` and `enfyra_guard_rule`. Use them for IP allow/deny lists and coarse rate limits before writing custom pre-hooks. Use route permissions for authenticated access, field permissions for field access, and column rules for request body validation.',
+    '- Guard execution positions: `pre_auth` runs before JWT/auth and only has client IP + route/method context; use it for anonymous/IP/route-wide gates such as `rate_limit_by_ip`, `rate_limit_by_route`, `ip_whitelist`, and `ip_blacklist`. `post_auth` runs after auth/RoleGuard and has the authenticated user id; use it for `rate_limit_by_user` or rules scoped to specific users.',
+    '- Rule types: `rate_limit_by_ip`, `rate_limit_by_user`, `rate_limit_by_route`, `ip_whitelist`, and `ip_blacklist`. Rate-limit rule config is `{"maxRequests": number, "perSeconds": number}`. IP list config is `{"ips": ["203.0.113.10", "198.51.100.0/24"]}`; CIDR matching is IPv4-oriented.',
+    '- Root guards can attach to one route through `path` or `routeId`, or globally with `isGlobal: true`. `methods` is an array of HTTP method names; omit it to apply the guard to all methods on that route/global scope. Child guards inherit the root `position`; only root guard `position`, `route`, `methods`, and `isGlobal` determine where it runs.',
+    '- Guard `combinator` controls evaluation: `and` rejects on the first failing rule/child; `or` allows when any rule/child passes and rejects only if all fail. Lower `priority` runs first among sibling guards/rules.',
+    '- `create_guard` defaults `isEnabled` to `false` to avoid lockouts. For risky global or IP whitelist guards, create disabled first, inspect the saved guard/rules, then enable only after the rule config and route/method scope are confirmed.',
+    '- `create_guard` reloads guard cache best-effort after creation. After changing guard metadata, verify behavior with `inspect_route({ path })` and `test_rest_endpoint`; use `/admin/reload/guards` only when verification shows stale guard behavior.',
+    '- Do not use `rate_limit_by_user` or user-scoped rule `userIds` on `pre_auth` guards. Server guard cache drops `rate_limit_by_user` from pre-auth trees and ignores user scopes there because no user exists yet.',
+    '',
     '### After a new table is created',
     '- MCP **`create_table` supports creating columns and relations in the same call**: pass `columns` and `relations` as JSON arrays. Use `create_relation` only when adding a relation to an existing table later.',
     '- MCP **`create_table` supports `isSingleRecord` directly**. Set `isSingleRecord: true` in the create call for settings/config tables that should keep only one record; do not create first and then patch only for this flag.',

package/src/mcp-server-entry.mjs

@@ -2593,11 +2593,13 @@ server.tool(
   'create_guard',
   [
     'Create a metadata guard with optional rules for REST request gating.',
-    'Root guards attach to route or global position. Rule configs: rate limits use {"maxRequests":number,"perSeconds":number}; IP lists use {"ips":["127.0.0.1"]}.',
+    'Root guards attach to one route by path/routeId or globally with isGlobal. pre_auth runs before JWT and only has IP/route context; post_auth runs after auth and can use user id.',
+    'Rule types: rate_limit_by_ip, rate_limit_by_user, rate_limit_by_route, ip_whitelist, ip_blacklist. Rate limits use {"maxRequests":number,"perSeconds":number}; IP lists use {"ips":["127.0.0.1","10.0.0.0/24"]}.',
+    'Do not use rate_limit_by_user or userIds on pre_auth guards. Create risky global/IP whitelist guards disabled first, then inspect and test before enabling.',
   ].join(' '),
   {
     name: z.string().describe('Guard name'),
-    position: z.enum(['pre_auth', 'post_auth']).default('pre_auth').describe('Execution position for root guard'),
+    position: z.enum(['pre_auth', 'post_auth']).default('pre_auth').describe('Execution position for root guard. pre_auth has only IP/route context; post_auth also has authenticated user id.'),
     routeId: z.union([z.string(), z.number()]).optional().describe('Optional route id'),
     path: z.string().optional().describe('Optional route path'),
     methods: z.array(z.string()).optional().describe('Method names this guard applies to. Empty means all configured behavior for route/global.'),
@@ -2606,7 +2608,7 @@ server.tool(
     isGlobal: z.boolean().optional().default(false).describe('Apply globally instead of one route'),
     isEnabled: z.boolean().optional().default(false).describe('Enable immediately. Default false to avoid accidental lockout.'),
     description: z.string().optional().describe('Admin note'),
-    rules: z.string().optional().describe('Optional rules JSON array: [{type, config, priority?, isEnabled?, description?, userIds?}]'),
+    rules: z.string().optional().describe('Optional rules JSON array: [{type, config, priority?, isEnabled?, description?, userIds?}]. Supported types: rate_limit_by_ip, rate_limit_by_user, rate_limit_by_route, ip_whitelist, ip_blacklist.'),
   },
   async ({ name, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules }) => {
     let route = null;