内容
# use_aws 中间件服务器
## 支持 Codex 的分支
该分支为原始的 `use_aws_mcp` 项目添加了 Codex 支持。
- 原始项目：https://github.com/runjivu/use_aws_mcp
- 该分支：https://github.com/mrzhxl/use_aws_mcp
与上游的主要区别：
- 作为 MCP 客户端与 Codex 配合使用。
- 支持 MCP `Content-Length` 帧的 stdio 消息和换行分隔的 JSON 消息。
- 将跟踪/日志输出发送到 stderr，保持 stdout 清洁以进行 MCP 协议响应。
- 处理 `resources/list` 并带有空资源列表，以便 MCP 客户端可以初始化干净。
🌟 amazon-q-cli 很棒，它之所以伟大，是因为它具有与 AWS API 交互的 `use_aws` 中间件工具。
💡 如果这个 `use_aws` 是可移植的，并且可以在您当前使用的不同 AI 工具中使用，那岂不是更好？
⚡ `use_aws_mcp` 是一个独立的模型上下文协议（MCP）服务器，通过标准化的接口提供 AWS CLI 功能。 \
该服务器复制了 Amazon Q Developer CLI 中 `use_aws` 工具的功能。
## 🎬 演示
- **与 Avante、MCPHub 在 nvim 中一起使用** \
- **与 Cursor 一起使用** \
## ✨ 功能
- **AWS CLI 集成**：使用正确的参数处理执行 AWS CLI 命令
- **安全检查**：自动检测只读与写入操作
- **用户代理管理**：正确的 AWS CLI 用户代理设置用于跟踪
- **参数格式化**：自动将参数转换为 kebab-case 以兼容 CLI
- **错误处理**：全面的错误处理和输出格式化
- **MCP 协议**：完全符合模型上下文协议
- **人类可读的描述**：使用终端格式化显示丰富的命令描述
## 📦 安装
### 📋 先决条件
- 🦀 **Rust（1.70 或更高版本），Cargo**
- 对于 MacOS 和 linux，使用 `curl https://sh.rustup.rs -sSf | sh` 安装
- ☁️ **已安装并配置 AWS CLI**
- 🔑 **已配置 AWS 凭证** （通过 AWS CLI、环境变量或 IAM 角色）
### 🔨 构建
```bash
cargo build --release
```
二进制文件将在 `target/release/use_aws` 处可用。
## 🚀 使用
### 🔗 MCP 客户端集成
要将此服务器与 MCP 客户端一起使用，首先使用 Cargo 安装它：
```sh
cargo install use_aws_mcp
```
然后使用以下配置您的 MCP 客户端：
```json
{
"mcpServers": {
"use_aws_mcp": {
"name": "use_aws_mcp",
"command": "use_aws_mcp",
"timeout": 300,
"env": {},
"disabled": false
}
}
}
```
Codex 配置示例：
```toml
[mcp_servers.use_aws_mcp]
command = "/path/to/use_aws_mcp"
timeout_seconds = 300
startup_timeout_sec = 30
disabled = false
```
#### ⚠️ 使用 MCP 客户端的重要注意事项
使用 q cli 时，mcp 客户端是 shell 进程，因此诸如 `AWS_DEFAULT_PROFILE` 之类的凭证环境会自动传递给 mcp 服务器。
但是，非 shell mcp 客户端（如 cursor）无法利用此优势，因此最好要求 mcp 客户端直接使用特定的 aws 配置文件。
**📋 用户流程：**
1. 设置上述 mcp.json
2. 设置 API 密钥，或使用 `aws sso login` 登录到特定的配置文件
3. 随意提问 mcp 客户端有关 aws 的问题！并确保要求它使用特定的配置文件。
### 在本地运行 MCP 服务器
```bash
./target/release/use_aws_mcp
```
服务器通过 stdin/stdout 使用 JSON-RPC 协议进行通信。
### 命令描述
服务器提供人类可读的 AWS CLI 命令描述。您可以通过运行以下示例来查看此功能：
```bash
cargo run --example description_demo
```
这将输出类似的内容：
```
运行 aws cli 命令：
服务名称：s3
操作名称：list-buckets
参数：
- max-items: "10"
- query: "Buckets[].Name"
配置文件名称：development
区域：us-west-2
标签：列出带有查询的 S3 存储桶
✅ 此命令是只读的（不需要接受）
```
## 🛠️ 工具规范
服务器提供一个名为 `use_aws` 的工具，具有以下架构：
```json
{
"name": "use_aws",
"description": "执行 AWS CLI 命令，并具有正确的参数处理和安全检查",
"inputSchema": {
"type": "object",
"properties": {
"service_name": {
"type": "string",
"description": "AWS 服务名称（例如：s3、ec2、lambda）"
},
"operation_name": {
"type": "string",
"description": "AWS CLI 操作名称（例如：list-buckets、describe-instances）"
},
"parameters": {
"type": "object",
"description": "AWS CLI 命令的可选参数",
"additionalProperties": true
},
"region": {
"type": "string",
"description": "AWS 区域（例如：us-west-2、eu-west-1）"
},
"profile_name": {
"type": "string",
"description": "可选的 AWS 配置文件名称"
},
"label": {
"type": "string",
"description": "操作的标签"
}
},
"required": ["service_name", "operation_name", "region"]
}
}
```
## 📚 示例
### 列出 S3 存储桶
```json
{
"name": "use_aws",
"arguments": {
"service_name": "s3",
"operation_name": "ls",
"region": "us-west-2"
}
}
```
### 描述 EC2 实例
```json
{
"name": "use_aws",
"arguments": {
"service_name": "ec2",
"operation_name": "describe-instances",
"region": "us-west-2",
"parameters": {
"instance-ids": "i-1234567890abcdef0"
}
}
}
```
### 列出具有配置文件的 Lambda 函数
```json
{
"name": "use_aws",
"arguments": {
"service_name": "lambda",
"operation_name": "list-functions",
"region": "us-west-2",
"profile_name": "development"
}
}
```
## 🛡️ 安全功能
### 只读操作检测
服务器根据操作名称前缀自动检测只读操作：
- **只读前缀**：`get`、`describe`、`list`、`ls`、`search`、`batch_get`
- **写入操作**：所有其他操作需要明确的用户接受
### 输出截断
大型输出会自动截断以防止内存问题，最大响应大小为 100KB。
## 开发
### 运行测试
```bash
cargo test
```
### 🔨 开发构建
```bash
cargo build
```
### 运行日志记录
```bash
RUST_LOG=use_aws=debug cargo run
```
### 示例
```bash
# 运行描述演示
cargo run --example description_demo
```
## 架构
项目结构如下：
- `src/lib.rs`：核心库，包含类型和常量
- `src/error.rs`：错误处理类型
- `src/use_aws.rs`：核心 AWS CLI 功能（从原始代码复制）
- `src/mcp_server.rs`：MCP 服务器实现
- `src/main.rs`：二进制入口点
- `examples/description_demo.rs`：演示命令描述的示例
## 📦 依赖项
如果您没有安装 Cargo（Rust 包管理器），可以通过安装 Rust 来获取：
```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
按照屏幕上的说明完成安装。安装后，重启您的终端，并通过运行以下命令确保 Cargo 可用：
```sh
cargo --version
```
您应该看到已安装的 Cargo 版本。
此项目作为 Rust crate 分发。以下依赖项由 Cargo 自动管理：
- `tokio`
- `serde`
- `serde_json`
- `eyre`
- `bstr`
- `convert_case`
- `async-trait`
- `thiserror`
- `tracing`
- `tracing-subscriber`
- `crossterm`
测试/开发依赖项：
- `tokio-test`
您不需要手动安装这些；Cargo 将在安装过程中处理它们。
## 📄 许可证
MIT, Apache-2.0
## 🤝 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求
## 🔒 安全
此服务器执行 AWS CLI 命令，这可能会带来安全影响：
- 确保正确的 AWS 凭证和权限
- 在执行前审查所有命令
- 在可能的情况下使用只读操作
- 考虑在受限环境中运行
## 🔧 故障排除
### 常见问题
1. **未找到 AWS CLI**：确保 AWS CLI 已安装并在 PATH 中
2. **权限被拒绝**：检查 AWS 凭证和权限
3. **无效区域**：验证区域名称是否正确
4. **参数错误**：检查参数名称和值
### 调试模式
运行调试日志记录以查看详细信息：
```bash
RUST_LOG=use_aws=debug ./target/release/use_aws
```
## 参考资料
- [amazon-q-cli](https://github.com/aws/amazon-q-developer-cli)
