artisan-es-reader-plugin 0.1.0__tar.gz

artisan_es_reader_plugin-0.1.0/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__elasticsearch-logs__list_indices",
+      "mcp__elasticsearch-logs__search_logs",
+      "mcp__elasticsearch-logs__get_recent_errors",
+      "mcp__elasticsearch-logs__get_index_mapping",
+      "mcp__elasticsearch-logs__run_aggregation",
+      "mcp__elasticsearch-logs__connection_info",
+      "mcp__gitnexus__impact",
+      "mcp__gitnexus__query",
+      "mcp__gitnexus__context",
+      "mcp__e0233bf5-d167-4834-8c53-594fec129450__getJiraIssue"
+    ]
+  }
+}

artisan_es_reader_plugin-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell(if \\($LASTEXITCODE -ne 0\\) { \"Directory empty or does not exist\" })",
+      "PowerShell(Get-Item \"$env:APPDATA\\\\Claude\\\\claude_desktop_config.json\" | Select-Object FullName)",
+      "mcp__plugin_es-mcp_elasticsearch-logs__search_logs"
+    ]
+  }
+}

artisan_es_reader_plugin-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# 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.1.0/.gitignore

@@ -0,0 +1,9 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/

artisan_es_reader_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: artisan-es-reader-plugin
+Version: 0.1.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 |

artisan_es_reader_plugin-0.1.0/README.md

@@ -0,0 +1,119 @@
+# 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 |

artisan_es_reader_plugin-0.1.0/mcp-config.example.json

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "elasticsearch-logs": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/artisan-soohao/es-mcp.git", "es-mcp"],
+      "env": {
+        "ES_HOST": "localhost",
+        "ES_PORT": "9200",
+        "ES_USERNAME": "",
+        "ES_PASSWORD": "",
+        "ES_USE_SSL": "false",
+        "ES_VERIFY_CERTS": "false",
+
+        "SSH_HOST": "",
+        "SSH_PORT": "22",
+        "SSH_USERNAME": "ubuntu",
+        "SSH_PEM_FILE": "C:/Users/NgSooHao/.ssh/my-key.pem",
+        "SSH_REMOTE_ES_HOST": "localhost",
+        "SSH_REMOTE_ES_PORT": "9200",
+        "SSH_LOCAL_PORT": "0"
+      }
+    }
+  }
+}

artisan_es_reader_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "artisan-es-reader-plugin"
+version = "0.1.0"
+description = "Elasticsearch MCP server — query logs with or without SSH tunnel"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "elasticsearch>=8.0.0,<9.0.0",
+    "paramiko>=3.0.0",
+    "python-dotenv>=1.0.0",
+    "sshtunnel>=0.4.0",
+]
+
+[project.scripts]
+artisan-es-reader-plugin = "es_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/es_mcp"]

artisan_es_reader_plugin-0.1.0/requirements.txt

@@ -0,0 +1,5 @@
+mcp>=1.0.0
+elasticsearch>=8.0.0,<9.0.0
+paramiko>=3.0.0
+python-dotenv>=1.0.0
+sshtunnel>=0.4.0

artisan_es_reader_plugin-0.1.0/src/es_mcp/server.py

@@ -0,0 +1,255 @@
+"""
+Elasticsearch MCP Server
+Supports direct connection or SSH tunnel (PEM file).
+"""
+
+import os
+import json
+import paramiko
+from typing import Any
+
+# sshtunnel references the removed paramiko.DSSKey in older versions — patch before import
+if not hasattr(paramiko, "DSSKey"):
+    paramiko.DSSKey = type("DSSKey", (), {})  # type: ignore[attr-defined]
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from elasticsearch import Elasticsearch
+from sshtunnel import SSHTunnelForwarder
+
+load_dotenv()
+
+# ---------------------------------------------------------------------------
+# SSH tunnel / ES client lifecycle
+# ---------------------------------------------------------------------------
+
+_tunnel: SSHTunnelForwarder | None = None
+_es_client: Elasticsearch | None = None
+
+
+def _build_es_client(host: str, port: int) -> Elasticsearch:
+    username = os.getenv("ES_USERNAME", "")
+    password = os.getenv("ES_PASSWORD", "")
+    use_ssl = os.getenv("ES_USE_SSL", "false").lower() == "true"
+    verify_certs = os.getenv("ES_VERIFY_CERTS", "false").lower() == "true"
+
+    scheme = "https" if use_ssl else "http"
+    kwargs: dict[str, Any] = {
+        "hosts": [{"host": host, "port": port, "scheme": scheme}],
+        "verify_certs": verify_certs,
+    }
+    if username and password:
+        kwargs["basic_auth"] = (username, password)
+
+    return Elasticsearch(**kwargs)
+
+
+def _start_tunnel() -> tuple[SSHTunnelForwarder, int]:
+    pem_path = os.path.expanduser(os.getenv("SSH_PEM_FILE", "~/.ssh/id_rsa"))
+    ssh_host = os.getenv("SSH_HOST", "").strip().strip('"')
+    tunnel = SSHTunnelForwarder(
+        (ssh_host, int(os.getenv("SSH_PORT", "22"))),
+        ssh_username=os.getenv("SSH_USERNAME", "ubuntu"),
+        ssh_pkey=pem_path,
+        remote_bind_address=(
+            os.getenv("SSH_REMOTE_ES_HOST", "localhost"),
+            int(os.getenv("SSH_REMOTE_ES_PORT", "9200")),
+        ),
+        local_bind_address=("127.0.0.1", int(os.getenv("SSH_LOCAL_PORT", "0"))),
+    )
+    tunnel.start()
+    return tunnel, tunnel.local_bind_port
+
+
+def get_es() -> Elasticsearch:
+    global _tunnel, _es_client
+    if _es_client is not None:
+        return _es_client
+
+    ssh_host = os.getenv("SSH_HOST", "").strip().strip('"')
+    if ssh_host:
+        _tunnel, local_port = _start_tunnel()
+        _es_client = _build_es_client("127.0.0.1", local_port)
+    else:
+        _es_client = _build_es_client(
+            os.getenv("ES_HOST", "localhost"),
+            int(os.getenv("ES_PORT", "9200")),
+        )
+
+    return _es_client
+
+
+def shutdown():
+    global _tunnel, _es_client
+    if _es_client:
+        _es_client.close()
+        _es_client = None
+    if _tunnel:
+        _tunnel.stop()
+        _tunnel = None
+
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP("elasticsearch-logs")
+
+
+@mcp.tool()
+def list_indices(pattern: str = "*") -> str:
+    """List Elasticsearch indices matching a glob pattern (default: all)."""
+    es = get_es()
+    resp = es.cat.indices(index=pattern, h="index,health,status,docs.count,store.size", s="index", format="json")
+    return json.dumps(resp.body, indent=2)
+
+
+@mcp.tool()
+def search_logs(
+    index: str,
+    query: str = "",
+    size: int = 20,
+    from_: int = 0,
+    sort_field: str = "@timestamp",
+    sort_order: str = "desc",
+    filters: str = "",
+) -> str:
+    """
+    Search logs in an Elasticsearch index.
+
+    Args:
+        index: Index name or pattern (e.g. "logs-*").
+        query: Lucene/simple query string. Empty returns all docs.
+        size: Number of hits to return (max 1000).
+        from_: Pagination offset.
+        sort_field: Field to sort by (default: @timestamp).
+        sort_order: "asc" or "desc".
+        filters: JSON string of extra must-term filters, e.g.
+                 '[{"term": {"level": "ERROR"}}]'.
+    """
+    es = get_es()
+    size = min(size, 1000)
+
+    must: list[Any] = []
+    if query:
+        must.append({"query_string": {"query": query}})
+    if filters:
+        extra = json.loads(filters)
+        must.extend(extra)
+
+    body: dict[str, Any] = {
+        "query": {"bool": {"must": must}} if must else {"match_all": {}},
+        "sort": [{sort_field: {"order": sort_order}}],
+        "size": size,
+        "from": from_,
+    }
+
+    resp = es.search(index=index, body=body)
+    hits = resp["hits"]["hits"]
+    total = resp["hits"]["total"]["value"]
+    return json.dumps({"total": total, "hits": [h["_source"] for h in hits]}, indent=2, default=str)
+
+
+@mcp.tool()
+def get_recent_errors(
+    index: str,
+    size: int = 20,
+    level_field: str = "level",
+    level_value: str = "ERROR",
+    minutes: int = 60,
+) -> str:
+    """
+    Fetch recent error-level log entries from the last N minutes.
+
+    Args:
+        index: Index name or pattern.
+        size: Number of results.
+        level_field: Field name that holds the log level.
+        level_value: The error level value to filter on (e.g. ERROR, CRITICAL).
+        minutes: Look back window in minutes.
+    """
+    es = get_es()
+    body: dict[str, Any] = {
+        "query": {
+            "bool": {
+                "must": [
+                    {"term": {level_field: level_value}},
+                    {"range": {"@timestamp": {"gte": f"now-{minutes}m", "lte": "now"}}},
+                ]
+            }
+        },
+        "sort": [{"@timestamp": {"order": "desc"}}],
+        "size": min(size, 1000),
+    }
+    resp = es.search(index=index, body=body)
+    hits = resp["hits"]["hits"]
+    total = resp["hits"]["total"]["value"]
+    return json.dumps({"total": total, "hits": [h["_source"] for h in hits]}, indent=2, default=str)
+
+
+@mcp.tool()
+def get_index_mapping(index: str) -> str:
+    """Return the field mapping for an Elasticsearch index."""
+    es = get_es()
+    resp = es.indices.get_mapping(index=index)
+    return json.dumps(resp.body, indent=2)
+
+
+@mcp.tool()
+def run_aggregation(
+    index: str,
+    aggs: str,
+    query: str = "",
+) -> str:
+    """
+    Run a custom aggregation against an index.
+
+    Args:
+        index: Index name or pattern.
+        aggs: JSON string of an Elasticsearch aggregations object, e.g.
+              '{"by_level": {"terms": {"field": "level", "size": 10}}}'.
+        query: Optional Lucene query string to filter docs before aggregating.
+    """
+    es = get_es()
+    body: dict[str, Any] = {"size": 0, "aggs": json.loads(aggs)}
+    if query:
+        body["query"] = {"query_string": {"query": query}}
+    resp = es.search(index=index, body=body)
+    return json.dumps(resp["aggregations"], indent=2, default=str)
+
+
+@mcp.tool()
+def connection_info() -> str:
+    """Show current connection details (host, SSH tunnel status)."""
+    ssh_host = os.getenv("SSH_HOST", "").strip()
+    info: dict[str, Any] = {
+        "mode": "ssh_tunnel" if ssh_host else "direct",
+        "es_host": os.getenv("ES_HOST", "localhost"),
+        "es_port": os.getenv("ES_PORT", "9200"),
+    }
+    if ssh_host:
+        info["ssh_host"] = ssh_host
+        info["ssh_user"] = os.getenv("SSH_USERNAME", "ubuntu")
+        info["ssh_pem"] = os.getenv("SSH_PEM_FILE", "~/.ssh/id_rsa")
+        info["remote_es"] = (
+            f"{os.getenv('SSH_REMOTE_ES_HOST', 'localhost')}:"
+            f"{os.getenv('SSH_REMOTE_ES_PORT', '9200')}"
+        )
+        if _tunnel and _tunnel.is_active:
+            info["tunnel_local_port"] = _tunnel.local_bind_port
+            info["tunnel_active"] = True
+    return json.dumps(info, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    import atexit
+    atexit.register(shutdown)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()