@leanmcp/env-injection 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LeanMCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# @leanmcp/env-injection
+
+Request-scoped environment variable injection for LeanMCP tools. Enables user-specific secrets (API keys, tokens) to be securely fetched and accessed within MCP tool methods.
+
+## Features
+
+- **Request-scoped isolation** - Each user's secrets are isolated using `AsyncLocalStorage`
+- **@RequireEnv decorator** - Validate required env vars exist before method execution
+- **getEnv() / getAllEnv()** - Access user-specific secrets in your tool code
+- **Type-safe** - Full TypeScript support
+- **Works with @leanmcp/auth** - Integrates with `@Authenticated` decorator
+
+## Installation
+
+```bash
+npm install @leanmcp/env-injection @leanmcp/auth @leanmcp/core
+```
+
+## Quick Start
+
+### 1. Configure Auth Provider with projectId
+
+```typescript
+import { AuthProvider } from "@leanmcp/auth";
+
+export const projectId = process.env.LEANMCP_PROJECT_ID;
+
+export const authProvider = new AuthProvider('leanmcp', {
+    apiKey: process.env.LEANMCP_API_KEY,
+    orchestrationApiUrl: 'https://api.leanmcp.com',
+    authUrl: 'https://auth.leanmcp.com'
+});
+
+await authProvider.init();
+```
+
+### 2. Use @RequireEnv and getEnv()
+
+```typescript
+import { Tool } from "@leanmcp/core";
+import { Authenticated } from "@leanmcp/auth";
+import { RequireEnv, getEnv } from "@leanmcp/env-injection";
+import { authProvider, projectId } from "./config.js";
+
+@Authenticated(authProvider, { projectId })
+export class SlackService {
+
+    @Tool({ description: 'Send a message to Slack' })
+    @RequireEnv(["SLACK_TOKEN", "SLACK_CHANNEL"])
+    async sendMessage(args: { message: string }) {
+        // getEnv() returns THIS USER's secret, not a global env var
+        const token = getEnv("SLACK_TOKEN")!;
+        const channel = getEnv("SLACK_CHANNEL")!;
+
+        // Send message using user's own Slack token
+        await slackApi.postMessage(channel, args.message, token);
+
+        return { success: true, channel };
+    }
+}
+```
+
+## API Reference
+
+### runWithEnv(env, fn)
+
+Run a function with environment variables in scope. Used internally by `@Authenticated`.
+
+```typescript
+import { runWithEnv } from "@leanmcp/env-injection";
+
+await runWithEnv({ API_KEY: "secret123" }, async () => {
+    console.log(getEnv("API_KEY")); // "secret123"
+});
+```
+
+### getEnv(key)
+
+Get a single environment variable from the current request context.
+
+```typescript
+import { getEnv } from "@leanmcp/env-injection";
+
+const token = getEnv("SLACK_TOKEN");
+// Returns undefined if key doesn't exist
+// Throws if called outside env context (projectId not configured)
+```
+
+### getAllEnv()
+
+Get all environment variables from the current request context.
+
+```typescript
+import { getAllEnv } from "@leanmcp/env-injection";
+
+const env = getAllEnv();
+// { SLACK_TOKEN: "xoxb-...", SLACK_CHANNEL: "#general" }
+```
+
+### hasEnvContext()
+
+Check if currently inside an env context.
+
+```typescript
+import { hasEnvContext } from "@leanmcp/env-injection";
+
+if (hasEnvContext()) {
+    // Safe to call getEnv()
+}
+```
+
+### @RequireEnv(keys)
+
+Decorator to validate required environment variables exist before method execution.
+
+```typescript
+import { RequireEnv } from "@leanmcp/env-injection";
+
+@RequireEnv(["SLACK_TOKEN", "SLACK_CHANNEL"])
+async sendMessage(args: { message: string }) {
+    // Method only executes if BOTH keys exist
+    // Otherwise throws: "Missing required environment variables: SLACK_TOKEN, SLACK_CHANNEL"
+}
+```
+
+**Requirements:**
+- Must be used with `@Authenticated(authProvider, { projectId })` 
+- Throws clear error if `projectId` is not configured
+
+## Error Messages
+
+### Missing projectId Configuration
+
+```
+Environment injection not configured for SlackService.sendMessage().
+To use @RequireEnv, you must configure 'projectId' in your @Authenticated decorator:
+@Authenticated(authProvider, { projectId: 'your-project-id' })
+```
+
+### Missing Required Variables
+
+```
+Missing required environment variables: SLACK_TOKEN, SLACK_CHANNEL.
+Please configure these secrets in your LeanMCP dashboard for this project.
+```
+
+### Called Outside Context
+
+```
+getEnv("SLACK_TOKEN") called outside of env context.
+To use getEnv(), you must configure 'projectId' in your @Authenticated decorator:
+@Authenticated(authProvider, { projectId: 'your-project-id' })
+```
+
+## How It Works
+
+1. User makes request to your MCP server with auth token
+2. `@Authenticated` verifies token and fetches user's secrets from LeanMCP API
+3. Secrets are stored in `AsyncLocalStorage` for this request only
+4. `@RequireEnv` validates required secrets exist
+5. `getEnv()` / `getAllEnv()` access secrets during method execution
+6. Context is automatically cleaned up after request completes
+
+```
+Request → @Authenticated(projectId) → Fetch Secrets → runWithEnv() → @RequireEnv → Method → Cleanup
+           ↓                                            ↓                ↓
+     Verify token                              Store in ALS        getEnv() works
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LEANMCP_API_KEY` | Your LeanMCP API key (with SDK scope) |
+| `LEANMCP_PROJECT_ID` | Project ID to scope secrets to |
+| `LEANMCP_ORCHESTRATION_API_URL` | API URL (default: https://api.leanmcp.com) |
+| `LEANMCP_AUTH_URL` | Auth URL (default: https://auth.leanmcp.com) |
+
+## Best Practices
+
+1. **Always use @Authenticated with projectId** - Required for env injection to work
+2. **Use @RequireEnv for validation** - Fails fast with clear error messages
+3. **Don't cache secrets** - They're request-scoped for security
+4. **Configure secrets in dashboard** - Users manage their own secrets
+5. **Use non-null assertion** - After @RequireEnv, secrets are guaranteed to exist
+
+```typescript
+@RequireEnv(["API_KEY"])
+async method() {
+    const key = getEnv("API_KEY")!; // Safe to use ! here
+}
+```
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@leanmcp/auth](../auth) - Authentication decorators
+- [@leanmcp/core](../core) - Core MCP server functionality
+
+## Links
+
+- [GitHub Repository](https://github.com/LeanMCP/leanmcp-sdk)
+- [Documentation](https://github.com/LeanMCP/leanmcp-sdk#readme)

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+/**
+ * Run a function with the given environment variables in scope
+ * @param env - Environment variables to make available via getEnv()
+ * @param fn - Function to execute with the env context
+ */
+declare function runWithEnv<T>(env: Record<string, string>, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Check if we're currently inside an env context
+ */
+declare function hasEnvContext(): boolean;
+/**
+ * Get an environment variable from the current request context
+ *
+ * IMPORTANT: This function requires @Authenticated(authProvider, { projectId: '...' })
+ * to be configured. Throws an error if called outside of an env context.
+ *
+ * @param key - Environment variable key
+ * @returns The value or undefined if the key doesn't exist
+ * @throws Error if called outside of env context (projectId not configured)
+ */
+declare function getEnv(key: string): string | undefined;
+/**
+ * Get all environment variables from the current request context
+ *
+ * IMPORTANT: This function requires @Authenticated(authProvider, { projectId: '...' })
+ * to be configured. Throws an error if called outside of an env context.
+ *
+ * @returns A copy of all environment variables
+ * @throws Error if called outside of env context (projectId not configured)
+ */
+declare function getAllEnv(): Record<string, string>;
+
+/**
+ * Decorator to validate required environment variables exist before method execution
+ *
+ * IMPORTANT: This decorator REQUIRES @Authenticated(authProvider, { projectId: '...' })
+ * to be applied either on the method or on the enclosing class. This is validated at
+ * runtime when the method is called.
+ *
+ * @param keys - List of required environment variable keys
+ *
+ * @example
+ * ```typescript
+ * @Authenticated(authProvider, { projectId: 'my-project' })
+ * class SlackService {
+ *   @Tool("Send Slack message")
+ *   @RequireEnv(["SLACK_TOKEN", "SLACK_CHANNEL"])
+ *   async sendMessage({ message }: { message: string }) {
+ *     const token = getEnv("SLACK_TOKEN"); // User's token, not global
+ *     const channel = getEnv("SLACK_CHANNEL");
+ *     // ... send message
+ *   }
+ * }
+ * ```
+ */
+declare function RequireEnv(keys: string[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Get the required env keys for a method
+ */
+declare function getRequiredEnvKeys(target: any, propertyKey: string): string[] | undefined;
+/**
+ * Check if a method has @RequireEnv decorator
+ */
+declare function hasRequireEnv(target: any, propertyKey: string): boolean;
+
+export { RequireEnv, getAllEnv, getEnv, getRequiredEnvKeys, hasEnvContext, hasRequireEnv, runWithEnv };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Run a function with the given environment variables in scope
+ * @param env - Environment variables to make available via getEnv()
+ * @param fn - Function to execute with the env context
+ */
+declare function runWithEnv<T>(env: Record<string, string>, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Check if we're currently inside an env context
+ */
+declare function hasEnvContext(): boolean;
+/**
+ * Get an environment variable from the current request context
+ *
+ * IMPORTANT: This function requires @Authenticated(authProvider, { projectId: '...' })
+ * to be configured. Throws an error if called outside of an env context.
+ *
+ * @param key - Environment variable key
+ * @returns The value or undefined if the key doesn't exist
+ * @throws Error if called outside of env context (projectId not configured)
+ */
+declare function getEnv(key: string): string | undefined;
+/**
+ * Get all environment variables from the current request context
+ *
+ * IMPORTANT: This function requires @Authenticated(authProvider, { projectId: '...' })
+ * to be configured. Throws an error if called outside of an env context.
+ *
+ * @returns A copy of all environment variables
+ * @throws Error if called outside of env context (projectId not configured)
+ */
+declare function getAllEnv(): Record<string, string>;
+
+/**
+ * Decorator to validate required environment variables exist before method execution
+ *
+ * IMPORTANT: This decorator REQUIRES @Authenticated(authProvider, { projectId: '...' })
+ * to be applied either on the method or on the enclosing class. This is validated at
+ * runtime when the method is called.
+ *
+ * @param keys - List of required environment variable keys
+ *
+ * @example
+ * ```typescript
+ * @Authenticated(authProvider, { projectId: 'my-project' })
+ * class SlackService {
+ *   @Tool("Send Slack message")
+ *   @RequireEnv(["SLACK_TOKEN", "SLACK_CHANNEL"])
+ *   async sendMessage({ message }: { message: string }) {
+ *     const token = getEnv("SLACK_TOKEN"); // User's token, not global
+ *     const channel = getEnv("SLACK_CHANNEL");
+ *     // ... send message
+ *   }
+ * }
+ * ```
+ */
+declare function RequireEnv(keys: string[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Get the required env keys for a method
+ */
+declare function getRequiredEnvKeys(target: any, propertyKey: string): string[] | undefined;
+/**
+ * Check if a method has @RequireEnv decorator
+ */
+declare function hasRequireEnv(target: any, propertyKey: string): boolean;
+
+export { RequireEnv, getAllEnv, getEnv, getRequiredEnvKeys, hasEnvContext, hasRequireEnv, runWithEnv };

package/dist/index.js

@@ -0,0 +1,113 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RequireEnv: () => RequireEnv,
+  getAllEnv: () => getAllEnv,
+  getEnv: () => getEnv,
+  getRequiredEnvKeys: () => getRequiredEnvKeys,
+  hasEnvContext: () => hasEnvContext,
+  hasRequireEnv: () => hasRequireEnv,
+  runWithEnv: () => runWithEnv
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/env-context.ts
+var import_reflect_metadata = require("reflect-metadata");
+var import_async_hooks = require("async_hooks");
+var envStorage = new import_async_hooks.AsyncLocalStorage();
+function runWithEnv(env, fn) {
+  return envStorage.run(env, fn);
+}
+__name(runWithEnv, "runWithEnv");
+function hasEnvContext() {
+  return envStorage.getStore() !== void 0;
+}
+__name(hasEnvContext, "hasEnvContext");
+function getEnv(key) {
+  const store = envStorage.getStore();
+  if (store === void 0) {
+    throw new Error(`getEnv("${key}") called outside of env context. To use getEnv(), you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+  }
+  return store[key];
+}
+__name(getEnv, "getEnv");
+function getAllEnv() {
+  const store = envStorage.getStore();
+  if (store === void 0) {
+    throw new Error(`getAllEnv() called outside of env context. To use getAllEnv(), you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+  }
+  return {
+    ...store
+  };
+}
+__name(getAllEnv, "getAllEnv");
+
+// src/decorators.ts
+var import_reflect_metadata2 = require("reflect-metadata");
+var REQUIRE_ENV_KEY = /* @__PURE__ */ Symbol("requireEnv");
+function RequireEnv(keys) {
+  return function(target, propertyKey, descriptor) {
+    Reflect.defineMetadata(REQUIRE_ENV_KEY, keys, target, propertyKey);
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(...args) {
+      if (!hasEnvContext()) {
+        const className = target.constructor?.name || target.name || "Unknown";
+        throw new Error(`Environment injection not configured for ${className}.${propertyKey}(). To use @RequireEnv, you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+      }
+      const missing = keys.filter((key) => !getEnv(key));
+      if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(", ")}. Please configure these secrets in your LeanMCP dashboard for this project.`);
+      }
+      return originalMethod.apply(this, args);
+    };
+    copyMethodMetadata(originalMethod, descriptor.value);
+    return descriptor;
+  };
+}
+__name(RequireEnv, "RequireEnv");
+function getRequiredEnvKeys(target, propertyKey) {
+  return Reflect.getMetadata(REQUIRE_ENV_KEY, target, propertyKey);
+}
+__name(getRequiredEnvKeys, "getRequiredEnvKeys");
+function hasRequireEnv(target, propertyKey) {
+  return Reflect.hasMetadata(REQUIRE_ENV_KEY, target, propertyKey);
+}
+__name(hasRequireEnv, "hasRequireEnv");
+function copyMethodMetadata(source, target) {
+  const metadataKeys = Reflect.getMetadataKeys(source);
+  for (const key of metadataKeys) {
+    const value = Reflect.getMetadata(key, source);
+    Reflect.defineMetadata(key, value, target);
+  }
+}
+__name(copyMethodMetadata, "copyMethodMetadata");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RequireEnv,
+  getAllEnv,
+  getEnv,
+  getRequiredEnvKeys,
+  hasEnvContext,
+  hasRequireEnv,
+  runWithEnv
+});

package/dist/index.mjs

@@ -0,0 +1,82 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/env-context.ts
+import "reflect-metadata";
+import { AsyncLocalStorage } from "async_hooks";
+var envStorage = new AsyncLocalStorage();
+function runWithEnv(env, fn) {
+  return envStorage.run(env, fn);
+}
+__name(runWithEnv, "runWithEnv");
+function hasEnvContext() {
+  return envStorage.getStore() !== void 0;
+}
+__name(hasEnvContext, "hasEnvContext");
+function getEnv(key) {
+  const store = envStorage.getStore();
+  if (store === void 0) {
+    throw new Error(`getEnv("${key}") called outside of env context. To use getEnv(), you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+  }
+  return store[key];
+}
+__name(getEnv, "getEnv");
+function getAllEnv() {
+  const store = envStorage.getStore();
+  if (store === void 0) {
+    throw new Error(`getAllEnv() called outside of env context. To use getAllEnv(), you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+  }
+  return {
+    ...store
+  };
+}
+__name(getAllEnv, "getAllEnv");
+
+// src/decorators.ts
+import "reflect-metadata";
+var REQUIRE_ENV_KEY = /* @__PURE__ */ Symbol("requireEnv");
+function RequireEnv(keys) {
+  return function(target, propertyKey, descriptor) {
+    Reflect.defineMetadata(REQUIRE_ENV_KEY, keys, target, propertyKey);
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(...args) {
+      if (!hasEnvContext()) {
+        const className = target.constructor?.name || target.name || "Unknown";
+        throw new Error(`Environment injection not configured for ${className}.${propertyKey}(). To use @RequireEnv, you must configure 'projectId' in your @Authenticated decorator: @Authenticated(authProvider, { projectId: 'your-project-id' })`);
+      }
+      const missing = keys.filter((key) => !getEnv(key));
+      if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(", ")}. Please configure these secrets in your LeanMCP dashboard for this project.`);
+      }
+      return originalMethod.apply(this, args);
+    };
+    copyMethodMetadata(originalMethod, descriptor.value);
+    return descriptor;
+  };
+}
+__name(RequireEnv, "RequireEnv");
+function getRequiredEnvKeys(target, propertyKey) {
+  return Reflect.getMetadata(REQUIRE_ENV_KEY, target, propertyKey);
+}
+__name(getRequiredEnvKeys, "getRequiredEnvKeys");
+function hasRequireEnv(target, propertyKey) {
+  return Reflect.hasMetadata(REQUIRE_ENV_KEY, target, propertyKey);
+}
+__name(hasRequireEnv, "hasRequireEnv");
+function copyMethodMetadata(source, target) {
+  const metadataKeys = Reflect.getMetadataKeys(source);
+  for (const key of metadataKeys) {
+    const value = Reflect.getMetadata(key, source);
+    Reflect.defineMetadata(key, value, target);
+  }
+}
+__name(copyMethodMetadata, "copyMethodMetadata");
+export {
+  RequireEnv,
+  getAllEnv,
+  getEnv,
+  getRequiredEnvKeys,
+  hasEnvContext,
+  hasRequireEnv,
+  runWithEnv
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@leanmcp/env-injection",
+    "version": "0.1.0",
+    "description": "Request-scoped environment variable injection for LeanMCP",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "require": "./dist/index.js",
+            "import": "./dist/index.mjs"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format esm,cjs --dts",
+        "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+        "test": "jest --passWithNoTests"
+    },
+    "dependencies": {
+        "reflect-metadata": "^0.2.1"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LeanMCP/leanmcp-sdk.git",
+        "directory": "packages/env-injection"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "environment",
+        "injection",
+        "secrets"
+    ],
+    "author": "LeanMCP <admin@leanmcp.com>",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    }
+}