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.pyinstead.
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
- 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"]
}
}
}
- Restart Claude Desktop. The
opensearch_workflowprompt 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_planningreturnsmanual_planning_required=truewithmanual_planner_system_promptandmanual_planner_initial_input. Run planner turns with your LLM and callset_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.