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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. artisan_es_reader_plugin-0.4.0/.env.example +40 -0
  2. {artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/.gitignore +7 -1
  3. artisan_es_reader_plugin-0.4.0/PKG-INFO +179 -0
  4. artisan_es_reader_plugin-0.4.0/README.md +167 -0
  5. {artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/artisan-es-reader-plugin.plugin +0 -0
  6. artisan_es_reader_plugin-0.4.0/mcp-config.example.json +8 -0
  7. {artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/pyproject.toml +1 -1
  8. artisan_es_reader_plugin-0.4.0/src/es_mcp/server.py +582 -0
  9. artisan_es_reader_plugin-0.2.0/.claude/settings.json +0 -16
  10. artisan_es_reader_plugin-0.2.0/.claude/settings.local.json +0 -9
  11. artisan_es_reader_plugin-0.2.0/.env.example +0 -18
  12. artisan_es_reader_plugin-0.2.0/PKG-INFO +0 -131
  13. artisan_es_reader_plugin-0.2.0/README.md +0 -119
  14. artisan_es_reader_plugin-0.2.0/mcp-config.example.json +0 -24
  15. artisan_es_reader_plugin-0.2.0/src/es_mcp/server.py +0 -255
  16. artisan_es_reader_plugin-0.2.0/uv.lock +0 -927
  17. {artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/requirements.txt +0 -0
  18. {artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/src/es_mcp/__init__.py +0 -0
artisan_es_reader_plugin-0.4.0/.env.example ADDED
@@ -0,0 +1,40 @@
1
+ # ---------------------------------------------------------------------------
2
+ # Multi-profile config (recommended)
3
+ # ---------------------------------------------------------------------------
4
+ # Define every Elasticsearch source as a named profile and pick a default.
5
+ # ES_PROFILES is a single JSON object. Shape:
6
+ #
7
+ # {"default": "<name>", "profiles": {"<name>": { <per-profile keys> }, ...}}
8
+ #
9
+ # Per-profile keys (all optional): es_host, es_port, es_username, es_password,
10
+ # es_use_ssl, es_verify_certs, ssh_host, ssh_port, ssh_username, ssh_pem_file,
11
+ # ssh_remote_es_host, ssh_remote_es_port, ssh_local_port.
12
+ #
13
+ # Example (single line — JSON, no comments allowed inside):
14
+ # 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"}}}
15
+
16
+ # Optionally override the default profile (otherwise the JSON "default" or the
17
+ # first profile is used):
18
+ # ES_DEFAULT_PROFILE=tealive_staging
19
+
20
+ # ---------------------------------------------------------------------------
21
+ # Legacy single-source config (used only when ES_PROFILES is NOT set)
22
+ # ---------------------------------------------------------------------------
23
+ # Elasticsearch connection
24
+ ES_HOST=localhost
25
+ ES_PORT=9200
26
+ ES_USERNAME=
27
+ ES_PASSWORD=
28
+ ES_USE_SSL=true
29
+ ES_VERIFY_CERTS=false
30
+
31
+ # SSH Tunnel (optional — leave SSH_HOST empty to connect directly)
32
+ SSH_HOST=
33
+ SSH_PORT=22
34
+ SSH_USERNAME=ubuntu
35
+ SSH_PEM_FILE=~/.ssh/my-key.pem
36
+ # Remote ES host/port as seen from the SSH server
37
+ SSH_REMOTE_ES_HOST=localhost
38
+ SSH_REMOTE_ES_PORT=9200
39
+ # Local port to bind the tunnel to (auto-picked if 0)
40
+ SSH_LOCAL_PORT=19200
{artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/.gitignore RENAMED
@@ -6,4 +6,10 @@ __pycache__/
6
6
  .Python
7
7
  *.egg-info/
8
8
  dist/
9
- build/
9
+ build/
10
+
11
+ # UV
12
+ uv.lock
13
+
14
+ # Claude
15
+ .claude/
artisan_es_reader_plugin-0.4.0/PKG-INFO ADDED
@@ -0,0 +1,179 @@
1
+ Metadata-Version: 2.4
2
+ Name: artisan-es-reader-plugin
3
+ Version: 0.4.0
4
+ Summary: Elasticsearch MCP server — query logs with or without SSH tunnel
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: elasticsearch<9.0.0,>=8.0.0
7
+ Requires-Dist: mcp>=1.0.0
8
+ Requires-Dist: paramiko>=3.0.0
9
+ Requires-Dist: python-dotenv>=1.0.0
10
+ Requires-Dist: sshtunnel>=0.4.0
11
+ Description-Content-Type: text/markdown
12
+
13
+ # Elasticsearch MCP Server
14
+
15
+ Query Elasticsearch logs directly from Claude Cowork — with or without an SSH tunnel.
16
+
17
+ ---
18
+
19
+ ## Installation
20
+
21
+ ### 1. Install the plugin
22
+
23
+ Get **es-mcp** from the Cowork plugin marketplace and install it.
24
+
25
+ ### 2. Install `uv`
26
+
27
+ The MCP server runs via `uvx`, which requires `uv` to be installed on your machine:
28
+
29
+ ```powershell
30
+ # Windows
31
+ powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
32
+ ```
33
+
34
+ ```bash
35
+ # macOS / Linux
36
+ curl -LsSf https://astral.sh/uv/install.sh | sh
37
+ ```
38
+
39
+ ### 3. Add the MCP entry to claude_desktop_config.json
40
+
41
+ Open the file at:
42
+
43
+ ```
44
+ Windows: %APPDATA%\Claude\claude_desktop_config.json
45
+ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
46
+ ```
47
+
48
+ Add this minimal entry inside `"mcpServers": { }`:
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "elasticsearch-logs": {
54
+ "command": "uvx",
55
+ "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"]
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ That's it — no env vars needed.
62
+
63
+ ### 4. Configure your profiles by asking Claude
64
+
65
+ Restart Cowork, then just ask Claude to add your Elasticsearch connections:
66
+
67
+ > "Add a tealive_production profile — bastion is 43.216.208.205, pem is at ~/keys/prod.pem"
68
+
69
+ Claude will call `configure_profile` and save your settings to `~/.es-mcp/profiles.json`
70
+ automatically. You can add as many profiles as you like this way.
71
+
72
+ ### 5. Restart Cowork
73
+
74
+ The SSH tunnel starts automatically on first tool use.
75
+
76
+ ---
77
+
78
+ ## How profiles are stored
79
+
80
+ Profiles are saved to `~/.es-mcp/profiles.json` — a plain, human-readable JSON file
81
+ you can also edit directly if you prefer:
82
+
83
+ ```json
84
+ {
85
+ "default": "tealive_production",
86
+ "profiles": {
87
+ "tealive_production": {
88
+ "es_use_ssl": true,
89
+ "es_verify_certs": false,
90
+ "es_username": "your-username",
91
+ "es_password": "your-password",
92
+ "ssh_host": "43.216.208.205",
93
+ "ssh_username": "ubuntu",
94
+ "ssh_pem_file": "~/keys/prod.pem"
95
+ },
96
+ "baskbear": {
97
+ "es_use_ssl": true,
98
+ "es_verify_certs": false,
99
+ "ssh_host": "baskbear-bastion-ip",
100
+ "ssh_username": "ubuntu",
101
+ "ssh_pem_file": "~/keys/baskbear.pem"
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ ### Config priority order
108
+
109
+ The server looks for profiles in this order — the first match wins:
110
+
111
+ 1. `ES_PROFILES` env var (JSON string) — backward compat for existing users
112
+ 2. `ES_PROFILES_FILE` env var — path to a custom JSON file
113
+ 3. `~/.es-mcp/profiles.json` — auto-discovered (written by `configure_profile`)
114
+ 4. Legacy flat `ES_*` / `SSH_*` env vars — single profile named "default"
115
+
116
+ ---
117
+
118
+ ## Selecting a profile
119
+
120
+ Every tool accepts an optional `profile` argument. Just ask naturally:
121
+
122
+ > "Search **baskbear** logs for payment errors"
123
+ > "Show recent errors in **tealive production**"
124
+
125
+ Omit it and the `default` profile is used. Call `list_profiles` to see what's
126
+ configured, or `connection_info` to inspect a specific one.
127
+
128
+ ---
129
+
130
+ ## Per-profile settings reference
131
+
132
+ | Key | Description | Default |
133
+ |---|---|---|
134
+ | `es_host` / `es_port` | ES host/port for **direct** connections (ignored when `ssh_host` is set) | `localhost` / `9200` |
135
+ | `es_username` / `es_password` | Elasticsearch credentials | empty |
136
+ | `es_use_ssl` | `true` if ES runs HTTPS | `false` |
137
+ | `es_verify_certs` | `false` for self-signed certs | `false` |
138
+ | `ssh_host` | Bastion / jump host IP or hostname. Leave unset for a direct connection | empty |
139
+ | `ssh_port` / `ssh_username` | SSH port / user | `22` / `ubuntu` |
140
+ | `ssh_pem_file` | Path to the PEM key on this machine (e.g. `~/keys/prod.pem`) | `~/.ssh/id_rsa` |
141
+ | `ssh_remote_es_host` / `ssh_remote_es_port` | ES host/port as seen from the bastion | `localhost` / `9200` |
142
+ | `ssh_local_port` | Local tunnel port (`0` = auto) | `0` |
143
+
144
+ ---
145
+
146
+ ## Available tools
147
+
148
+ All tools accept an optional `profile` argument to choose the Elasticsearch source.
149
+
150
+ | Tool | What it does |
151
+ |---|---|
152
+ | `configure_profile` | Add or update a profile — saves to `~/.es-mcp/profiles.json` |
153
+ | `delete_profile` | Remove a profile |
154
+ | `list_profiles` | List configured profiles and the default |
155
+ | `list_indices` | List indices (supports glob pattern) |
156
+ | `search_logs` | Full-text search with filters, sort, pagination |
157
+ | `get_recent_errors` | Error-level entries from the last N minutes |
158
+ | `get_index_mapping` | Field schema for an index |
159
+ | `run_aggregation` | Run a custom ES aggregation |
160
+ | `connection_info` | Show active connection / tunnel status |
161
+
162
+ ---
163
+
164
+ ## Updating
165
+
166
+ ### For users
167
+
168
+ Updates are automatic — just restart Cowork and `uvx` will pull the latest version from PyPI.
169
+
170
+ ### For maintainers
171
+
172
+ 1. Make changes to `src/es_mcp/server.py`
173
+ 2. Bump the version in `pyproject.toml`
174
+ 3. Build and publish:
175
+ ```bash
176
+ python -m build
177
+ twine upload dist/*
178
+ ```
179
+ 4. Users get the new version automatically on next Cowork restart — no action needed on their end
artisan_es_reader_plugin-0.4.0/README.md ADDED
@@ -0,0 +1,167 @@
1
+ # Elasticsearch MCP Server
2
+
3
+ Query Elasticsearch logs directly from Claude Cowork — with or without an SSH tunnel.
4
+
5
+ ---
6
+
7
+ ## Installation
8
+
9
+ ### 1. Install the plugin
10
+
11
+ Get **es-mcp** from the Cowork plugin marketplace and install it.
12
+
13
+ ### 2. Install `uv`
14
+
15
+ The MCP server runs via `uvx`, which requires `uv` to be installed on your machine:
16
+
17
+ ```powershell
18
+ # Windows
19
+ powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
20
+ ```
21
+
22
+ ```bash
23
+ # macOS / Linux
24
+ curl -LsSf https://astral.sh/uv/install.sh | sh
25
+ ```
26
+
27
+ ### 3. Add the MCP entry to claude_desktop_config.json
28
+
29
+ Open the file at:
30
+
31
+ ```
32
+ Windows: %APPDATA%\Claude\claude_desktop_config.json
33
+ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
34
+ ```
35
+
36
+ Add this minimal entry inside `"mcpServers": { }`:
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "elasticsearch-logs": {
42
+ "command": "uvx",
43
+ "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"]
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ That's it — no env vars needed.
50
+
51
+ ### 4. Configure your profiles by asking Claude
52
+
53
+ Restart Cowork, then just ask Claude to add your Elasticsearch connections:
54
+
55
+ > "Add a tealive_production profile — bastion is 43.216.208.205, pem is at ~/keys/prod.pem"
56
+
57
+ Claude will call `configure_profile` and save your settings to `~/.es-mcp/profiles.json`
58
+ automatically. You can add as many profiles as you like this way.
59
+
60
+ ### 5. Restart Cowork
61
+
62
+ The SSH tunnel starts automatically on first tool use.
63
+
64
+ ---
65
+
66
+ ## How profiles are stored
67
+
68
+ Profiles are saved to `~/.es-mcp/profiles.json` — a plain, human-readable JSON file
69
+ you can also edit directly if you prefer:
70
+
71
+ ```json
72
+ {
73
+ "default": "tealive_production",
74
+ "profiles": {
75
+ "tealive_production": {
76
+ "es_use_ssl": true,
77
+ "es_verify_certs": false,
78
+ "es_username": "your-username",
79
+ "es_password": "your-password",
80
+ "ssh_host": "43.216.208.205",
81
+ "ssh_username": "ubuntu",
82
+ "ssh_pem_file": "~/keys/prod.pem"
83
+ },
84
+ "baskbear": {
85
+ "es_use_ssl": true,
86
+ "es_verify_certs": false,
87
+ "ssh_host": "baskbear-bastion-ip",
88
+ "ssh_username": "ubuntu",
89
+ "ssh_pem_file": "~/keys/baskbear.pem"
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ ### Config priority order
96
+
97
+ The server looks for profiles in this order — the first match wins:
98
+
99
+ 1. `ES_PROFILES` env var (JSON string) — backward compat for existing users
100
+ 2. `ES_PROFILES_FILE` env var — path to a custom JSON file
101
+ 3. `~/.es-mcp/profiles.json` — auto-discovered (written by `configure_profile`)
102
+ 4. Legacy flat `ES_*` / `SSH_*` env vars — single profile named "default"
103
+
104
+ ---
105
+
106
+ ## Selecting a profile
107
+
108
+ Every tool accepts an optional `profile` argument. Just ask naturally:
109
+
110
+ > "Search **baskbear** logs for payment errors"
111
+ > "Show recent errors in **tealive production**"
112
+
113
+ Omit it and the `default` profile is used. Call `list_profiles` to see what's
114
+ configured, or `connection_info` to inspect a specific one.
115
+
116
+ ---
117
+
118
+ ## Per-profile settings reference
119
+
120
+ | Key | Description | Default |
121
+ |---|---|---|
122
+ | `es_host` / `es_port` | ES host/port for **direct** connections (ignored when `ssh_host` is set) | `localhost` / `9200` |
123
+ | `es_username` / `es_password` | Elasticsearch credentials | empty |
124
+ | `es_use_ssl` | `true` if ES runs HTTPS | `false` |
125
+ | `es_verify_certs` | `false` for self-signed certs | `false` |
126
+ | `ssh_host` | Bastion / jump host IP or hostname. Leave unset for a direct connection | empty |
127
+ | `ssh_port` / `ssh_username` | SSH port / user | `22` / `ubuntu` |
128
+ | `ssh_pem_file` | Path to the PEM key on this machine (e.g. `~/keys/prod.pem`) | `~/.ssh/id_rsa` |
129
+ | `ssh_remote_es_host` / `ssh_remote_es_port` | ES host/port as seen from the bastion | `localhost` / `9200` |
130
+ | `ssh_local_port` | Local tunnel port (`0` = auto) | `0` |
131
+
132
+ ---
133
+
134
+ ## Available tools
135
+
136
+ All tools accept an optional `profile` argument to choose the Elasticsearch source.
137
+
138
+ | Tool | What it does |
139
+ |---|---|
140
+ | `configure_profile` | Add or update a profile — saves to `~/.es-mcp/profiles.json` |
141
+ | `delete_profile` | Remove a profile |
142
+ | `list_profiles` | List configured profiles and the default |
143
+ | `list_indices` | List indices (supports glob pattern) |
144
+ | `search_logs` | Full-text search with filters, sort, pagination |
145
+ | `get_recent_errors` | Error-level entries from the last N minutes |
146
+ | `get_index_mapping` | Field schema for an index |
147
+ | `run_aggregation` | Run a custom ES aggregation |
148
+ | `connection_info` | Show active connection / tunnel status |
149
+
150
+ ---
151
+
152
+ ## Updating
153
+
154
+ ### For users
155
+
156
+ Updates are automatic — just restart Cowork and `uvx` will pull the latest version from PyPI.
157
+
158
+ ### For maintainers
159
+
160
+ 1. Make changes to `src/es_mcp/server.py`
161
+ 2. Bump the version in `pyproject.toml`
162
+ 3. Build and publish:
163
+ ```bash
164
+ python -m build
165
+ twine upload dist/*
166
+ ```
167
+ 4. Users get the new version automatically on next Cowork restart — no action needed on their end
artisan_es_reader_plugin-0.4.0/mcp-config.example.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "elasticsearch-logs": {
4
+ "command": "uvx",
5
+ "args": ["artisan-es-reader-plugin@latest", "artisan-es-reader-plugin"]
6
+ }
7
+ }
8
+ }
{artisan_es_reader_plugin-0.2.0 → artisan_es_reader_plugin-0.4.0}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "artisan-es-reader-plugin"
7
- version = "0.2.0"
7
+ version = "0.4.0"
8
8
  description = "Elasticsearch MCP server — query logs with or without SSH tunnel"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"