带基岩和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凭据
安装
- 克隆存储库：
git clone git@github.com:rithin-pullela-aws/opensearch-mcp-server-with-bedrock-and-strands.git
cd opensearch-mcp-server-with-bedrock-and-strands- 安装依赖项：
pip install -r requirements.txt- 设置环境变量：
创建一个 .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"
}
}
}代理人将：
- 理解自然语言查询
- 找到合适的索引
- 分析索引映射
- 生成最佳OpenSearch DSL查询
- 执行搜索并返回结果
在本地运行代理
要在本地测试代理：
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运作原理
- 自然语言输入：用户以自然语言提供查询
- 上下文收集：代理使用MCP工具发现索引和映射
- 查询计划：代理使用上下文调用查询计划器工具（QPT）
- DSL生成：代理生成有效的OpenSearch DSL
- 验证：代理验证DSL是否覆盖了用户的意图
- 执行：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报告和修复
- 功能请求和实现
- 文档改进
- 示例用例和教程
请随时：
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
该项目根据 Apache许可证2.0 -看看 许可证 文件以获取详细信息。
您可以出于任何目的自由使用、修改和分发此软件，包括商业应用程序。Apache 2.0许可证还明确授予贡献者向用户授予专利权。
支持
如果您遇到问题或有疑问：
- 在GitHub上打开一个问题
- 检查现有问题的解决方案
- 查看上面的故障排除部分
致谢
内置：
- AWS Bedrock -基础模型托管
- 缕 -代理编排框架
- 开放搜索 -搜索和分析引擎
- MCP（模型上下文协议） -工具集成协议