diff --git a/app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx b/app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx index e7589c8d0..624284748 100644 --- a/app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx +++ b/app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx @@ -80,17 +80,17 @@ This generates a Python module with the following structure: ```bash my_server/ +├── .env.example ├── src/ │ └── my_server/ │ ├── __init__.py -│ ├── .env.example │ └── server.py └── pyproject.toml ``` - **server.py** Entrypoint file with MCPApp and example tools - **pyproject.toml** Dependencies and project configuration -- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py` +- **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory. `server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools: @@ -106,17 +106,17 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra -You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret: +You can create a `.env` file at your project root directory and add your secret: ```env filename=".env" MY_SECRET_KEY="my-secret-value" ``` -The generated project includes a `.env.example` file with the secret key name and example value. +The generated project includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it. ```bash -mv .env.example .env +mv ../../.env.example ../../.env ``` diff --git a/app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx b/app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx index b02555388..981ab61a2 100644 --- a/app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx +++ b/app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx @@ -76,17 +76,17 @@ This generates a Python module with the following structure: ```bash my_server/ +├── .env.example ├── src/ │ └── my_server/ │ ├── __init__.py -│ ├── .env.example │ └── server.py └── pyproject.toml ``` 1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly. 1. **pyproject.toml** Dependencies and project configuration -1. **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.** +1. **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.** ```python filename="server.py" showLineNumbers #!/usr/bin/env python3 @@ -171,17 +171,19 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra -You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret: +You can create a `.env` file at your project root directory and add your secret: ```env filename=".env" MY_SECRET_KEY="my-secret-value" ``` -The generated project includes a `.env.example` file with the secret key name and example value. +Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the project root (`my_server/`), and it will be found even when running your server from a subdirectory like `src/my_server/`. + +The generated project includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it. ```bash -mv .env.example .env +mv ../../.env.example ../../.env ``` diff --git a/app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx b/app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx index 9d0bb4902..a18fa88aa 100644 --- a/app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx +++ b/app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx @@ -68,13 +68,13 @@ Depending on where you're running your server, you can store your secret in a fe -You can create a `.env` file in the same directory as your entrypoint file (typically `server.py` by default) and add your secret: +You can create a `.env` file in your project root directory and add your secret: ```env filename=".env" MY_SECRET_KEY="my-secret-value" ``` -The project includes a `.env.example` file with the secret key name and example value. +The project includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it. ```bash @@ -206,7 +206,7 @@ When your tool is executed, it will return: `"Got SECRET_KEY of length..."`. In ## Key Concepts - **Secure Access:** Secrets are accessed through context, not imported directly -- **Environment Integration:** Works with both environment variables and .env files +- **Environment Integration:** Works with both environment variables and `.env` files - **Error Handling:** Always handle the case where a secret might be missing - **Masking:** Never expose full secret values in logs or return values - **Declaration:** Use `requires_secrets` to make dependencies explicit @@ -221,7 +221,7 @@ SECRET_KEY="supersecret" -For the code to work, you must define your environment variables locally or in a `.env` file. +For the code to work, you must define your environment variables locally or in a `.env` file. Arcade will automatically search upward from the current directory to find your `.env` file. diff --git a/app/en/guides/deployment-hosting/arcade-deploy/page.mdx b/app/en/guides/deployment-hosting/arcade-deploy/page.mdx index c05e679f7..91fc5c3a7 100644 --- a/app/en/guides/deployment-hosting/arcade-deploy/page.mdx +++ b/app/en/guides/deployment-hosting/arcade-deploy/page.mdx @@ -105,7 +105,7 @@ Validating user is logged in... Validating pyproject.toml exists in current directory... ✓ pyproject.toml found at /path/to/your/project/pyproject.toml -Loading .env file from current directory if it exists... +Searching for .env file... ✓ Loaded environment from /path/to/your/project/.env Validating server is healthy and extracting metadata before deploying... diff --git a/app/en/references/mcp/python/settings/page.mdx b/app/en/references/mcp/python/settings/page.mdx index 2fc2f9266..30aece80d 100644 --- a/app/en/references/mcp/python/settings/page.mdx +++ b/app/en/references/mcp/python/settings/page.mdx @@ -7,6 +7,42 @@ description: Global configuration and environment-driven settings for the Arcade Global configuration and environment-driven settings. +## find_env_file() + +```python +arcade_mcp_server.settings.find_env_file( + start_dir: Path | None = None, + stop_at: Path | None = None, + filename: str = ".env" +) -> Path | None +``` + +Find a `.env` file by traversing upward through parent directories. + +Starts at the specified directory (or current working directory) and traverses upward through parent directories until a `.env` file is found or the filesystem root (or `stop_at` directory) is reached. + +**Parameters:** +- `start_dir` - Directory to start searching from. Defaults to current working directory. +- `stop_at` - Directory to stop traversal at (inclusive). If specified, the search will not continue past this directory. The `stop_at` directory itself is still checked for the `.env` file. +- `filename` - Name of the env file to find. Defaults to `.env`. + +**Returns:** Path to the `.env` file if found, `None` otherwise. + +**Example:** + +```python +from arcade_mcp_server.settings import find_env_file + +# Find .env starting from current directory +env_path = find_env_file() + +# Find .env starting from a specific directory +env_path = find_env_file(start_dir=Path("/path/to/project/src")) + +# Find .env but don't search above project root +env_path = find_env_file(stop_at=Path("/path/to/project")) +``` + ## MCPSettings ```python @@ -25,6 +61,10 @@ from_env() classmethod Create settings from environment variables. +Automatically discovers and loads a `.env` file by traversing upward from the current directory through parent directories until a `.env` file is found or the filesystem root is reached. + +The `.env` file is loaded with `override=False`, meaning existing environment variables take precedence. Multiple calls are safe. + ### to_dict() ```python