Docs: Add .mcp.json setup instructions and reference .env.example for configuration templates

Author: silkspace

README.md

@@ -18,36 +18,52 @@ This project integrates Graphistry's powerful GPU-accelerated graph visualizatio
 **This MCP server requires a free Graphistry account to use visualization features.**
 
 1. Sign up for a free account at [hub.graphistry.com](https://hub.graphistry.com)
-2. Set your credentials as environment variables before starting the server:
+2. Set your credentials as environment variables or in a `.env` file before starting the server:
    ```bash
    export GRAPHISTRY_USERNAME=your_username
    export GRAPHISTRY_PASSWORD=your_password
+   # or create a .env file with:
+   # GRAPHISTRY_USERNAME=your_username
+   # GRAPHISTRY_PASSWORD=your_password
    ```
+   See `.env.example` for a template.
 
-Without these credentials, visualization features will not work.
+## MCP Configuration (.mcp.json)
 
-## Installation
+To use this project with Cursor or other MCP-compatible tools, you need a `.mcp.json` file in your project root. A template is provided as `.mcp.json.example`.
+
+**Setup:**
+
+```bash
+cp .mcp.json.example .mcp.json
+```
 
-### Quick Installation with uv/uvx
+Edit `.mcp.json` to:
+- Set the correct paths for your environment (e.g., project root, Python executable, server script)
+- Set your Graphistry credentials (or use environment variables/.env)
+- Choose between HTTP and stdio modes:
+  - `graphistry-http`: Connects via HTTP (set the `url` to match your server's port)
+  - `graphistry`: Connects via stdio (set the `command`, `args`, and `env` as needed)
 
-This project uses [uv](https://astral.sh/uv) for dependency management, which provides fast and reliable Python package installations.
+**Note:**
+- `.mcp.json.example` contains both HTTP and stdio configurations. Enable/disable as needed by setting the `disabled` field.
+- See `.env.example` for environment variable setup.
+
+## Installation
+
+### Recommended Installation (Python venv + pip)
 
 ```bash
 # Clone the repository
 git clone https://github.com/graphistry/graphistry-mcp.git
 cd graphistry-mcp
 
-# Install uv if you don't have it
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
 # Set up virtual environment and install dependencies
-uv venv .venv
+python3 -m venv .venv
 source .venv/bin/activate
-uvx pip install -e ".[dev]"
+pip install -e ".[dev]"
 
-# Set up your Graphistry credentials (obtained from hub.graphistry.com)
-export GRAPHISTRY_USERNAME=your_username
-export GRAPHISTRY_PASSWORD=your_password
+# Set up your Graphistry credentials (see above)
 ```
 
 Or use the setup script:
@@ -67,10 +83,16 @@ source .venv/bin/activate
 # Start the server (stdio mode)
 python run_graphistry_mcp.py
 
-# Or use the start script for HTTP or stdio mode
+# Or use the start script for HTTP or stdio mode (recommended, sources .env securely)
 ./start-graphistry-mcp.sh --http 8080
 ```
 
+### Security & Credential Handling
+
+- The server loads credentials from environment variables or `.env` using [python-dotenv](https://pypi.org/project/python-dotenv/), so you can safely use a `.env` file for local development.
+- **Credentials are never printed in logs.** Only whether they are set is shown (e.g., `GRAPHISTRY_PASSWORD is set: True`).
+- The `start-graphistry-mcp.sh` script sources `.env` and is the most robust and secure way to launch the server.
+
 ### Adding to Cursor (or other LLM tools)
 
 - Add the MCP server to your `.cursor/mcp.json` or equivalent config:
@@ -121,7 +143,8 @@ The main tool, `visualize_graph`, now accepts a single `graph_data` dictionary.
 
 ### What We Learned / Caveats & Gotchas
 
-- **Environment Variables:** Always ensure `GRAPHISTRY_USERNAME` and `GRAPHISTRY_PASSWORD` are set in the environment where the server runs. Debug prints can help verify this.
+- **Environment Variables & .env:** Always ensure `GRAPHISTRY_USERNAME` and `GRAPHISTRY_PASSWORD` are set in the environment or `.env` file. The server loads `.env` automatically using `python-dotenv`.
+- **No Credential Leaks:** Debug prints and logs never show your actual credentials—only whether they are set.
 - **Virtual Environment:** Use the venv's Python directly or activate the environment before running the server. This avoids dependency and path issues.
 - **LLM Tool Schemas:** LLMs and tool bridges work best with single-argument (dict) APIs. Avoid multi-argument signatures for tools you want to expose to LLMs.
 - **Cursor Integration:** When adding to Cursor, use the full path to the venv's Python and ensure all environment variables are set in the config.