Release Testing Openserach MCP Server

OpenSearch MCP服务器-发布测试框架

一个全面的、可扩展的测试框架，用于在不同的身份验证方法和部署场景中验证OpenSearch MCP（模型上下文协议）服务器。

🎯 目的

该框架旨在 发布测试 OpenSearch MCP服务器。它提供：

• ✅ 全面的测试覆盖率 适用于所有身份验证方法
• ✅ 多集群测试 支持
• ✅ 可扩展架构 用于添加自定义测试场景
• ✅ 详细日志记录 有组织的输出
• ✅ 简单、可组合的界面 用于编写自定义测试

🚀 快速开始

先决条件

• Python 3.10+
• mcp_server_opensearch 软件包已安装
• 访问OpenSearch集群进行测试

安装

1. 克隆存储库：

   git clone 
   cd sanity_test_release

1. 设置虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项：

   pip install mcp-server-opensearch pyyaml

1. 配置集群：

   # Copy example config files
   cp config/test_clusters.yml.example config/test_clusters.yml
   cp config/mcp_server_multi_mode.yml.example config/mcp_server_multi_mode.yml

   # Edit with your actual credentials
   nano config/test_clusters.yml
   nano config/mcp_server_multi_mode.yml

📋 配置

群集配置(config/test_clusters.yml)

使用身份验证详细信息定义测试集群：

clusters:
  cluster1-basic-auth-ssl:
    opensearch_url: "https://your-cluster.es.amazonaws.com"
    opensearch_username: "admin"
    opensearch_password: "your-password"
    test_index: "your-index-name"
  
  cluster3-aws:
    opensearch_url: "https://your-cluster.es.amazonaws.com"
    aws_region: "us-east-1"
    aws_access_key_id: "YOUR_KEY"
    aws_secret_access_key: "YOUR_SECRET"
    aws_session_token: "YOUR_TOKEN"  # Optional
    test_index: "your-index-name"

看 config/test_clusters.yml.example 适用于所有支持的集群类型。

多模式配置(config/mcp_server_multi_mode.yml)

为多模式测试配置集群：

clusters:
  cluster1-basic-auth-ssl:
    opensearch_url: https://your-cluster.es.amazonaws.com
    opensearch_username: admin
    opensearch_password: your-password

🧪 运行测试

选项1：运行所有测试

python run_all_tests.py

这将按顺序运行所有9个测试场景：

• 基本身份验证（带/不带SSL）
• AWS凭据
• AWS配置文件（命令行界面和环境变量）
• IAM角色
• 基于标头的身份验证
• 多模式（带/不带标头）

选项2：运行单独测试

# Basic authentication
python tests/basic_with_ssl.py
python tests/basic_no_ssl.py

# AWS authentication
python tests/aws_credentials.py
python tests/aws_profile_cli.py
python tests/aws_profile_env.py
python tests/iam_role.py

# Header-based authentication
python tests/header_single.py

# Multi-mode testing
python tests/multi_no_header.py
python tests/multi_with_header.py

选项3：编写自定义测试

看 用法.md 详细示例和API文档。

📊 测试结果

日志文件

测试结果会自动记录到：

test_logs/
  ├── basic_with_ssl/
  │   └── basic_with_ssl_YYYYMMDD_HHMMSS.log
  ├── aws_credentials/
  │   └── aws_credentials_YYYYMMDD_HHMMSS.log
  └── ...

每个日志文件包含：

• 工具调用详细信息
• 响应内容（截断为200个字符）
• 成功/错误状态
• 汇总统计

控制台输出

• 单模测试：逐工具结果的详细输出
• 多模式测试：安静的控制台（日志文件中的所有详细信息），末尾有摘要

🏗️ 框架架构

.
├── config/                    # Configuration files
│   ├── test_clusters.yml     # Cluster definitions (create from .example)
│   ├── mcp_server_multi_mode.yml  # Multi-mode config (create from .example)
│   └── tool_filter.yml       # Tool enablement config
│
├── framework/                # Core framework code
│   ├── clusters.py          # Cluster loading/access
│   ├── server.py            # Server lifecycle management
│   ├── tests.py             # Test execution logic
│   ├── client.py            # MCP client wrapper
│   ├── logging.py           # Logging utilities
│   └── aws_profile.py       # AWS profile helpers
│
├── tests/                    # Test files
│   ├── basic_with_ssl.py
│   ├── aws_credentials.py
│   └── ...
│
├── tool_definitions/        # Tool definitions
│   └── definitions.py       # All 19 OpenSearch tools
│
└── test_logs/               # Generated log files (gitignored)

🔧 框架API

核心功能

from framework import (
    load_clusters,      # Load cluster configs
    get_cluster,        # Get cluster by name
    create_server,      # Start MCP server
    stop_server,        # Stop MCP server
    test_tools,         # Run tool tests
    create_aws_profile_config  # AWS profile helper
)

示例：基本测试

import asyncio
from framework import load_clusters, get_cluster, create_server, stop_server, test_tools
from framework.logging import open_log_file, close_log_file, print_test_summary

async def main():
    open_log_file("my_test")
    try:
        load_clusters()
        cluster = get_cluster("cluster1-basic-auth-ssl")
        
        server = create_server(
            env_dict={
                "OPENSEARCH_URL": cluster["opensearch_url"],
                "OPENSEARCH_USERNAME": cluster["opensearch_username"],
                "OPENSEARCH_PASSWORD": cluster["opensearch_password"],
            },
            command="python -m mcp_server_opensearch --transport stream --config config/tool_filter.yml"
        )
        
        try:
            results = await test_tools(test_index=cluster["test_index"], verbose=True)
            print_test_summary(results, "my_test")
        finally:
            stop_server(server)
    finally:
        close_log_file()

asyncio.run(main())

看 用法.md 更多示例。

🔐 安全

凭据管理

• 配置文件 (config/test_clusters.yml, config/mcp_server_multi_mode.yml)被忽视了
• 示例文件 (.example)作为模板提供
• 日志文件 不包含凭据（仅API响应）
• 临时凭据 写信给 ~/.aws/credentials 测试期间（自动备份）

最佳实践

1. 永不承诺 带有凭据的实际配置文件
2. 使用示例文件 作为模板
3. 查看日志文件 在共享之前（它们可能包含集群名称）
4. 轮换凭据 定期
5. 使用临时凭据 如果可能（会话令牌）

📝 支持的测试场景

🛠️ 故障排除

服务器无法启动

• 检查端口9900是否已在使用中： lsof -i :9900
• 验证 mcp_server_opensearch 已安装： pip list | grep mcp
• 检查测试文件中的服务器命令语法

测试超时

• 增加超时时间 framework/tests.py （默认值：每个工具30秒，总共5-10分钟）
• 检查OpenSearch群集的网络连接
• 验证凭据是否有效且未过期

未找到索引错误

• 确保 test_index 在中设置正确 config/test_clusters.yml
• 验证索引是否存在于OpenSearch集群中
• 检查索引名称拼写

AWS凭据错误

• 验证凭据是否未过期（尤其是会话令牌）
• 检查角色/用户的IAM权限
• 确保 AWS_REGION 设置正确

📚 附加资源

• 用法.md -详细的使用指南和API文档
• config/*.example -配置文件模板
• tests/*.py -示例测试实现

🤝 贡献

添加新测试场景时：

1. 在中创建新的测试文件 tests/
2. 遵循现有测试的模式
3. 使用 open_log_file() 和 close_log_file() 用于日志记录
4. 总是使用 try/finally 确保 stop_server() 被称为
5. 如果添加新的测试类型，请更新此README

📄 许可证

\[在此处添加您的许可证\]

🙋 支持

对于问题或疑问：

• 检查中的现有测试日志 test_logs/
• 审查 用法.md 获取API详细信息
• 查看OpenSearch MCP服务器文档

______________________________________________________________________

备注：此框架是为发布测试而设计的。始终使用测试/测试集群，而不是生产集群。