artisan-es-reader-plugin 0.2.0__tar.gz → 0.3.0__tar.gz

artisan_es_reader_plugin-0.3.0/.env.example

@@ -0,0 +1,40 @@
+# ---------------------------------------------------------------------------
+# Multi-profile config (recommended)
+# ---------------------------------------------------------------------------
+# Define every Elasticsearch source as a named profile and pick a default.
+# ES_PROFILES is a single JSON object. Shape:
+#
+#   {"default": "<name>", "profiles": {"<name>": { <per-profile keys> }, ...}}
+#
+# Per-profile keys (all optional): es_host, es_port, es_username, es_password,
+# es_use_ssl, es_verify_certs, ssh_host, ssh_port, ssh_username, ssh_pem_file,
+# ssh_remote_es_host, ssh_remote_es_port, ssh_local_port.
+#
+# Example (single line — JSON, no comments allowed inside):
+# ES_PROFILES={"default":"tealive_staging","profiles":{"tealive_staging":{"es_use_ssl":true,"es_username":"u","es_password":"p","ssh_host":"staging-bastion","ssh_pem_file":"~/staging.pem"},"tealive_production":{"es_use_ssl":true,"es_username":"u","es_password":"p","ssh_host":"prod-bastion","ssh_pem_file":"~/prod.pem"},"baskbear":{"es_use_ssl":true,"es_username":"u","es_password":"p","ssh_host":"baskbear-bastion","ssh_pem_file":"~/baskbear.pem"}}}
+
+# Optionally override the default profile (otherwise the JSON "default" or the
+# first profile is used):
+# ES_DEFAULT_PROFILE=tealive_staging
+
+# ---------------------------------------------------------------------------
+# Legacy single-source config (used only when ES_PROFILES is NOT set)
+# ---------------------------------------------------------------------------
+# Elasticsearch connection
+ES_HOST=localhost
+ES_PORT=9200
+ES_USERNAME=
+ES_PASSWORD=
+ES_USE_SSL=true
+ES_VERIFY_CERTS=false
+
+# SSH Tunnel (optional — leave SSH_HOST empty to connect directly)
+SSH_HOST=
+SSH_PORT=22
+SSH_USERNAME=ubuntu
+SSH_PEM_FILE=~/.ssh/my-key.pem
+# Remote ES host/port as seen from the SSH server
+SSH_REMOTE_ES_HOST=localhost
+SSH_REMOTE_ES_PORT=9200
+# Local port to bind the tunnel to (auto-picked if 0)
+SSH_LOCAL_PORT=19200

{artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.3.0}/.gitignore

@@ -6,4 +6,10 @@ __pycache__/
 .Python
 *.egg-info/
 dist/
-build/
+build/
+
+# UV
+uv.lock
+
+# Claude
+.claude/

artisan_es_reader_plugin-0.3.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: artisan-es-reader-plugin
+Version: 0.3.0
+Summary: Elasticsearch MCP server — query logs with or without SSH tunnel
+Requires-Python: >=3.11
+Requires-Dist: elasticsearch<9.0.0,>=8.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: paramiko>=3.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: sshtunnel>=0.4.0
+Description-Content-Type: text/markdown
+
+# Elasticsearch MCP Server
+
+Query Elasticsearch logs directly from Claude Cowork — with or without an SSH tunnel.
+
+---
+
+## Installation
+
+### 1. Install the plugin
+
+Get **es-mcp** from the Cowork plugin marketplace and install it.
+
+### 2. Install `uv`
+
+The MCP server runs via `uvx`, which requires `uv` to be installed on your machine:
+
+```powershell
+# Windows
+powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 3. Configure the MCP server
+
+Open `claude_desktop_config.json`:
+
+```
+Windows:  %APPDATA%\Claude\claude_desktop_config.json
+macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Add the entry inside `"mcpServers": { }`. Define every Elasticsearch source you
+want to reach as a **profile** under `ES_PROFILES`, and pick which one is used
+when no profile is specified with `"default"`:
+
+```json
+{
+  "mcpServers": {
+    "elasticsearch-logs": {
+      "command": "uvx",
+      "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"],
+      "env": {
+        "ES_PROFILES": "{\"default\":\"tealive_staging\",\"profiles\":{\"tealive_staging\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"staging-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\staging.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200},\"tealive_production\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"prod-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\prod.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200},\"baskbear\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"baskbear-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\baskbear.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200}}}"
+      }
+    }
+  }
+}
+```
+
+`ES_PROFILES` is a JSON object (as a string). Because it lives inside JSON, every
+quote is escaped `\"` and Windows backslashes are doubled again to `\\\\`. The
+de-escaped shape is just:
+
+```json
+{
+  "default": "tealive_staging",
+  "profiles": {
+    "tealive_staging":     { "ssh_host": "...", "ssh_pem_file": "...", "es_username": "...", "es_password": "...", ... },
+    "tealive_production":  { "ssh_host": "...", "ssh_pem_file": "...", ... },
+    "baskbear":            { "ssh_host": "...", "ssh_pem_file": "...", ... }
+  }
+}
+```
+
+Per-profile keys (all optional; sensible defaults applied):
+
+| Key | Description | Default |
+|---|---|---|
+| `es_host` / `es_port` | ES host/port for **direct** connections (ignored when `ssh_host` is set) | `localhost` / `9200` |
+| `es_username` / `es_password` | Elasticsearch credentials | empty |
+| `es_use_ssl` | `true` if ES runs HTTPS | `false` |
+| `es_verify_certs` | `false` for self-signed certs | `false` |
+| `ssh_host` | Bastion / jump host. Leave unset for a direct connection | empty |
+| `ssh_port` / `ssh_username` | SSH port / user | `22` / `ubuntu` |
+| `ssh_pem_file` | Absolute path to your local PEM key (Windows: `C:\\\\Users\\\\you\\\\key.pem`) | `~/.ssh/id_rsa` |
+| `ssh_remote_es_host` / `ssh_remote_es_port` | ES host/port as seen from the bastion | `localhost` / `9200` |
+| `ssh_local_port` | Local tunnel port (`0` = auto) | `0` |
+
+### Selecting a profile
+
+Every tool takes an optional `profile` argument. Just ask naturally — "search
+**baskbear** logs for X", "recent errors in **tealive production**" — and the
+matching profile is used. Omit it and the `default` profile is queried. Call
+`list_profiles` to see what's configured, or `connection_info` to inspect one.
+
+> **Backward compatible:** if `ES_PROFILES` is not set, the server falls back to
+> the old flat `ES_*` / `SSH_*` env vars as a single profile named `default`.
+
+### 4. Restart Cowork
+
+The SSH tunnel starts automatically on first tool use.
+
+---
+
+## Notes
+
+- `es_host` is only used for direct connections. When `ssh_host` is set, traffic routes through the tunnel and `es_host` is ignored.
+- `es_use_ssl`: set `true` if your Elasticsearch runs HTTPS.
+- `es_verify_certs`: set `false` for self-signed certificates.
+- `ssh_local_port`: `0` = auto-pick a free local port.
+- To connect without an SSH tunnel for a profile, leave its `ssh_host` unset.
+- Each profile gets its own client + tunnel, created lazily on first use and reused afterwards.
+
+---
+
+## Updating
+
+### For users
+
+Updates are automatic — just restart Cowork and `uvx` will pull the latest version from PyPI.
+
+### For maintainers
+
+1. Make changes to `src/es_mcp/server.py`
+2. Bump the version in `pyproject.toml`
+3. Build and publish:
+   ```bash
+   python -m build
+   twine upload dist/*
+   ```
+4. Users get the new version automatically on next Cowork restart — no action needed on their end
+
+---
+
+## Available tools
+
+All tools accept an optional `profile` argument to choose the Elasticsearch source.
+
+| Tool | What it does |
+|---|---|
+| `list_profiles` | List configured profiles and the default |
+| `list_indices` | List indices (supports glob pattern) |
+| `search_logs` | Full-text search with filters, sort, pagination |
+| `get_recent_errors` | Error-level entries from the last N minutes |
+| `get_index_mapping` | Field schema for an index |
+| `run_aggregation` | Run a custom ES aggregation |
+| `connection_info` | Show active connection / tunnel status |

artisan_es_reader_plugin-0.3.0/README.md

@@ -0,0 +1,141 @@
+# Elasticsearch MCP Server
+
+Query Elasticsearch logs directly from Claude Cowork — with or without an SSH tunnel.
+
+---
+
+## Installation
+
+### 1. Install the plugin
+
+Get **es-mcp** from the Cowork plugin marketplace and install it.
+
+### 2. Install `uv`
+
+The MCP server runs via `uvx`, which requires `uv` to be installed on your machine:
+
+```powershell
+# Windows
+powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 3. Configure the MCP server
+
+Open `claude_desktop_config.json`:
+
+```
+Windows:  %APPDATA%\Claude\claude_desktop_config.json
+macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Add the entry inside `"mcpServers": { }`. Define every Elasticsearch source you
+want to reach as a **profile** under `ES_PROFILES`, and pick which one is used
+when no profile is specified with `"default"`:
+
+```json
+{
+  "mcpServers": {
+    "elasticsearch-logs": {
+      "command": "uvx",
+      "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"],
+      "env": {
+        "ES_PROFILES": "{\"default\":\"tealive_staging\",\"profiles\":{\"tealive_staging\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"staging-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\staging.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200},\"tealive_production\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"prod-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\prod.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200},\"baskbear\":{\"es_use_ssl\":true,\"es_verify_certs\":false,\"es_username\":\"your-es-username\",\"es_password\":\"your-es-password\",\"ssh_host\":\"baskbear-bastion-ip\",\"ssh_username\":\"ubuntu\",\"ssh_pem_file\":\"C:\\\\Users\\\\your-name\\\\baskbear.pem\",\"ssh_remote_es_host\":\"localhost\",\"ssh_remote_es_port\":9200}}}"
+      }
+    }
+  }
+}
+```
+
+`ES_PROFILES` is a JSON object (as a string). Because it lives inside JSON, every
+quote is escaped `\"` and Windows backslashes are doubled again to `\\\\`. The
+de-escaped shape is just:
+
+```json
+{
+  "default": "tealive_staging",
+  "profiles": {
+    "tealive_staging":     { "ssh_host": "...", "ssh_pem_file": "...", "es_username": "...", "es_password": "...", ... },
+    "tealive_production":  { "ssh_host": "...", "ssh_pem_file": "...", ... },
+    "baskbear":            { "ssh_host": "...", "ssh_pem_file": "...", ... }
+  }
+}
+```
+
+Per-profile keys (all optional; sensible defaults applied):
+
+| Key | Description | Default |
+|---|---|---|
+| `es_host` / `es_port` | ES host/port for **direct** connections (ignored when `ssh_host` is set) | `localhost` / `9200` |
+| `es_username` / `es_password` | Elasticsearch credentials | empty |
+| `es_use_ssl` | `true` if ES runs HTTPS | `false` |
+| `es_verify_certs` | `false` for self-signed certs | `false` |
+| `ssh_host` | Bastion / jump host. Leave unset for a direct connection | empty |
+| `ssh_port` / `ssh_username` | SSH port / user | `22` / `ubuntu` |
+| `ssh_pem_file` | Absolute path to your local PEM key (Windows: `C:\\\\Users\\\\you\\\\key.pem`) | `~/.ssh/id_rsa` |
+| `ssh_remote_es_host` / `ssh_remote_es_port` | ES host/port as seen from the bastion | `localhost` / `9200` |
+| `ssh_local_port` | Local tunnel port (`0` = auto) | `0` |
+
+### Selecting a profile
+
+Every tool takes an optional `profile` argument. Just ask naturally — "search
+**baskbear** logs for X", "recent errors in **tealive production**" — and the
+matching profile is used. Omit it and the `default` profile is queried. Call
+`list_profiles` to see what's configured, or `connection_info` to inspect one.
+
+> **Backward compatible:** if `ES_PROFILES` is not set, the server falls back to
+> the old flat `ES_*` / `SSH_*` env vars as a single profile named `default`.
+
+### 4. Restart Cowork
+
+The SSH tunnel starts automatically on first tool use.
+
+---
+
+## Notes
+
+- `es_host` is only used for direct connections. When `ssh_host` is set, traffic routes through the tunnel and `es_host` is ignored.
+- `es_use_ssl`: set `true` if your Elasticsearch runs HTTPS.
+- `es_verify_certs`: set `false` for self-signed certificates.
+- `ssh_local_port`: `0` = auto-pick a free local port.
+- To connect without an SSH tunnel for a profile, leave its `ssh_host` unset.
+- Each profile gets its own client + tunnel, created lazily on first use and reused afterwards.
+
+---
+
+## Updating
+
+### For users
+
+Updates are automatic — just restart Cowork and `uvx` will pull the latest version from PyPI.
+
+### For maintainers
+
+1. Make changes to `src/es_mcp/server.py`
+2. Bump the version in `pyproject.toml`
+3. Build and publish:
+   ```bash
+   python -m build
+   twine upload dist/*
+   ```
+4. Users get the new version automatically on next Cowork restart — no action needed on their end
+
+---
+
+## Available tools
+
+All tools accept an optional `profile` argument to choose the Elasticsearch source.
+
+| Tool | What it does |
+|---|---|
+| `list_profiles` | List configured profiles and the default |
+| `list_indices` | List indices (supports glob pattern) |
+| `search_logs` | Full-text search with filters, sort, pagination |
+| `get_recent_errors` | Error-level entries from the last N minutes |
+| `get_index_mapping` | Field schema for an index |
+| `run_aggregation` | Run a custom ES aggregation |
+| `connection_info` | Show active connection / tunnel status |

{artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "artisan-es-reader-plugin"
-version = "0.2.0"
+version = "0.3.0"
 description = "Elasticsearch MCP server — query logs with or without SSH tunnel"
 readme = "README.md"
 requires-python = ">=3.11"