envibe 0.1.1 → 0.2.1

package/README.md

@@ -215,7 +215,14 @@ envibe setup
 | `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
 
 ## Why envibe?
 

package/dist/cli/index.js

@@ -23000,7 +23000,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: {
@@ -23011,6 +23011,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: {}
+          }
         }
       ]
     };
@@ -23041,18 +23049,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: [
               {
@@ -23094,25 +23141,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: [
@@ -23123,6 +23195,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/dist/index.js

@@ -20509,7 +20509,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: {
@@ -20520,6 +20520,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: {}
+          }
         }
       ]
     };
@@ -20550,18 +20558,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: [
               {
@@ -20603,25 +20650,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: [
@@ -20632,6 +20704,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",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "The missing permission layer between AI agents and your .env",
   "type": "module",
   "bin": {