使用Rust和Axum实现的MCP(模型上下文协议)服务器。
特点/特性
- HTTP服务器基于Axum的HTTP服务器,支持SSE(服务器发送事件)
- MCP协议使用rmcp实现完整的模型上下文协议(Full Model Context Protocol)
- 工具支持定义并提供用于人工智能模型交互的工具
- 资源管理提供资源时,正确处理URI
- 提示模板支持动态提示模板
- 实时通信用于实时双向通信的SSE(Server-Sent Events)
- 信号处理优雅地关闭并处理适当的信号
- 安全为生产部署内置的安全功能
安全特性
这台服务器具备以下安全功能:
- 交通运输安全为Web部署提供安全的SSE模式,支持配置绑定地址
- 输入净化(或输入验证/输入清理)所有输入都经过了适当的验证和清理
- 结构化日志记录JSON日志记录可防止日志注入攻击
- 优雅关闭在终止信号时进行适当的清理
- 错误处理安全的错误消息,不泄露实现细节
使用方法
基本用法```bash
Start the server in STDIO mode (default)
cargo run
Start the server in SSE mode with HTTP endpoints
cargo run -- --transport sse --sse-addr 127.0.0.1:8080
Start with custom configuration
cargo run -- --log-dir /var/log/mcp --api-url https://api.example.com
Use a configuration file
cargo run -- --config-file server.toml
Start with debug logging (standard Rust logging)
RUST_LOG=debug cargo run
### 配置
所有服务器配置均通过命令行参数完成:```
ngsi-v2-mcp [OPTIONS]
Options:
-t, --transport Transport type to use [default: stdio] [possible values: stdio, sse]
--sse-addr SSE server bind address [default: 127.0.0.1:3300]
--sse-keep-alive SSE keep-alive interval in seconds [default: 30]
--log-dir Log directory path [default: logs]
--api-url API URL for backend services [default: http://localhost:1026/]
-c, --config-file Optional configuration file path (TOML format)
-h, --help Print help
-V, --version Print version
运输方式
STDIO模式 (默认):
- 服务器通过标准输入/输出进行通信
- 适用于直接的进程间通信
- 被桌面版MCP客户端(如Cursor/VS Code)使用
SSE模式:
- 服务器为SSE通信暴露了HTTP端点
/sse- 用于实时消息的服务器发送事件(Server-Sent Events)端点/message- 客户端消息的POST端点- 适用于基于网络的客户端和远程连接
配置文件
如果你更倾向于使用配置文件(通过指定 --config-file),创建一个 TOML 文件:```toml
log_dir = "logs"
api_url = "http://localhost:1026/"
transport = "stdio"
sse_addr = "127.0.0.1:3300"
sse_keep_alive = 30
注:命令行参数总是会覆盖配置文件中的设置。
## API终端点
### MCP协议端点
- `POST /mcp/sse` - 用于MCP通信的服务器发送事件(Server-Sent Events)端点
- `GET /health` - 健康检查端点
- `GET /schema` - OpenAPI schema 端点
### 开发终点/开发目标
- `GET /docs` - Swagger UI 文档(仅限开发环境)
## 实施
### 添加工具
工具在(某处)中被定义 `src/handlers/` 并注册于 `src/main.rs`:```rust
use agenterra_rmcp::prelude::*;
#[tool]
async fn my_tool(
#[description("Input parameter")] input: String,
) -> Result> {
Ok(format!("Processed: {}", input))
}
添加资源
资源通过MCP协议进行管理,可以表示文件、数据库或任何可访问的数据:```rust
use agenterra_rmcp::prelude::*;
async fn list_resources() -> Vec {
vec![
Resource {
uri: "file:///example.txt".to_string(),
name: Some("Example File".to_string()),
description: Some("An example resource".to_string()),
mime_type: Some("text/plain".to_string()),
}
]
}
### 添加提示
可以为动态内容生成定义提示模板:```rust
use agenterra_rmcp::prelude::*;
async fn get_prompt(name: &str, args: &serde_json::Value) -> Option {
match name {
"example" => Some(PromptMessage {
role: MessageRole::User,
content: MessageContent::Text("Example prompt".to_string()),
}),
_ => None,
}
}
依赖项
- rmcp(注:这个缩写在中文中没有直接对应的含义,它可能是一个特定领域或上下文中的术语,直译为“rmcp”或根据具体上下文可能需要意译为更具体的含义。)MCP协议实现
- 阿克苏姆HTTP 网络框架
- 追踪;追溯日志记录和仪器仪表
- 信号钩优雅关闭时的信号处理
出版限制
⚠️(注意/警告) 重要的这个项目使用了git依赖,因此无法以当前形式发布到crates.io。
这个(或“该”) rmcp 直接从官方的 ModelContextProtocol GitHub 仓库引用依赖项,以确保能够访问最新功能(包括身份验证支持)。要将此项目发布到 crates.io,您需要:
- 等待官方(消息/通知)
rmcp在 crates.io 上发布的版本,其中包含auth特性;特点 - 或者移除那些需要 git 依赖的特性
- 或者在本地提供依赖项
这一限制确保您在开发过程中能够访问完整的、官方的MCP SDK功能。
发展
建筑```bash
cargo build
### 运行测试```bash
cargo test
格式化```bash
cargo fmt
### 代码检查(或代码格式化/代码规范检查)```bash
cargo clippy
运行时热重载
对于开发,你可以使用 cargo watch:```bash
cargo install cargo-watch
cargo watch -x run
## 项目结构```
ngsi-v2-mcp/
├── Cargo.toml # Rust project manifest
├── src/
│ ├── handlers/ # MCP request handlers
│ │ ├── mod.rs # Handler module exports
│ │ └── {endpoint}.rs # Individual endpoint handlers
│ ├── schemas/ # JSON schema files (created during generation)
│ ├── common.rs # Common utilities and error handling
│ ├── config.rs # Server configuration
│ ├── server.rs # MCP server implementation
│ ├── signal.rs # Signal handling for graceful shutdown
│ ├── transport.rs # Transport layer (STDIO/SSE)
│ └── main.rs # Server entry point
├── .env # Environment variables
└── README.md # Project documentation
该结构组织如下:
handlers/- 包含所有MCP工具的实现,每个端点对应一个文件schemas/- 工具参数的JSON模式文件(自动生成)common.rsAPI通信和错误处理的共享实用程序config.rs- 配置管理和命令行解析server.rs- 核心MCP服务器实现,包含协议处理功能signal.rs- 优雅关闭时的信号处理(SIGTERM,SIGINT)transport.rs- 支持STDIO和SSE模式的传输层main.rs- 应用程序入口点和服务器初始化
生产部署
构建发布二进制文件```bash
cargo build --release
### Docker 部署
创建一个 `Dockerfile`:```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/ngsi-v2-mcp /usr/local/bin/server
EXPOSE 3000
CMD ["server"]
环境配置
对于生产,考虑以下因素:
- 设定适当的
RUST_LOG层级;水平 - 配置适当的错误处理
- 建立监控和指标体系
- 实施速率限制
- 添加认证中间件
许可证
此项目遵循MIT许可协议。