Metadata-Version: 2.4
Name: artisan-es-reader-plugin
Version: 0.2.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": { }`:

```json
{
  "mcpServers": {
    "elasticsearch-logs": {
      "command": "uvx",
      "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"],
      "env": {
        "ES_HOST": "localhost",
        "ES_PORT": "9200",
        "ES_USERNAME": "your-es-username",
        "ES_PASSWORD": "your-es-password",
        "ES_USE_SSL": "true",
        "ES_VERIFY_CERTS": "false",
        "SSH_HOST": "your-bastion-ip",
        "SSH_PORT": "22",
        "SSH_USERNAME": "ubuntu",
        "SSH_PEM_FILE": "C:\\Users\\your-name\\path\\to\\key.pem",
        "SSH_REMOTE_ES_HOST": "localhost",
        "SSH_REMOTE_ES_PORT": "9200",
        "SSH_LOCAL_PORT": "0"
      }
    }
  }
}
```

Each team member only needs to fill in these personal values:

| Variable | Description |
|---|---|
| `ES_USERNAME` | Elasticsearch username |
| `ES_PASSWORD` | Elasticsearch password |
| `SSH_HOST` | Bastion / jump host IP or hostname |
| `SSH_PEM_FILE` | Absolute path to your local PEM key file |

> **Windows paths** must use double backslashes in JSON: `C:\\Users\\your-name\\key.pem`

### 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 SSH tunnel, leave `SSH_HOST` empty.

---

## 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

| Tool | What it does |
|---|---|
| `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 |
