Opensearch MCP Server With Bedrock And Strands

带基岩和Strands的OpenSearch MCP服务器


该项目实现了 代理搜索 该系统使用AWS Bedrock、Strands代理框架和模型上下文协议（MCP）将自然语言查询转换为OpenSearch DSL查询。

开源：此项目在Apache 2.0许可证下发布，您可以随意使用、修改和分发！

概述

代理人使用：

• AWS Bedrock （克劳德·十四行诗4.5）自然语言理解
• Strands框架 用于代理编排
• MCP（模型上下文协议） 连接到OpenSearch工具
• 基岩试剂核心 用于运行时管理

该代理可以理解自然语言问题，如“查找500美元以下的鞋子”，并自动生成相应的OpenSearch DSL查询。

先决条件

• Python 3.8+
• 具有基岩访问权限的AWS帐户
• 启用ML Commons插件的OpenSearch集群
• 已配置AWS凭据

安装

1. 克隆存储库：

git clone git@github.com:rithin-pullela-aws/opensearch-mcp-server-with-bedrock-and-strands.git
cd opensearch-mcp-server-with-bedrock-and-strands

1. 安装依赖项：

pip install -r requirements.txt

1. 设置环境变量：

创建一个 .env 项目根目录中的文件（复制自 env.example):

cp env.example .env

编辑 .env 根据您的配置：

# AWS Configuration
AWS_REGION=us-east-1

# Bedrock Model Configuration
BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-5-20250929-v1:0

# OpenSearch Configuration
OPENSEARCH_URL=http://localhost:9200
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=admin

# MCP Configuration
MCP_URL=http://localhost:9200/_plugins/_ml/mcp/
# Optional: Uncomment if you need bearer token authentication
# MCP_BEARER=your-bearer-token-here

# Optional: Customize the system prompt
# SYSTEM_PROMPT_FILE=custom_prompt.txt
# or set it directly:
# SYSTEM_PROMPT="Your custom system prompt..."

重要：The .env 为了安全起见，该文件被标记为无效。永远不要将凭据提交到版本控制！

在OpenSearch中设置代理搜索

按照以下步骤在OpenSearch集群中配置代理搜索：

步骤1：创建连接器工具

创建一个将调用Bedrock代理的连接器：

POST /_plugins/_ml/connectors/_create
{
  "name": "Conenctor to AgentCore",
  "description": "Demo connector of function",
  "version": 1,
  "protocol": "http",
  "parameters": {
    // add if needed
  },
  "credential": {
    "access": "rand"
  },
  "actions": [
    {
      "action_type": "execute",
      "method": "POST",
      "url": "http://localhost:8080/invocations",
      "headers": {
        "content-type": "application/json"
      },
      "request_body": "{ \"prompt\": \"NLQ is: ${parameters.question}, index_name is: ${parameters.index_name:-}, and the model ID for neural search is: ${parameters.embedding_model_id:-}.\" }"
    }
  ]
}

注： 保存 connector_id 从回复中可以看出，下一步你需要它。

步骤2：使用连接器工具创建流代理

注册使用连接器的流代理：

POST /_plugins/_ml/agents/_register
{
    "name": "Agentic Search",
    "type": "flow",
    "description": "this is a test agent",
    "tools": [
        {
            "type": "ConnectorTool",
            "parameters": {
                "connector_id": "PCEKTJoBwAH_C-u4fNUl",  // Replace with your connector_id from Step 1
                "output_processors": [
                    {
                        "type": "jsonpath_filter",
                        "path": "$.inference_results[0].output[0].dataAsMap.content[0].text"
                    }
                ]
            }
        }
    ]
}

注： 保存 agent_id 从回复中可以看出，下一步你需要它。

步骤3：注册搜索管道

创建一个使用代理查询转换器的搜索管道：

PUT /_search/pipeline/no-cache-pipeline
{
    "request_processors": [
        {
            "agentic_query_translator": {
                "agent_id": "7DKRLZoBpTIbg0854Nod"  // Replace with your agent_id from Step 2
            }
        }
    ],
    "response_processors": [
        {
            "agentic_context": {
                "agent_steps_summary": true,
                "dsl_query": true
            }
        }
    ]
}

步骤4：执行代理搜索

现在，您可以使用自然语言查询进行搜索：

POST /_search?search_pipeline=no-cache-pipeline
{
    "query": {
        "agentic": {
            "query_text": "Find Macbook cases from Case Star"
        }
    }
}

代理人将：

1. 理解自然语言查询
2. 找到合适的索引
3. 分析索引映射
4. 生成最佳OpenSearch DSL查询
5. 执行搜索并返回结果

在本地运行代理

要在本地测试代理：

python agent_example.py

代理将开始 http://localhost:8080 并接受调用请求。

测试调用格式

{
    "prompt": "NLQ is: Find shoes under $500, index_name is: products, and the model ID for neural search is: ."
}

项目结构

.
├── agent_example.py      # Main agent implementation with DSL generation logic
├── temp_agent.py         # Simplified agent example
├── requirements.txt      # Python dependencies
└── README.md            # This file

运作原理

1. 自然语言输入：用户以自然语言提供查询
2. 上下文收集：代理使用MCP工具发现索引和映射
3. 查询计划：代理使用上下文调用查询计划器工具（QPT）
4. DSL生成：代理生成有效的OpenSearch DSL
5. 验证：代理验证DSL是否覆盖了用户的意图
6. 执行：OpenSearch执行DSL并返回结果

主要特点

• 零样本DSL生成 从自然语言
• 自动索引发现 和选择
• 模式感知查询构造 不向用户公开模式
• 迭代优化 用于复杂查询
• JSON输出合约 为了实现可靠的集成

配置

所有配置都通过环境变量进行管理(.env 文件）：

所需变量：

• AWS_REGION：基岩的AWS区域（默认值： us-east-1)
• OPENSEARCH_URL：您的OpenSearch集群URL（默认值： http://localhost:9200)
• OPENSEARCH_USERNAME：OpenSearch用户名（默认值： admin)
• OPENSEARCH_PASSWORD：OpenSearch密码（默认值： admin)

可选变量：

• BEDROCK_MODEL_ID：要使用的基岩模型（默认值： us.anthropic.claude-sonnet-4-5-20250929-v1:0)
• MCP_URL：OpenSearch MCP端点（默认值：从OpenSearch_URL自动构造）
• MCP_BEARER：MCP身份验证的承载令牌（覆盖基本身份验证）
• VERIFY_SSL：启用/禁用SSL证书验证（默认值： true，设置为 false 对于自签名证书）
• SYSTEM_PROMPT：自定义系统提示为字符串
• SYSTEM_PROMPT_FILE：包含自定义系统提示的文件路径

自定义系统提示

您可以通过提供自己的系统提示来自定义代理的行为：

选项1：直接环境变量

export SYSTEM_PROMPT="Your custom instructions here..."

选项2：从文件

echo "Your custom instructions here..." > my_prompt.txt
export SYSTEM_PROMPT_FILE=my_prompt.txt

如果两者都没有设置，代理将使用针对OpenSearch DSL生成优化的默认提示。

故障排除

代理返回match_all查询：

• 代理无法理解查询或缺少所需的上下文
• 检查MCP工具是否可访问并返回有效数据

连接错误：

• 验证 MCP_URL 正确且可访问
• 检查AWS凭据是否已配置
• 确保您所在地区已启用基岩模型访问

SSL证书错误：

• 对于自签名证书，设置 VERIFY_SSL=false 在你的 .env 文件
• 警告：仅在开发/测试环境中禁用SSL验证
• 生产时，使用正确签署的证书

生成的DSL无效：

• 查看系统提示是否清晰
• 检查索引映射是否正确
• 验证查询计划器工具是否正常工作

贡献

欢迎投稿！这是一个开源项目，我们感谢：

• Bug报告和修复
• 功能请求和实现
• 文档改进
• 示例用例和教程

请随时：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

许可证

该项目根据 Apache许可证2.0 -看看 许可证 文件以获取详细信息。

您可以出于任何目的自由使用、修改和分发此软件，包括商业应用程序。Apache 2.0许可证还明确授予贡献者向用户授予专利权。

支持

如果您遇到问题或有疑问：

• 在GitHub上打开一个问题
• 检查现有问题的解决方案
• 查看上面的故障排除部分

致谢

内置：

• AWS Bedrock -基础模型托管
• 缕 -代理编排框架
• 开放搜索 -搜索和分析引擎
• MCP（模型上下文协议） -工具集成协议