内容
# MCP 服务器模板
[中文文档](README.zh.md)
可克隆的最小化 MCP（模型上下文协议）服务器骨架，带有双模式二进制文件：**MCP 服务器**，适用于 AI 助手，和一个小型 **CLI**，适用于人类。附带示例工具 `echo` / `ping`。
## 快速开始
```bash
# 需要 Go 1.25+（参见 .tool-versions）
make build
./bin/mcp-server version
# 启动 MCP 服务器（stdio，默认）
./bin/mcp-server mcp
# 从 CLI 列出/调用工具（无需 MCP 客户端）
./bin/mcp-server tools list
./bin/mcp-server tools call echo --params '{"message":"hello"}'
./bin/mcp-server tools call ping --params '{}'
```
## 功能特点
- **子命令 CLI**：`mcp` 启动服务器；`tools` / `version` / `completion` 是独立命令
- **多传输**：stdio、Streamable HTTP 和 SSE
- **工具过滤**：`--enabled-tools`、`--disabled-tools`、`--enable-domains`、`--disable-domains`
- **工程默认值**：Makefile、Dockerfile、GitHub Actions CI、golangci-lint 配置、MIT 许可证
## CLI 命令
| 命令 | 目的 |
|---------|---------|
| `mcp-server mcp` | 启动 MCP 服务器（stdio 或 HTTP） |
| `mcp-server tools list` | 列出已启用工具 |
| `mcp-server tools describe <name>` | 显示工具模式 |
| `mcp-server tools call <name>` | 调用工具，带 JSON 参数 |
| `mcp-server version` | 打印构建元数据 |
| `mcp-server completion <shell>` | 生成 shell 补全 |
### 工具示例
```bash
./bin/mcp-server tools list
./bin/mcp-server tools list --json
./bin/mcp-server tools describe echo
./bin/mcp-server tools describe echo --json
./bin/mcp-server tools call echo --params '{"message":"hello"}'
echo '{"message":"hello"}' | ./bin/mcp-server tools call echo --params-file -
./bin/mcp-server tools call ping --params '{}'
```
## MCP 传输
### Stdio（默认）
```bash
./bin/mcp-server mcp
```
光标 / 克劳德桌面样式配置：
```json
{
"mcpServers": {
"mcp-server-template": {
"command": "/absolute/path/to/bin/mcp-server",
"args": ["mcp"]
}
}
}
```
### Streamable HTTP
```bash
./bin/mcp-server mcp --port 8080
curl -s http://127.0.0.1:8080/healthz
```
客户端配置示例：
```json
{
"mcpServers": {
"mcp-server-template": {
"url": "http://127.0.0.1:8080/mcp"
}
}
}
```
### SSE
与 HTTP 模式相同的进程。端点：
| 路径 | 目的 |
|------|---------|
| `/healthz` | 健康检查（`GET`/`HEAD`） |
| `/mcp` | Streamable HTTP |
| `/sse` | SSE 连接 |
| `/message` | SSE 消息端点 |
```bash
./bin/mcp-server mcp --port 8080 --sse-base-url http://127.0.0.1:8080
```
### Docker
```bash
# 构建
make docker
# Stdio（默认入口点为 `mcp-server mcp`）
docker run -i --rm mcp-server-template:dev
# HTTP
docker run --rm -p 8080:8080 mcp-server-template:dev --port 8080 --listen 0.0.0.0
```
HTTP / SSE **无身份验证和无 TLS**。默认 `--listen 127.0.0.1`。仅在受信任的网络中使用；在公开端口时，请在前面添加反向代理。
## 配置
优先级：**标志 > 环境变量 > 配置文件 > 默认值**。
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `MCP_LOG_LEVEL` | 日志级别 | `info` |
| `MCP_PORT` | HTTP 端口（`0` = stdio） | `0` |
| `MCP_LISTEN` | HTTP 监听主机 | `127.0.0.1` |
| `MCP_SSE_BASE_URL` | 公共 SSE 基本 URL | `""` |
### 配置文件
参见 `config.example.yaml`:
```yaml
port: 0
listen: 127.0.0.1
sse_base_url: ""
log_level: info
enabled_tools: []
disabled_tools: []
enabled_domains: []
disabled_domains: []
```
```bash
./bin/mcp-server mcp --config config.example.yaml --port 8080
```
## 项目布局
```
cmd/mcp-server/ # 二进制入口点
internal/cmd/ # cobra CLI（mcp / tools / version / completion）
pkg/core/ # 配置 / 日志 / 版本
pkg/server/mcp/ # MCP 注册和传输
pkg/server/http/ # HTTP / SSE / healthz
pkg/toolset/ # 工具集接口和过滤器
pkg/toolset/example/ # 示例工具（替换为您的领域）
.github/workflows/ # CI
```
## 使用您自己的工具扩展
1. 添加 `pkg/toolset/<your-domain>/` 实现 `toolset.Toolset`。
2. 在 `internal/cmd/root.go` 中通过 `defaultToolsets()` 注册它。
3. 使用 `--enabled-tools` / `--enable-domains` 控制暴露。
## 开发
```bash
make tidy
make format
make lint
make test
make coverage
make ci
make build
make docker
```
CI（`.github/workflows/build.yaml`）运行 lint、带有覆盖率上传的竞速测试、多 OS 构建、CLI 烟雾测试（`version` / `tools list`）和 Docker 镜像构建。
## 本地参考克隆
`third-party-projects/` 可以保存本地参考检出。它被列在 `.gitignore` 中，不属于模板交付成果。
## 许可证
[MIT](LICENSE)
