envibe-mcp 0.1.0 → 0.2.0

package/README.md

@@ -66,7 +66,14 @@ This is the MCP server component of [envibe](https://github.com/dominic-righther
 | `env_list` | List visible variables with access levels |
 | `env_get` | Get a variable's value (respects permissions) |
 | `env_set` | Set a variable (only `full` access) |
-| `env_describe` | Get detailed info about a variable |
+| `env_describe` | Get detailed info including format and example |
+| `env_check_required` | Check which required variables are missing |
+
+### v0.2.0 Features
+
+- **Better error messages** - When access is denied, get helpful guidance
+- **Format hints** - Know what format a variable should be (url, key, number, etc.)
+- **Required var checking** - Use `env_check_required` to guide users through setup
 
 ## For CLI tools
 

package/dist/index.js

@@ -20603,193 +20603,245 @@ var CLASSIFICATION_PATTERNS = [
     name: "stripe-secret",
     pattern: /^STRIPE_SECRET/i,
     suggestedAccess: "hidden" /* HIDDEN */,
-    description: "Stripe secret key"
+    description: "Stripe secret key",
+    format: "key",
+    example: "sk_live_..."
   },
   {
     name: "private-key",
     pattern: /PRIVATE[_-]?KEY/i,
     suggestedAccess: "hidden" /* HIDDEN */,
-    description: "Private key material"
+    description: "Private key material",
+    format: "pem",
+    example: "-----BEGIN PRIVATE KEY-----..."
   },
   {
     name: "signing-secret",
     pattern: /SIGNING[_-]?SECRET/i,
     suggestedAccess: "hidden" /* HIDDEN */,
-    description: "Signing secret"
+    description: "Signing secret",
+    format: "key"
   },
   {
     name: "api-key",
     pattern: /API[_-]?KEY/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "API key"
+    description: "API key",
+    format: "key",
+    example: "sk-..."
   },
   {
     name: "secret-key",
     pattern: /SECRET[_-]?KEY/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Secret key"
+    description: "Secret key",
+    format: "key"
   },
   {
     name: "access-key",
     pattern: /ACCESS[_-]?KEY/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Access key"
+    description: "Access key",
+    format: "key",
+    example: "AKIA..."
   },
   {
     name: "auth-token",
     pattern: /AUTH[_-]?TOKEN/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Authentication token"
+    description: "Authentication token",
+    format: "token"
   },
   {
     name: "bearer-token",
     pattern: /BEARER[_-]?TOKEN/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Bearer token"
+    description: "Bearer token",
+    format: "token"
   },
   {
     name: "jwt-secret",
     pattern: /JWT[_-]?SECRET/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "JWT signing secret"
+    description: "JWT signing secret",
+    format: "key"
   },
   {
     name: "password",
     pattern: /PASSWORD/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Password credential"
+    description: "Password credential",
+    format: "password"
   },
   {
     name: "credential",
     pattern: /CREDENTIAL/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Credential"
+    description: "Credential",
+    format: "key"
   },
   {
     name: "secret",
     pattern: /SECRET/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Secret value"
+    description: "Secret value",
+    format: "key"
   },
   {
     name: "token",
     pattern: /TOKEN$/i,
     suggestedAccess: "placeholder" /* PLACEHOLDER */,
-    description: "Token"
+    description: "Token",
+    format: "token"
   },
   {
     name: "database-url",
     pattern: /DATABASE[_-]?URL/i,
-    suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "Database connection URL"
+    suggestedAccess: "placeholder" /* PLACEHOLDER */,
+    description: "Database connection URL (may contain password)",
+    format: "url",
+    example: "postgres://user:pass@localhost:5432/dbname"
   },
   {
     name: "redis-url",
     pattern: /REDIS[_-]?URL/i,
-    suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "Redis connection URL"
+    suggestedAccess: "placeholder" /* PLACEHOLDER */,
+    description: "Redis connection URL (may contain password)",
+    format: "url",
+    example: "redis://user:pass@localhost:6379/0"
   },
   {
     name: "mongodb-uri",
     pattern: /MONGO(DB)?[_-]?URI/i,
-    suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "MongoDB connection URI"
+    suggestedAccess: "placeholder" /* PLACEHOLDER */,
+    description: "MongoDB connection URI (may contain password)",
+    format: "url",
+    example: "mongodb://user:pass@localhost:27017/dbname"
   },
   {
     name: "connection-string",
     pattern: /CONNECTION[_-]?STRING/i,
-    suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "Connection string"
+    suggestedAccess: "placeholder" /* PLACEHOLDER */,
+    description: "Connection string (may contain password)",
+    format: "url"
   },
   {
     name: "url-suffix",
     pattern: /_URL$/i,
     suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "URL endpoint"
+    description: "URL endpoint",
+    format: "url",
+    example: "https://api.example.com"
   },
   {
     name: "uri-suffix",
     pattern: /_URI$/i,
     suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "URI endpoint"
+    description: "URI endpoint",
+    format: "url"
   },
   {
     name: "host",
     pattern: /_HOST$/i,
     suggestedAccess: "read-only" /* READ_ONLY */,
-    description: "Host address"
+    description: "Host address",
+    format: "hostname",
+    example: "localhost"
   },
   {
     name: "node-env",
     pattern: /^NODE_ENV$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Node.js environment mode"
+    description: "Node.js environment mode",
+    format: "enum",
+    example: "development | production | test"
   },
   {
     name: "env-suffix",
     pattern: /_ENV$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Environment setting"
+    description: "Environment setting",
+    format: "string"
   },
   {
     name: "debug",
     pattern: /DEBUG/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Debug flag"
+    description: "Debug flag",
+    format: "boolean",
+    example: "true | false"
   },
   {
     name: "log-level",
     pattern: /LOG[_-]?LEVEL/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Logging level"
+    description: "Logging level",
+    format: "enum",
+    example: "debug | info | warn | error"
   },
   {
     name: "port",
     pattern: /^PORT$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Server port"
+    description: "Server port",
+    format: "number",
+    example: "3000"
   },
   {
     name: "port-suffix",
     pattern: /_PORT$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Port number"
+    description: "Port number",
+    format: "number",
+    example: "5432"
   },
   {
     name: "timeout",
     pattern: /TIMEOUT/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Timeout setting"
+    description: "Timeout setting",
+    format: "number",
+    example: "30000"
   },
   {
     name: "max-size",
     pattern: /MAX[_-]?(SIZE|LENGTH|COUNT)/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Size/count limit"
+    description: "Size/count limit",
+    format: "number",
+    example: "100"
   },
   {
     name: "enable-disable",
     pattern: /(ENABLE|DISABLE)[_-]/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Feature flag"
+    description: "Feature flag",
+    format: "boolean",
+    example: "true | false"
   },
   {
     name: "feature-flag",
     pattern: /FEATURE[_-]/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Feature flag"
+    description: "Feature flag",
+    format: "boolean",
+    example: "true | false"
   },
   {
     name: "region",
     pattern: /_REGION$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Cloud region"
+    description: "Cloud region",
+    format: "string",
+    example: "us-east-1"
   },
   {
     name: "version",
     pattern: /_VERSION$/i,
     suggestedAccess: "full" /* FULL */,
-    description: "Version number"
+    description: "Version number",
+    format: "string",
+    example: "1.0.0"
   }
 ];
 function classifyVariable(name) {
@@ -20797,7 +20849,9 @@ function classifyVariable(name) {
     if (pattern.pattern.test(name)) {
       return {
         access: pattern.suggestedAccess,
-        description: pattern.description
+        description: pattern.description,
+        format: pattern.format,
+        example: pattern.example
       };
     }
   }
@@ -21149,6 +21203,10 @@ async function configureClaudeSettings(silent = false) {
     } else {
       console.log("     Already configured");
     }
+    console.log("");
+    console.log("  Recommended next steps:");
+    console.log("    → Add to .gitignore: .env.ai");
+    console.log("    → Review settings: npm i -g envibe && envibe view");
   }
   return { denyAdded, allowAdded, mcpConfigured, discoveredFiles };
 }
@@ -21287,7 +21345,7 @@ async function startMCPServer() {
         },
         {
           name: "env_describe",
-          description: "Get detailed information about a variable including its access level and description.",
+          description: "Get detailed information about a variable including its access level, description, format, and example.",
           inputSchema: {
             type: "object",
             properties: {
@@ -21298,6 +21356,14 @@ async function startMCPServer() {
             },
             required: ["key"]
           }
+        },
+        {
+          name: "env_check_required",
+          description: "Check which required environment variables are missing. Use this to help users set up their environment.",
+          inputSchema: {
+            type: "object",
+            properties: {}
+          }
         }
       ]
     };
@@ -21328,18 +21394,57 @@ async function startMCPServer() {
         }
         case "env_get": {
           const key = args.key;
+          const config2 = manifest2.variables[key];
           const variable = getVariableForAI(key, env, manifest2);
+          if (config2 && config2.access === "hidden" /* HIDDEN */) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "ACCESS_DENIED",
+                    key,
+                    access: "hidden",
+                    message: "This variable is hidden from AI. Ask the user to configure it manually.",
+                    hint: config2.description
+                  }, null, 2)
+                }
+              ],
+              isError: true
+            };
+          }
           if (!variable) {
             return {
               content: [
                 {
                   type: "text",
-                  text: `Error: Variable "${key}" is hidden or does not exist`
+                  text: JSON.stringify({
+                    error: "NOT_FOUND",
+                    key,
+                    message: `Variable "${key}" does not exist in the manifest.`
+                  }, null, 2)
                 }
               ],
               isError: true
             };
           }
+          if (variable.access === "placeholder" /* PLACEHOLDER */) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    value: variable.displayValue,
+                    access: "placeholder",
+                    message: "You can reference this variable but cannot see the actual value.",
+                    hint: config2?.description,
+                    format: config2?.format,
+                    example: config2?.example
+                  }, null, 2)
+                }
+              ]
+            };
+          }
           return {
             content: [
               {
@@ -21381,25 +21486,50 @@ async function startMCPServer() {
           const key = args.key;
           const variable = getVariableForAI(key, env, manifest2);
           const config2 = manifest2.variables[key];
-          if (!variable) {
+          if (config2 && config2.access === "hidden" /* HIDDEN */) {
             return {
               content: [
                 {
                   type: "text",
-                  text: `Error: Variable "${key}" is hidden or does not exist`
+                  text: JSON.stringify({
+                    key,
+                    access: "hidden",
+                    canModify: false,
+                    description: config2.description,
+                    message: "This variable is hidden from AI. Ask the user to configure it.",
+                    required: config2.required ?? false,
+                    format: config2.format,
+                    example: config2.example
+                  }, null, 2)
+                }
+              ]
+            };
+          }
+          if (!variable && !config2) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "NOT_FOUND",
+                    key,
+                    message: `Variable "${key}" does not exist in the manifest.`
+                  }, null, 2)
                 }
               ],
               isError: true
             };
           }
           const info = {
-            key: variable.key,
-            access: variable.access,
-            canModify: variable.canModify,
-            description: variable.description,
+            key: variable?.key ?? key,
+            access: variable?.access ?? config2?.access,
+            canModify: variable?.canModify ?? false,
+            description: variable?.description ?? config2?.description,
             required: config2?.required ?? false,
             hasDefault: config2?.default !== undefined,
-            isSet: env[key] !== undefined
+            isSet: env[key] !== undefined,
+            format: config2?.format,
+            example: config2?.example
           };
           return {
             content: [
@@ -21410,6 +21540,42 @@ async function startMCPServer() {
             ]
           };
         }
+        case "env_check_required": {
+          const missing = [];
+          const set2 = [];
+          for (const [key, config2] of Object.entries(manifest2.variables)) {
+            if (config2.required) {
+              if (env[key] === undefined || env[key] === "") {
+                missing.push({
+                  key,
+                  description: config2.description,
+                  format: config2.format,
+                  example: config2.example
+                });
+              } else {
+                const variable = getVariableForAI(key, env, manifest2);
+                if (variable && (variable.access === "full" /* FULL */ || variable.access === "read-only" /* READ_ONLY */)) {
+                  set2.push({ key, value: variable.displayValue });
+                } else {
+                  set2.push({ key, value: "<set>" });
+                }
+              }
+            }
+          }
+          const result = {
+            missing,
+            set: set2,
+            message: missing.length > 0 ? `${missing.length} required variable(s) are not set. Ask the user to configure them.` : "All required variables are set."
+          };
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        }
         default:
           return {
             content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envibe-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for envibe - the missing permission layer between AI agents and your .env",
   "type": "module",
   "bin": {