opensearch-mcp-server 2.0.0__py3-none-any.whl

opensearch_mcp_server-2.0.0.dist-info/METADATA

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: opensearch-mcp-server
+Version: 2.0.0
+Summary: MCP Server for interacting with Elasticsearch and OpenSearch
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [2025] [cr7258]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.49.0
+Requires-Dist: elasticsearch>=8.0.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: opensearch-py>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: tomli>=2.2.1
+Description-Content-Type: text/markdown
+
+# Elasticsearch/OpenSearch MCP Server
+
+[![smithery badge](https://smithery.ai/badge/elasticsearch-mcp-server)](https://smithery.ai/server/elasticsearch-mcp-server)
+
+## Overview
+
+A Model Context Protocol (MCP) server implementation that provides Elasticsearch and OpenSearch interaction. This server enables searching documents, analyzing indices, and managing cluster through a set of tools.
+
+<a href="https://glama.ai/mcp/servers/b3po3delex"><img width="380" height="200" src="https://glama.ai/mcp/servers/b3po3delex/badge" alt="Elasticsearch MCP Server" /></a>
+
+## Demo
+
+https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15
+
+## Features
+
+### Index Operations
+
+- `list_indices`: List all indices.
+- `get_index`: Returns information (mappings, settings, aliases) about one or more indices.
+- `create_index`: Create a new index.
+- `delete_index`: Delete an index.
+
+### Document Operations
+
+- `search_documents`: Search for documents.
+- `index_document`: Creates or updates a document in the index.
+- `get_document`: Get a document by ID.
+- `delete_document`: Delete a document by ID.
+- `delete_by_query`: Deletes documents matching the provided query.
+
+### Cluster Operations
+
+- `get_cluster_health`: Returns basic information about the health of the cluster.
+- `get_cluster_stats`: Returns high-level overview of cluster statistics.
+
+### Alias Operations
+
+- `list_aliases`: List all aliases.
+- `get_alias`: Get alias information for a specific index.
+- `put_alias`: Create or update an alias for a specific index.
+- `delete_alias`: Delete an alias for a specific index.
+
+## Configure Environment Variables
+
+Copy the `.env.example` file to `.env` and update the values accordingly.
+
+## Start Elasticsearch/OpenSearch Cluster
+
+Start the Elasticsearch/OpenSearch cluster using Docker Compose:
+
+```bash
+# For Elasticsearch
+docker-compose -f docker-compose-elasticsearch.yml up -d
+
+# For OpenSearch
+docker-compose -f docker-compose-opensearch.yml up -d
+```
+
+The default Elasticsearch username is `elastic` and password is `test123`. The default OpenSearch username is `admin` and password is `admin`.
+
+You can access Kibana/OpenSearch Dashboards from http://localhost:5601.
+
+## Usage with Claude Desktop
+
+### Option 1: Installing via Smithery
+
+To install Elasticsearch Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/elasticsearch-mcp-server):
+
+```bash
+npx -y @smithery/cli install elasticsearch-mcp-server --client claude
+```
+
+### Option 2: Using uvx
+
+Using `uvx` will automatically install the package from PyPI, no need to clone the repository locally. Add the following configuration to Claude Desktop's config file `claude_desktop_config.json`.
+
+```json
+// For Elasticsearch
+{
+  "mcpServers": {
+    "elasticsearch-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "elasticsearch-mcp-server"
+      ],
+      "env": {
+        "ELASTICSEARCH_HOST": "https://localhost:9200",
+        "ELASTICSEARCH_USERNAME": "elastic",
+        "ELASTICSEARCH_PASSWORD": "test123"
+      }
+    }
+  }
+}
+
+// For OpenSearch
+{
+  "mcpServers": {
+    "opensearch-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "opensearch-mcp-server"
+      ],
+      "env": {
+        "OPENSEARCH_HOST": "https://localhost:9200",
+        "OPENSEARCH_USERNAME": "admin",
+        "OPENSEARCH_PASSWORD": "admin"
+      }
+    }
+  }
+}
+```
+
+### Option 3: Using uv with local development
+
+Using `uv` requires cloning the repository locally and specifying the path to the source code. Add the following configuration to Claude Desktop's config file `claude_desktop_config.json`.
+
+```json
+// For Elasticsearch
+{
+  "mcpServers": {
+    "elasticsearch-mcp-server": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "path/to/src/elasticsearch_mcp_server",
+        "run",
+        "elasticsearch-mcp-server"
+      ],
+      "env": {
+        "ELASTICSEARCH_HOST": "https://localhost:9200",
+        "ELASTICSEARCH_USERNAME": "elastic",
+        "ELASTICSEARCH_PASSWORD": "test123"
+      }
+    }
+  }
+}
+
+// For OpenSearch
+{
+  "mcpServers": {
+    "opensearch-mcp-server": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "path/to/src/elasticsearch_mcp_server",
+        "run",
+        "opensearch-mcp-server"
+      ],
+      "env": {
+        "OPENSEARCH_HOST": "https://localhost:9200",
+        "OPENSEARCH_USERNAME": "admin",
+        "OPENSEARCH_PASSWORD": "admin"
+      }
+    }
+  }
+}
+```
+
+- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+Restart Claude Desktop to load the new MCP server.
+
+Now you can interact with your Elasticsearch/OpenSearch cluster through Claude using natural language commands like:
+- "List all indices in the cluster"
+- "How old is the student Bob?"
+- "Show me the cluster health status"
+
+## Usage with Anthropic MCP Client
+
+```python
+uv run mcp_client/client.py src/server.py
+```
+
+## License
+
+This project is licensed under the Apache License Version 2.0 - see the [LICENSE](LICENSE) file for details.

opensearch_mcp_server-2.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+src/__init__.py,sha256=aNKcThftSLh9IjOTA-UUpoRzIm4R0WwXKGAzykwecmU,211
+src/server.py,sha256=BtNr3oKiRK1rbnocFIKzwpukY87_AylzKh_ffwP6Zr8,2153
+src/clients/__init__.py,sha256=3UezAt9422S-7BvMiCo2Y9pmATVutorwsIQXP_g_CkA,1221
+src/clients/base.py,sha256=vTe4I62ruO2bEeSAag-2B5fJOWJDXllKbo8qA0h4VkM,2160
+src/clients/exceptions.py,sha256=NYF3KVw-9aAgCViin5OuBI6miMEPS5QsdHx6bcis1wc,2493
+src/clients/common/__init__.py,sha256=VgvgxFpESn2wAuJmH0XM_Ej2izI7dxK7QJe9wG4fmW0,211
+src/clients/common/alias.py,sha256=rB53TSld5x2vZyDNAwyEdnh1KWUXMSD7h5fSv_ubR2Q,759
+src/clients/common/client.py,sha256=GD-V97Dj8c2XGUYt58vqCggkk-k8WJePPgngBDWO5aM,973
+src/clients/common/cluster.py,sha256=pd5BVpqqDU6Lck3K704eEdhgFgzt9NstotWQLyG9zFM,401
+src/clients/common/document.py,sha256=ZzZiXDf_UhlN2FCmqW3drVjIZ07kGYP9yth_sgsJGPc,1623
+src/clients/common/index.py,sha256=vyH5iXlJe5JLcDK6fhCCEPN-tgGm6zP5ilwGPdWCXbY,776
+src/tools/__init__.py,sha256=qiMRNUKlpNGnqbrkgBHGa7El1Pw_0a2qUJnuk_Q8LtY,324
+src/tools/alias.py,sha256=p9TD4gXkGRGWHTYfvCg7G2hj-Uch9jwDXJNUY1hSD0Y,1376
+src/tools/cluster.py,sha256=XRAG-uxdfrieYX1ov_cBb66IYXaa8OoSWCUfXvNauy0,587
+src/tools/document.py,sha256=XZTVuk4di9VEwWMZN7jyDVnzoOiXkb4FBrXF44sVXTs,2052
+src/tools/index.py,sha256=7KNPtElTFelkjRSvdMqPBx9nx_9Uk01OnTMeVo7YeCs,1345
+src/tools/register.py,sha256=wrG2P6-YPW77bTg1j_ELp8omWRYsJjFeOHUy_unHe6Y,1344
+opensearch_mcp_server-2.0.0.dist-info/METADATA,sha256=0A6zv4UFDA609Uom3Dl2cv8MtuZPyTurw2jEPcmR_-E,18509
+opensearch_mcp_server-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+opensearch_mcp_server-2.0.0.dist-info/entry_points.txt,sha256=ImfJnUwMpQUBmu-1MeBG_P0dwamfXKQh82mBKW7tWNY,138
+opensearch_mcp_server-2.0.0.dist-info/licenses/LICENSE,sha256=DBsjuP5FR51d9kaUdXlVBuBv3cQ_I_adq9gefYQ9FcY,11339
+opensearch_mcp_server-2.0.0.dist-info/RECORD,,

opensearch_mcp_server-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opensearch_mcp_server-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+elasticsearch-mcp-server = src.server:elasticsearch_mcp_server
+opensearch-mcp-server = src.server:opensearch_mcp_server

opensearch_mcp_server-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2025] [cr7258]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

src/__init__.py

@@ -0,0 +1,6 @@
+"""
+Search MCP Server package.
+"""
+from src.server import elasticsearch_mcp_server, opensearch_mcp_server, run_search_server
+
+__all__ = ['elasticsearch_mcp_server', 'opensearch_mcp_server', 'run_search_server']

src/clients/__init__.py

@@ -0,0 +1,42 @@
+import os
+
+from dotenv import load_dotenv
+
+from src.clients.common.client import SearchClient
+from src.clients.exceptions import handle_search_exceptions
+
+def create_search_client(engine_type: str) -> SearchClient:
+    """
+    Create a search client for the specified engine type.
+    
+    Args:
+        engine_type: Type of search engine to use ("elasticsearch" or "opensearch")
+        
+    Returns:
+        A search client instance
+    """
+    # Load configuration from environment variables
+    load_dotenv()
+    
+    # Get configuration from environment variables
+    prefix = engine_type.upper()
+    hosts_str = os.environ.get(f"{prefix}_HOSTS", "https://localhost:9200")
+    hosts = [host.strip() for host in hosts_str.split(",")]
+    username = os.environ.get(f"{prefix}_USERNAME")
+    password = os.environ.get(f"{prefix}_PASSWORD")
+    verify_certs = os.environ.get(f"{prefix}_VERIFY_CERTS", "false").lower() == "true"
+    
+    config = {
+        "hosts": hosts,
+        "username": username,
+        "password": password,
+        "verify_certs": verify_certs
+    }
+    
+    return SearchClient(config, engine_type)
+
+__all__ = [
+    'create_search_client',
+    'handle_search_exceptions',
+    'SearchClient',
+]

src/clients/base.py

@@ -0,0 +1,54 @@
+from abc import ABC
+import logging
+import warnings
+from typing import Dict
+
+class SearchClientBase(ABC):
+    def __init__(self, config: Dict, engine_type: str):
+        """
+        Initialize the search client.
+        
+        Args:
+            config: Configuration dictionary with connection parameters
+            engine_type: Type of search engine to use ("elasticsearch" or "opensearch")
+        """
+        self.logger = logging.getLogger()
+        self.config = config
+        self.engine_type = engine_type
+        
+        # Extract common configuration
+        hosts = config.get("hosts")
+        username = config.get("username")
+        password = config.get("password")
+        verify_certs = config.get("verify_certs", False)
+        
+        # Disable insecure request warnings if verify_certs is False
+        if not verify_certs:
+            warnings.filterwarnings("ignore", message=".*verify_certs=False is insecure.*")
+            warnings.filterwarnings("ignore", message=".*Unverified HTTPS request is being made to host.*")
+            
+            try:
+                import urllib3
+                urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+            except ImportError:
+                pass
+        
+        # Initialize client based on engine type
+        if engine_type == "elasticsearch":
+            from elasticsearch import Elasticsearch
+            self.client = Elasticsearch(
+                hosts=hosts,
+                basic_auth=(username, password) if username and password else None,
+                verify_certs=verify_certs
+            )
+            self.logger.info(f"Elasticsearch client initialized with hosts: {hosts}")
+        elif engine_type == "opensearch":
+            from opensearchpy import OpenSearch
+            self.client = OpenSearch(
+                hosts=hosts,
+                http_auth=(username, password) if username and password else None,
+                verify_certs=verify_certs
+            )
+            self.logger.info(f"OpenSearch client initialized with hosts: {hosts}")
+        else:
+            raise ValueError(f"Unsupported engine type: {engine_type}")

src/clients/common/__init__.py

@@ -0,0 +1,6 @@
+from .index import IndexClient
+from .document import DocumentClient
+from .cluster import ClusterClient
+from .alias import AliasClient
+
+__all__ = ['IndexClient', 'DocumentClient', 'ClusterClient', 'AliasClient']

src/clients/common/alias.py

@@ -0,0 +1,20 @@
+from typing import Dict
+
+from src.clients.base import SearchClientBase
+
+class AliasClient(SearchClientBase):
+    def list_aliases(self) -> Dict:
+        """Get all aliases."""
+        return self.client.cat.aliases()
+    
+    def get_alias(self, index: str) -> Dict:
+        """Get aliases for the specified index."""
+        return self.client.indices.get_alias(index=index)
+
+    def put_alias(self, index: str, name: str, body: Dict) -> Dict:
+        """Creates or updates an alias."""
+        return self.client.indices.put_alias(index=index, name=name, body=body)
+    
+    def delete_alias(self, index: str, name: str) -> Dict:
+        """Delete an alias for the specified index."""
+        return self.client.indices.delete_alias(index=index, name=name)

src/clients/common/client.py

@@ -0,0 +1,25 @@
+from typing import Dict
+
+from src.clients.common.alias import AliasClient
+from src.clients.common.cluster import ClusterClient
+from src.clients.common.document import DocumentClient
+from src.clients.common.index import IndexClient
+
+class SearchClient(IndexClient, DocumentClient, ClusterClient, AliasClient):
+    """
+    Unified search client that combines all search functionality.
+    
+    This class uses multiple inheritance to combine all specialized client implementations
+    (index, document, cluster, alias) into a single unified client.
+    """
+    
+    def __init__(self, config: Dict, engine_type: str):
+        """
+        Initialize the search client.
+        
+        Args:
+            config: Configuration dictionary with connection parameters
+            engine_type: Type of search engine to use ("elasticsearch" or "opensearch")
+        """
+        super().__init__(config, engine_type)
+        self.logger.info(f"Initialized the {engine_type} client")

src/clients/common/cluster.py

@@ -0,0 +1,12 @@
+from typing import Dict
+
+from src.clients.base import SearchClientBase
+
+class ClusterClient(SearchClientBase):
+    def get_cluster_health(self) -> Dict:
+        """Get cluster health information from OpenSearch."""
+        return self.client.cluster.health()
+    
+    def get_cluster_stats(self) -> Dict:
+        """Get cluster statistics from OpenSearch."""
+        return self.client.cluster.stats()

src/clients/common/document.py

@@ -0,0 +1,37 @@
+from typing import Dict, Optional
+
+from src.clients.base import SearchClientBase
+
+class DocumentClient(SearchClientBase):
+    def search_documents(self, index: str, body: Dict) -> Dict:
+        """Search for documents in the index."""
+        return self.client.search(index=index, body=body)
+    
+    def index_document(self, index: str, document: Dict, id: Optional[str] = None) -> Dict:
+        """Creates a new document in the index."""
+        # Handle parameter name differences between Elasticsearch and OpenSearch
+        if self.engine_type == "elasticsearch":
+            # For Elasticsearch: index(index, document, id=None, ...)
+            if id is not None:
+                return self.client.index(index=index, document=document, id=id)
+            else:
+                return self.client.index(index=index, document=document)
+        else:
+            # For OpenSearch: index(index, body, id=None, ...)
+            if id is not None:
+                return self.client.index(index=index, body=document, id=id)
+            else:
+                return self.client.index(index=index, body=document)
+    
+    def get_document(self, index: str, id: str) -> Dict:
+        """Get a document by ID."""
+        return self.client.get(index=index, id=id)
+    
+    def delete_document(self, index: str, id: str) -> Dict:
+        """Removes a document from the index."""
+        return self.client.delete(index=index, id=id)
+
+    def delete_by_query(self, index: str, body: Dict) -> Dict:
+        """Deletes documents matching the provided query."""
+        return self.client.delete_by_query(index=index, body=body)
+

src/clients/common/index.py

@@ -0,0 +1,20 @@
+from typing import Dict, Optional
+
+from src.clients.base import SearchClientBase
+
+class IndexClient(SearchClientBase):
+    def list_indices(self) -> Dict:
+        """List all indices."""
+        return self.client.cat.indices()
+    
+    def get_index(self, index: str) -> Dict:
+        """Returns information (mappings, settings, aliases) about one or more indices."""
+        return self.client.indices.get(index=index)
+    
+    def create_index(self, index: str, body: Optional[Dict] = None) -> Dict:
+        """Creates an index with optional settings and mappings."""
+        return self.client.indices.create(index=index, body=body)
+    
+    def delete_index(self, index: str) -> Dict:
+        """Delete an index."""
+        return self.client.indices.delete(index=index)

src/clients/exceptions.py

@@ -0,0 +1,69 @@
+import functools
+import logging
+from typing import TypeVar, Callable
+
+from fastmcp import FastMCP
+from mcp.types import TextContent
+
+T = TypeVar('T')
+
+def handle_search_exceptions(func: Callable[..., T]) -> Callable[..., list[TextContent]]:
+    """
+    Decorator to handle exceptions in search client operations.
+    
+    Args:
+        func: The function to decorate
+        
+    Returns:
+        Decorated function that handles exceptions
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        logger = logging.getLogger()   
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"Unexpected error in {func.__name__}: {e}")
+            return [TextContent(type="text", text=f"Unexpected error in {func.__name__}: {str(e)}")]
+    
+    return wrapper
+
+def with_exception_handling(tool_instance: object, mcp: FastMCP) -> None:
+    """
+    Register tools from a tool instance with automatic exception handling applied to all tools.
+    
+    This function temporarily replaces mcp.tool with a wrapped version that automatically
+    applies the handle_search_exceptions decorator to all registered tool methods.
+    
+    Args:
+        tool_instance: The tool instance that has a register_tools method
+        mcp: The FastMCP instance used for tool registration
+    """
+    # Save the original tool method
+    original_tool = mcp.tool
+
+    @functools.wraps(original_tool)
+    def wrapped_tool(*args, **kwargs):
+        # Get the original decorator
+        decorator = original_tool(*args, **kwargs)
+
+        # Return a new decorator that applies both the exception handler and original decorator
+        def combined_decorator(func):
+            # First apply the exception handling decorator
+            wrapped_func = handle_search_exceptions(func)
+            # Then apply the original mcp.tool decorator
+            return decorator(wrapped_func)
+
+        return combined_decorator
+
+    try:
+        # Temporarily replace mcp.tool with our wrapped version
+        mcp.tool = wrapped_tool
+
+        # Call the registration method on the tool instance
+        tool_instance.register_tools(mcp)
+    finally:
+        # Restore the original mcp.tool to avoid affecting other code that might use mcp.tool
+        # This ensures that our modification is isolated to just this tool registration
+        # and prevents multiple nested decorators if register_all_tools is called multiple times
+        mcp.tool = original_tool

src/server.py

@@ -0,0 +1,71 @@
+import logging
+import sys
+
+from fastmcp import FastMCP
+
+from src.clients import create_search_client
+from src.tools.alias import AliasTools
+from src.tools.cluster import ClusterTools
+from src.tools.document import DocumentTools
+from src.tools.index import IndexTools
+from src.tools.register import ToolsRegister
+
+class SearchMCPServer:
+    def __init__(self, engine_type):
+        # Set engine type
+        self.engine_type = engine_type
+        self.name = f"{self.engine_type}_mcp_server"
+        self.mcp = FastMCP(self.name)
+        self.logger = logging.getLogger()
+        self.logger.info(f"Initializing {self.name}...")
+        
+        # Create the corresponding search client
+        self.search_client = create_search_client(self.engine_type)
+        
+        # Initialize tools
+        self._register_tools()
+
+    def _register_tools(self):
+        """Register all MCP tools."""
+        # Create a tools register
+        register = ToolsRegister(self.logger, self.search_client, self.mcp)
+        
+        # Define all tool classes to register
+        tool_classes = [
+            IndexTools,
+            DocumentTools,
+            ClusterTools,
+            AliasTools
+        ]        
+        # Register all tools
+        register.register_all_tools(tool_classes)
+
+    def run(self):
+        """Run the MCP server."""
+        self.mcp.run()
+
+def run_search_server(engine_type):
+    """Run search server with specified engine type."""
+    server = SearchMCPServer(engine_type=engine_type)
+    server.run()
+
+def elasticsearch_mcp_server():
+    """Entry point for Elasticsearch MCP server."""
+    run_search_server(engine_type="elasticsearch")
+
+def opensearch_mcp_server():
+    """Entry point for OpenSearch MCP server."""
+    run_search_server(engine_type="opensearch")
+
+if __name__ == "__main__":
+    # Default to Elasticsearch
+    engine_type = "elasticsearch"
+    
+    # If command line arguments are provided, use the first argument as the engine type
+    if len(sys.argv) > 1:
+        engine_type = sys.argv[1].lower()
+    
+    if engine_type == "opensearch":
+        opensearch_mcp_server()
+    else:
+        elasticsearch_mcp_server()

src/tools/__init__.py

@@ -0,0 +1,13 @@
+from src.tools.index import IndexTools
+from src.tools.document import DocumentTools
+from src.tools.cluster import ClusterTools
+from src.tools.alias import AliasTools
+from src.tools.register import ToolsRegister
+
+__all__ = [
+    'IndexTools',
+    'DocumentTools',
+    'ClusterTools',
+    'AliasTools',
+    'ToolsRegister',
+]

src/tools/alias.py

@@ -0,0 +1,46 @@
+from typing import Dict, List
+
+from fastmcp import FastMCP
+
+class AliasTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def list_aliases() -> List[Dict]:
+            """List all aliases."""
+            return self.search_client.list_aliases()
+
+        @mcp.tool()
+        def get_alias(index: str) -> Dict:
+            """
+            Get alias information for a specific index.
+
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.get_alias(index=index)
+
+        @mcp.tool()
+        def put_alias(index: str, name: str, body: Dict) -> Dict:
+            """
+            Create or update an alias for a specific index.
+
+            Args:
+                index: Name of the index
+                name: Name of the alias
+                body: Alias configuration
+            """
+            return self.search_client.put_alias(index=index, name=name, body=body)
+
+        @mcp.tool()
+        def delete_alias(index: str, name: str) -> Dict:
+            """
+            Delete an alias for a specific index.
+
+            Args:
+                index: Name of the index
+                name: Name of the alias
+            """
+            return self.search_client.delete_alias(index=index, name=name)
+        

src/tools/cluster.py

@@ -0,0 +1,17 @@
+from typing import Dict
+
+from fastmcp import FastMCP
+
+class ClusterTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def get_cluster_health() -> Dict:
+            """Returns basic information about the health of the cluster."""
+            return self.search_client.get_cluster_health()
+
+        @mcp.tool()
+        def get_cluster_stats() -> Dict:
+            """Returns high-level overview of cluster statistics."""
+            return self.search_client.get_cluster_stats()

src/tools/document.py

@@ -0,0 +1,64 @@
+from typing import Dict, Optional
+
+from fastmcp import FastMCP
+
+class DocumentTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def search_documents(index: str, body: Dict) -> Dict:
+            """
+            Search for documents.
+            
+            Args:
+                index: Name of the index
+                body: Search query
+            """
+            return self.search_client.search_documents(index=index, body=body)
+        
+        @mcp.tool()
+        def index_document(index: str, document: Dict, id: Optional[str] = None) -> Dict:
+            """
+            Creates or updates a document in the index.
+            
+            Args:
+                index: Name of the index
+                document: Document data
+                id: Optional document ID
+            """
+            return self.search_client.index_document(index=index, id=id, document=document)
+        
+        @mcp.tool()
+        def get_document(index: str, id: str) -> Dict:
+            """
+            Get a document by ID.
+            
+            Args:
+                index: Name of the index
+                id: Document ID
+            """
+            return self.search_client.get_document(index=index, id=id)
+        
+        @mcp.tool()
+        def delete_document(index: str, id: str) -> Dict:
+            """
+            Delete a document by ID.
+            
+            Args:
+                index: Name of the index
+                id: Document ID
+            """
+            return self.search_client.delete_document(index=index, id=id)
+        
+        @mcp.tool()
+        def delete_by_query(index: str, body: Dict) -> Dict:
+            """
+            Deletes documents matching the provided query.
+            
+            Args:
+                index: Name of the index
+                body: Query to match documents for deletion
+            """
+            return self.search_client.delete_by_query(index=index, body=body)

src/tools/index.py

@@ -0,0 +1,44 @@
+from typing import Dict, Optional, List
+
+from fastmcp import FastMCP
+
+class IndexTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+        
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def list_indices() -> List[Dict]:
+            """List all indices."""
+            return self.search_client.list_indices()
+
+        @mcp.tool()
+        def get_index(index: str) -> Dict:
+            """
+            Returns information (mappings, settings, aliases) about one or more indices.
+            
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.get_index(index=index)
+
+        @mcp.tool()
+        def create_index(index: str, body: Optional[Dict] = None) -> Dict:
+            """
+            Create a new index.
+            
+            Args:
+                index: Name of the index
+                body: Optional index configuration including mappings and settings
+            """
+            return self.search_client.create_index(index=index, body=body)
+
+        @mcp.tool()
+        def delete_index(index: str) -> Dict:
+            """
+            Delete an index.
+            
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.delete_index(index=index)

src/tools/register.py

@@ -0,0 +1,41 @@
+import logging
+from typing import List, Type
+
+from fastmcp import FastMCP
+
+from src.clients import SearchClient
+from src.clients.exceptions import with_exception_handling
+
+class ToolsRegister:
+    """Class to handle registration of MCP tools."""
+    
+    def __init__(self, logger: logging.Logger, search_client: SearchClient, mcp: FastMCP):
+        """
+        Initialize the tools register.
+        
+        Args:
+            logger: Logger instance
+            search_client: Search client instance
+            mcp: FastMCP instance
+        """
+        self.logger = logger
+        self.search_client = search_client
+        self.mcp = mcp
+    
+    def register_all_tools(self, tool_classes: List[Type]):
+        """
+        Register all tools with the MCP server.
+        
+        Args:
+            tool_classes: List of tool classes to register
+        """
+        for tool_class in tool_classes:
+            self.logger.info(f"Registering tools from {tool_class.__name__}")
+            tool_instance = tool_class(self.search_client)
+            
+            # Set logger and client attributes
+            tool_instance.logger = self.logger
+            tool_instance.search_client = self.search_client
+            
+            # Register tools with automatic exception handling
+            with_exception_handling(tool_instance, self.mcp)