mcp_stdio_proxy/client/support/
args.rs

1//! CLI 参数定义
2//!
3//! 定义所有命令行参数结构体
4
5use clap::Parser;
6use std::path::PathBuf;
7
8/// 通用日志配置参数
9///
10/// 用于多个命令之间共享日志配置
11#[derive(Parser, Debug, Clone)]
12pub struct LoggingArgs {
13    /// 启用详细诊断模式，输出连接和工具调用的详细时间信息（默认关闭
14    #[arg(
15        long,
16        default_value = "false",
17        help = "启用详细诊断模式，追踪连接生命周期和超时问题（默认关闭)"
18    )]
19    pub diagnostic: bool,
20
21    /// 日志输出目录（自动生成文件名）
22    #[arg(long, help = "日志输出目录，将自动生成日志文件名")]
23    pub log_dir: Option<PathBuf>,
24
25    /// 日志文件完整路径（手动指定）
26    #[arg(long, conflicts_with = "log_dir", help = "日志文件完整路径")]
27    pub log_file: Option<PathBuf>,
28
29    /// OTLP 追踪端点（如 http://localhost:4317）
30    ///
31    /// 启用 diagnostic 模式时，可配置此参数将追踪数据发送到 Jaeger 等 OTLP 兼容的后端。
32    /// 支持 gRPC (端口 4317) 和 HTTP (端口 4318) 协议。
33    #[arg(
34        long,
35        env = "OTEL_EXPORTER_OTLP_ENDPOINT",
36        help = "OTLP 追踪端点 (如 http://localhost:4317)"
37    )]
38    pub otlp_endpoint: Option<String>,
39
40    /// 追踪服务名称（用于 Jaeger 等追踪后端标识）
41    #[arg(
42        long,
43        default_value = "mcp-proxy",
44        help = "追踪服务名称（用于 Jaeger 等追踪后端标识）"
45    )]
46    pub service_name: String,
47}
48
49/// MCP-Proxy CLI 主命令结构
50#[derive(Parser, Debug)]
51#[command(name = "mcp-proxy")]
52#[command(version = env!("CARGO_PKG_VERSION"))]
53#[command(about = "MCP 协议转换代理工具", long_about = None)]
54pub struct Cli {
55    #[command(subcommand)]
56    pub command: Option<Commands>,
57
58    /// 直接URL模式（向后兼容）
59    #[arg(value_name = "URL", help = "MCP 服务的 URL 地址（直接模式）")]
60    pub url: Option<String>,
61
62    /// 全局详细输出
63    #[arg(short, long, global = true)]
64    pub verbose: bool,
65
66    /// 全局静默模式
67    #[arg(short, long, global = true)]
68    pub quiet: bool,
69}
70
71#[derive(clap::Subcommand, Debug)]
72pub enum Commands {
73    /// 协议转换模式 - 将 URL 转换为 stdio
74    Convert(ConvertArgs),
75
76    /// 检查服务状态
77    Check(CheckArgs),
78
79    /// 协议检测
80    Detect(DetectArgs),
81
82    /// 代理模式 - 将 stdio MCP 服务代理为 HTTP/SSE 服务
83    Proxy(crate::client::proxy_server::ProxyArgs),
84
85    /// 健康检查 - 验证 MCP 服务是否可用
86    Health(HealthArgs),
87}
88
89/// 协议转换参数
90#[derive(Parser, Debug, Clone)]
91pub struct ConvertArgs {
92    /// MCP 服务的 URL 地址（可选，与 --config/--config-file 二选一）
93    #[arg(value_name = "URL", help = "MCP 服务的 URL 地址")]
94    pub url: Option<String>,
95
96    /// MCP 服务配置 JSON
97    #[arg(long, conflicts_with = "config_file", help = "MCP 服务配置 JSON")]
98    pub config: Option<String>,
99
100    /// MCP 服务配置文件路径
101    #[arg(long, conflicts_with = "config", help = "MCP 服务配置文件路径")]
102    pub config_file: Option<PathBuf>,
103
104    /// MCP 服务名称（多服务配置时必需）
105    #[arg(short, long, help = "MCP 服务名称（多服务配置时必需）")]
106    pub name: Option<String>,
107
108    /// 指定远程服务协议类型（不指定则自动检测）
109    #[arg(long, value_enum, help = "指定远程服务协议类型（不指定则自动检测）")]
110    pub protocol: Option<crate::client::proxy_server::ProxyProtocol>,
111
112    /// 认证 header (如: "Bearer token")
113    #[arg(short, long, help = "认证 header")]
114    pub auth: Option<String>,
115
116    /// 自定义 HTTP headers
117    #[arg(short = 'H', long, value_parser = parse_key_val, help = "自定义 HTTP headers (KEY=VALUE 格式)")]
118    pub header: Vec<(String, String)>,
119
120    /// 重试次数
121    #[arg(long, default_value = "0", help = "重试次数，0 表示无限重试")]
122    pub retries: u32,
123
124    /// 工具白名单（逗号分隔），只允许指定的工具
125    #[arg(
126        long,
127        value_delimiter = ',',
128        help = "工具白名单（逗号分隔），只允许指定的工具"
129    )]
130    pub allow_tools: Option<Vec<String>>,
131
132    /// 工具黑名单（逗号分隔），排除指定的工具
133    #[arg(
134        long,
135        value_delimiter = ',',
136        help = "工具黑名单（逗号分隔），排除指定的工具"
137    )]
138    pub deny_tools: Option<Vec<String>>,
139
140    /// 客户端 ping 间隔（秒），0 表示禁用
141    #[arg(
142        long,
143        default_value = "30",
144        help = "客户端 ping 间隔（秒），0 表示禁用"
145    )]
146    pub ping_interval: u64,
147
148    /// 客户端 ping 超时（秒）
149    #[arg(
150        long,
151        default_value = "10",
152        help = "客户端 ping 超时（秒），超时则认为连接断开"
153    )]
154    pub ping_timeout: u64,
155
156    /// 日志配置（使用通用结构）
157    #[command(flatten)]
158    pub logging: LoggingArgs,
159}
160
161/// 检查参数
162#[derive(Parser, Debug)]
163pub struct CheckArgs {
164    /// 要检查的 MCP 服务 URL
165    #[arg(value_name = "URL")]
166    pub url: String,
167
168    /// 认证 header
169    #[arg(short, long)]
170    pub auth: Option<String>,
171
172    /// 超时时间
173    #[arg(long, default_value = "10")]
174    pub timeout: u64,
175}
176
177/// 协议检测参数
178#[derive(Parser, Debug)]
179pub struct DetectArgs {
180    /// 要检测的 MCP 服务 URL
181    #[arg(value_name = "URL")]
182    pub url: String,
183
184    /// 认证 header
185    #[arg(short, long)]
186    pub auth: Option<String>,
187}
188
189/// 健康检查参数
190#[derive(Parser, Debug)]
191#[command(after_help = "\
192退出码:
193  0  服务健康 - MCP 连接握手成功
194  1  服务不健康 - 连接失败、超时或握手失败
195
196示例:
197  # 基本用法
198  mcp-proxy health http://localhost:8080/mcp
199
200  # 带认证
201  mcp-proxy health http://localhost:8080/mcp -a \"Bearer token123\"
202
203  # 指定协议和超时
204  mcp-proxy health http://localhost:8080/mcp --protocol sse --timeout 5
205
206  # 静默模式（仅返回退出码，适合脚本使用）
207  mcp-proxy health http://localhost:8080/mcp -q
208
209  # 在 shell 脚本中使用
210  if mcp-proxy health http://localhost:8080/mcp -q; then
211      echo \"MCP 服务正常\"
212  else
213      echo \"MCP 服务不可用\"
214  fi
215")]
216pub struct HealthArgs {
217    /// 要检查的 MCP 服务 URL
218    #[arg(value_name = "URL")]
219    pub url: String,
220
221    /// 认证 header (如: "Bearer token")
222    #[arg(short, long, help = "认证 header")]
223    pub auth: Option<String>,
224
225    /// 自定义 HTTP headers
226    #[arg(short = 'H', long, value_parser = parse_key_val, help = "自定义 HTTP headers (KEY=VALUE 格式)")]
227    pub header: Vec<(String, String)>,
228
229    /// 超时时间（秒）
230    #[arg(long, default_value = "10")]
231    pub timeout: u64,
232
233    /// 指定远程服务协议类型（不指定则自动检测）
234    #[arg(long, value_enum, help = "指定远程服务协议类型（不指定则自动检测）")]
235    pub protocol: Option<crate::client::proxy_server::ProxyProtocol>,
236}
237
238/// 解析 KEY=VALUE 格式的辅助函数
239pub fn parse_key_val(s: &str) -> Result<(String, String), String> {
240    let pos = s
241        .find('=')
242        .ok_or_else(|| format!("无效的 KEY=VALUE 格式: {}", s))?;
243    Ok((s[..pos].to_string(), s[pos + 1..].to_string()))
244}
mcp_stdio_proxy/client/support/args.rs

mcp_stdio_proxy/client/support/
args.rs
