Skip to main content

OpenSearch Orchestrator

An MCP-powered assistant that guides you from initial requirements to a running OpenSearch search setup. It collects a sample document, gathers preferences, plans a search architecture, and executes the plan — creating indices, ML models, ingest pipelines, and a local search UI — with optional deployment to Amazon OpenSearch Service or Serverless.


Kiro Power (Primary Integration)

OpenSearch Orchestrator is packaged as a Kiro Power. Install it in Kiro by adding this repo as a power source. Kiro reads POWER.md for workflow instructions and calls MCP tools exposed by the server.

The mcp.json at the repo root runs uvx opensearch-orchestrator@latest — no local clone required.


Standalone CLI (Local Development)

Start the interactive orchestrator in a terminal:

python opensearch_orchestrator/orchestrator.py

The orchestrator guides you through sample collection, requirements gathering, solution planning, and execution — all in one interactive session.


MCP Server

The MCP server exposes the orchestrator workflow as a set of phase tools. Any MCP-compatible client (Claude Desktop, MCP Inspector, etc.) can drive the conversation.

Prerequisites

Install uv (one-time, no sudo needed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Running from PyPI

uvx opensearch-orchestrator@latest

If installed via pip:

opensearch-orchestrator

This starts a stdio MCP server (JSON-RPC), not an interactive CLI. Launch it from an MCP client. For an interactive terminal session, use python opensearch_orchestrator/orchestrator.py instead.

Running locally (dev)

uv run opensearch_orchestrator/mcp_server.py

uv reads inline script metadata and auto-installs dependencies into a cached virtual environment.

Claude Desktop integration

  1. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
  "mcpServers": {
    "opensearch-orchestrator": {
      "command": "uvx",
      "args": ["opensearch-orchestrator@latest"]
    }
  }
}
  1. Restart Claude Desktop. The opensearch_workflow prompt is available in the prompt picker and describes the full tool sequence.

Generic MCP clients

Any MCP-compatible client can connect via stdio and discover tools with tools/list. The opensearch_workflow prompt (available via prompts/list) describes the workflow. Tool docstrings also include prerequisite hints.

Without uv

Install dependencies manually and point to the server script:

pip install mcp opensearch-py
{
  "mcpServers": {
    "opensearch-orchestrator": {
      "command": "python3",
      "args": ["opensearch_orchestrator/mcp_server.py"],
      "cwd": "/path/to/agent"
    }
  }
}

MCP Workflow Tools

The server exposes high-level phase tools:

Tool Phase Description
load_sample 1 Load a sample document (built-in IMDB, local file, URL, index, or paste)
set_preferences 2 Set budget, performance, query pattern, deployment preferences
start_planning 3 Start the planning agent; returns initial architecture proposal
refine_plan 3 Send user feedback to refine the proposal
finalize_plan 3 Finalize the plan when the user confirms
set_plan_from_planning_complete 3 Parse/store a <planning_complete> planner response
execute_plan 4 Return worker bootstrap payload for execution
set_execution_from_execution_report 4 Parse/store <execution_report> and update retry state
retry_execution 4 Return resume bootstrap payload from last failed step
prepare_aws_deployment 5 Return deployment target and steering files for AWS
cleanup Post Remove test documents on user request

The following execution/knowledge tools are also exposed: create_index, create_and_attach_pipeline, create_bedrock_embedding_model, create_local_pretrained_model, apply_capability_driven_verification, launch_search_ui, set_search_ui_suggestions, read_knowledge_base, read_dense_vector_models, read_sparse_vector_models, search_opensearch_org.

Advanced tools are hidden by default; set OPENSEARCH_MCP_ENABLE_ADVANCED_TOOLS=true to expose them.

Localhost index auth (source_type="localhost_index")

Mode Behavior
"default" Username admin, password myStrongPassword123!
"none" No authentication
"custom" Requires localhost_auth_username + localhost_auth_password

Local Docker auto-bootstrap uses admin and reads the password from OPENSEARCH_PASSWORD (falls back to myStrongPassword123!).

Planner backend in MCP mode

  • Planning uses client sampling (client LLM only — no server-side Bedrock in MCP mode).
  • If the client does not support sampling/createMessage, start_planning returns manual_planning_required=true with manual_planner_system_prompt and manual_planner_initial_input. Run planner turns with your LLM and call set_plan_from_planning_complete(planner_response).

Release Checklist

# 1) Bump version in both files to the same value, e.g. 0.10.1
#    - pyproject.toml: [project].version
#    - opensearch_orchestrator/__init__.py: __version__

# Optional sanity check:
python -c "import tomllib; p=tomllib.load(open('pyproject.toml','rb')); import opensearch_orchestrator as pkg; print('pyproject=', p['project']['version'], 'package=', pkg.__version__)"

# 2) All tests must pass
uv run pytest -q

# 3) Build and verify artifacts
uv build
for whl in dist/*.whl; do python -m zipfile -l "$whl"; done
python -c "import opensearch_orchestrator.mcp_server as m; print(hasattr(m, 'main'))"

# Smoke-test the wheel
VERSION="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
WHEEL_PATH="$(ls dist/opensearch_orchestrator-${VERSION}-*.whl)"
uvx --from "$WHEEL_PATH" opensearch-orchestrator

# 4) Publish to PyPI
uv publish --token pypi-YOUR-TOKEN

Metadata

Release files for opensearch-orchestrator 0.2.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opensearch-orchestrator 0.2.9
File Size Uploaded Provenance Actions
opensearch_orchestrator-0.2.9.tar.gz 2.3 MB Without provenance Details for opensearch_orchestrator-0.2.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opensearch-orchestrator 0.2.9
File Interpreter ABI Platform Actions
opensearch_orchestrator-0.2.9-py3-none-any.whl Python 3 none any Details for opensearch_orchestrator-0.2.9-py3-none-any.whl

Total release size: 4.6 MB

Release files / opensearch_orchestrator-0.2.9.tar.gz

Download URL opensearch_orchestrator-0.2.9.tar.gz
Size 2.3 MB
Tags Source
SHA-256 checksum
How to use checksums
8ed70731c7bb861acd0fa956c5bf85d9ea2a0e075927cfce93782600a6e4a015
BLAKE2b-256 checksum
How to use checksums
b24e2c945f54a305cd390ed08082329f34e4b93ca77b7e757e042e5dca0faf98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.8

Release files / opensearch_orchestrator-0.2.9-py3-none-any.whl

Download URL opensearch_orchestrator-0.2.9-py3-none-any.whl
Size 2.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
45bc3656bc0583a7b59a76ea2d1f28b5aaf6bcddc000192d2fdf5b285995955d
BLAKE2b-256 checksum
How to use checksums
30cff12882b3b8314d33543fadb3dbc24b1a8f17b3a26bd96ca82a9ccf750d0c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.8

Security for opensearch-orchestrator 0.2.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page