feat: dotenv config files and plugin registry support (#75)

Add support for loading configuration from project-level
.mcp-outline.env and user-level ~/.config/mcp-outline/.env,
with empty env var stripping for Claude Code compatibility.

Add plugin/registry metadata (.claude-plugin/, .mcp.json,
server.json, glama.json) for discoverability across Claude Code,
VS Code, Glama, and the official MCP registry.

New dependency: python-dotenv>=1.0.0

Author: Vortiago

.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-outline",
+  "owner": {
+    "name": "Vortiago",
+    "url": "https://github.com/Vortiago"
+  },
+  "metadata": {
+    "description": "Outline knowledge base integration for Claude Code"
+  },
+  "plugins": [
+    {
+      "name": "mcp-outline",
+      "source": "./",
+      "description": "Connect Claude Code to Outline for document search, reading, creation, and management",
+      "version": "1.6.0",
+      "author": {
+        "name": "Vortiago"
+      },
+      "license": "MIT"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "mcp-outline",
+  "description": "Connect Claude Code to Outline for document search, reading, creation, and management",
+  "version": "1.6.0",
+  "author": {
+    "name": "Vortiago"
+  },
+  "homepage": "https://github.com/Vortiago/mcp-outline",
+  "repository": "https://github.com/Vortiago/mcp-outline",
+  "license": "MIT",
+  "keywords": [
+    "outline",
+    "documents",
+    "wiki",
+    "knowledge-base",
+    "mcp"
+  ]
+}

.github/workflows/publish-mcp-registry.yml

@@ -0,0 +1,31 @@
+name: Publish to MCP Registry
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    name: Publish to MCP Registry
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # Required for GitHub OIDC authentication
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Update server.json version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > server.json.tmp
+          mv server.json.tmp server.json
+          cat server.json
+
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

.mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "outline": {
+      "command": "uvx",
+      "args": ["mcp-outline"],
+      "env": {
+        "OUTLINE_API_KEY": "${OUTLINE_API_KEY:-}",
+        "OUTLINE_API_URL": "${OUTLINE_API_URL:-}",
+        "OUTLINE_READ_ONLY": "${OUTLINE_READ_ONLY:-}",
+        "OUTLINE_DISABLE_DELETE": "${OUTLINE_DISABLE_DELETE:-}",
+        "OUTLINE_DISABLE_AI_TOOLS": "${OUTLINE_DISABLE_AI_TOOLS:-}",
+        "OUTLINE_VERIFY_SSL": "${OUTLINE_VERIFY_SSL:-}"
+      }
+    }
+  }
+}

README.md

@@ -29,6 +29,16 @@ Before using this MCP server, you need:
 
 ## Quick Start
 
+### One-Click Install
+
+Click a button to install with interactive API key prompt:
+
+[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D&quality=insiders)
+[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=mcp-outline&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtY3Atb3V0bGluZSJdLCJlbnYiOnsiT1VUTElORV9BUElfS0VZIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV9rZXl9IiwiT1VUTElORV9BUElfVVJMIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV91cmx9In0sImlucHV0cyI6W3siaWQiOiJvdXRsaW5lX2FwaV9rZXkiLCJ0eXBlIjoicHJvbXB0U3RyaW5nIiwiZGVzY3JpcHRpb24iOiJFbnRlciBPVVRMSU5FX0FQSV9LRVkiLCJwYXNzd29yZCI6dHJ1ZX0seyJpZCI6Im91dGxpbmVfYXBpX3VybCIsInR5cGUiOiJwcm9tcHRTdHJpbmciLCJkZXNjcmlwdGlvbiI6Ik91dGxpbmUgQVBJIFVSTCAob3B0aW9uYWwsIGZvciBzZWxmLWhvc3RlZCkiLCJwYXNzd29yZCI6ZmFsc2V9XX0=)
+
+### Manual Install
+
 Install with uv (recommended), pip, or Docker:
 
 ```bash
@@ -41,7 +51,49 @@ pip install mcp-outline   # using pip
 docker run -e OUTLINE_API_KEY=<your-key> ghcr.io/vortiago/mcp-outline:latest
 ```
 
-Then add to your MCP client. Example for **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+Then add to your MCP client config (works with VS Code, Claude Desktop, Cursor, and others):
+
+```json
+{
+  "inputs": [
+    {
+      "id": "outline_api_key",
+      "type": "promptString",
+      "description": "Enter OUTLINE_API_KEY",
+      "password": true
+    },
+    {
+      "id": "outline_api_url",
+      "type": "promptString",
+      "description": "Outline API URL (optional, for self-hosted)",
+      "password": false
+    }
+  ],
+  "servers": {
+    "mcp-outline": {
+      "command": "uvx",
+      "args": ["mcp-outline"],
+      "env": {
+        "OUTLINE_API_KEY": "${input:outline_api_key}",
+        "OUTLINE_API_URL": "${input:outline_api_url}"
+      }
+    }
+  }
+}
+```
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add mcp-outline uvx mcp-outline
+```
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -51,20 +103,21 @@ Then add to your MCP client. Example for **Claude Desktop** (`~/Library/Applicat
       "args": ["mcp-outline"],
       "env": {
         "OUTLINE_API_KEY": "<YOUR_API_KEY>",
-        "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
+        "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>"
       }
     }
   }
 }
 ```
+</details>
 
-Setup guides for other clients: [Cursor, VS Code, Cline, Docker (HTTP), pip](docs/client-setup.md)
+Setup guides for more clients: [Docker (HTTP), Cline, Codex, Windsurf, and others](docs/client-setup.md)
 
 ## Configuration
 
 | Variable | Required | Default | Notes |
 |----------|----------|---------|-------|
-| `OUTLINE_API_KEY` | Yes* | - | Required for stdio transport. For SSE/HTTP, can be provided per-user via `x-outline-api-key` header instead ([details](docs/configuration.md#per-user-outline-api-keys)) |
+| `OUTLINE_API_KEY` | Yes* | - | Required for tool calls to succeed. For SSE/HTTP, can alternatively be provided per-request via `x-outline-api-key` header ([details](docs/configuration.md#per-user-outline-api-keys)) |
 | `OUTLINE_API_URL` | No | `https://app.getoutline.com/api` | For self-hosted: `https://your-domain/api` |
 | `OUTLINE_VERIFY_SSL` | No | `true` | Set `false` for self-signed certificates |
 | `OUTLINE_READ_ONLY` | No | `false` | `true` = disable ALL write operations ([details](docs/configuration.md#read-only-mode)) |

docs/client-setup.md

@@ -25,51 +25,57 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (or `%APP
 
 ## Cursor
 
-Go to **Settings → MCP** and click **Add Server**:
+**One-click install**: [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=mcp-outline&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtY3Atb3V0bGluZSJdLCJlbnYiOnsiT1VUTElORV9BUElfS0VZIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV9rZXl9IiwiT1VUTElORV9BUElfVVJMIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV91cmx9In0sImlucHV0cyI6W3siaWQiOiJvdXRsaW5lX2FwaV9rZXkiLCJ0eXBlIjoicHJvbXB0U3RyaW5nIiwiZGVzY3JpcHRpb24iOiJFbnRlciBPVVRMSU5FX0FQSV9LRVkiLCJwYXNzd29yZCI6dHJ1ZX0seyJpZCI6Im91dGxpbmVfYXBpX3VybCIsInR5cGUiOiJwcm9tcHRTdHJpbmciLCJkZXNjcmlwdGlvbiI6Ik91dGxpbmUgQVBJIFVSTCAob3B0aW9uYWwsIGZvciBzZWxmLWhvc3RlZCkiLCJwYXNzd29yZCI6ZmFsc2V9XX0=)
+
+Or go to **Settings → MCP** and click **Add Server**:
 
 ```json
 {
   "mcp-outline": {
     "command": "uvx",
     "args": ["mcp-outline"],
     "env": {
-      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
-      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
-    }
+      "OUTLINE_API_KEY": "${input:outline_api_key}",
+      "OUTLINE_API_URL": "${input:outline_api_url}"
+    },
+    "inputs": [
+      {
+        "id": "outline_api_key",
+        "type": "promptString",
+        "description": "Enter OUTLINE_API_KEY",
+        "password": true
+      },
+      {
+        "id": "outline_api_url",
+        "type": "promptString",
+        "description": "Outline API URL (optional, for self-hosted)",
+        "password": false
+      }
+    ]
   }
 }
 ```
 
 ## VS Code
 
-Create a `.vscode/mcp.json` file in your workspace:
-
-```json
-{
-  "servers": {
-    "mcp-outline": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["mcp-outline"],
-      "env": {
-        "OUTLINE_API_KEY": "<YOUR_API_KEY>",
-        "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
-      }
-    }
-  }
-}
-```
+**One-click install**: [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D)
 
-**Optional**: Use input variables for sensitive credentials:
+Or create a `.vscode/mcp.json` file in your workspace (recommended — uses secure password prompts):
 
 ```json
 {
   "inputs": [
     {
       "type": "promptString",
-      "id": "outline-api-key",
-      "description": "Outline API Key",
+      "id": "outline_api_key",
+      "description": "Enter OUTLINE_API_KEY",
       "password": true
+    },
+    {
+      "type": "promptString",
+      "id": "outline_api_url",
+      "description": "Outline API URL (optional, for self-hosted)",
+      "password": false
     }
   ],
   "servers": {
@@ -78,13 +84,20 @@ Create a `.vscode/mcp.json` file in your workspace:
       "command": "uvx",
       "args": ["mcp-outline"],
       "env": {
-        "OUTLINE_API_KEY": "${input:outline-api-key}"
+        "OUTLINE_API_KEY": "${input:outline_api_key}",
+        "OUTLINE_API_URL": "${input:outline_api_url}"
       }
     }
   }
 }
 ```
 
+You can also install via the CLI:
+
+```bash
+code --add-mcp '{"name":"mcp-outline","command":"uvx","args":["mcp-outline"],"env":{"OUTLINE_API_KEY":"${input:outline_api_key}","OUTLINE_API_URL":"${input:outline_api_url}"},"inputs":[{"id":"outline_api_key","type":"promptString","description":"Enter OUTLINE_API_KEY","password":true},{"id":"outline_api_url","type":"promptString","description":"Outline API URL (optional, for self-hosted)","password":false}]}'
+```
+
 See the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
 
 ## Cline (VS Code)
@@ -104,6 +117,31 @@ In Cline extension settings, add to MCP servers:
 }
 ```
 
+## Claude Code (Plugin)
+
+Install directly as a Claude Code plugin from GitHub:
+
+```bash
+/plugin marketplace add Vortiago/mcp-outline
+/plugin install mcp-outline@mcp-outline
+```
+
+Or test locally during development:
+
+```bash
+claude --plugin-dir ./path-to-mcp-outline
+```
+
+Set your Outline API key in your shell profile (`~/.bashrc` or `~/.zshrc`):
+
+```bash
+export OUTLINE_API_KEY="your-api-key-here"
+# For self-hosted Outline:
+export OUTLINE_API_URL="https://your-instance.example.com/api"
+```
+
+Restart Claude Code after setting environment variables. If `OUTLINE_API_KEY` is not configured, each tool call will return an error with setup instructions.
+
 ## Using pip Instead of uvx
 
 If you prefer to use `pip` instead:

docs/configuration.md

@@ -87,7 +87,7 @@ Then connect from your client with a user-specific key:
 }
 ```
 
-> **Note:** The `x-outline-api-key` header is only available for HTTP transports. In `stdio` mode, the `OUTLINE_API_KEY` environment variable is the only option.
+> **Note:** The `x-outline-api-key` header is only available for HTTP transports (SSE, streamable-http). In `stdio` mode, you must set `OUTLINE_API_KEY` via environment variable or a [dotenv config file](client-setup.md#claude-code-plugin). If it is missing, the server still starts but every tool call will return an error with setup instructions.
 
 ### Dynamic Tool List
 

docs/registries.md

@@ -0,0 +1,19 @@
+# Registries & Marketplaces
+
+Where mcp-outline is listed and which files control each listing.
+
+| Registry | Config Files | Published How | Notes |
+|----------|-------------|---------------|-------|
+| **PyPI** | `pyproject.toml` | CI on tag (`publish.yml`) | Version from git tag via setuptools-scm |
+| **Docker (GHCR)** | `Dockerfile` | CI on tag | Image: `ghcr.io/vortiago/mcp-outline` |
+| **MCP Official Registry** | `server.json` | CI on tag (`publish-mcp-registry.yml`) | Version patched from tag at publish time |
+| **Glama** | `glama.json` | Manual claim at [glama.ai](https://glama.ai) | Only sets maintainer for ownership |
+| **Claude Code Plugin** | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.mcp.json` | Repo discovery | Install: `/plugin marketplace add Vortiago/mcp-outline` |
+
+## File reference
+
+- **`server.json`** — MCP Registry server manifest. Schema: `2025-12-11`. Versions updated by CI at publish time.
+- **`glama.json`** — Glama ownership claim. Minimal: just `$schema` + `maintainers`.
+- **`.claude-plugin/plugin.json`** — Claude Code plugin metadata (name, description, keywords).
+- **`.claude-plugin/marketplace.json`** — Claude Code marketplace entry. Lists plugins available from this repo.
+- **`.mcp.json`** — MCP server config used by the Claude Code plugin. Defines how to run the server with env vars.

glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "Vortiago"
+  ]
+}

pyproject.toml

@@ -15,6 +15,7 @@ license-files = ["LICENSE"]
 dependencies = [
     "mcp[cli]>=1.20.0",
     "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
 ]
 
 [project.scripts]