# mcplint

**Repository Path**: codelint/mcplint

## Basic Information

- **Project Name**: mcplint
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCPLint

MCP（Model Context Protocol）规范合规性测试工具。该工具帮助您验证 MCP 服务器实现是否符合 MCP 规范。

## 功能特性

- **零第三方依赖**：使用纯 Go 标准库构建
- **多协议支持**：支持 HTTP 和 stdio 协议
- **版本特定验证**：工厂模式支持多个 MCP 规范版本
- **全面的测试覆盖**：采用 TDD 方法进行广泛的单元测试
- **灵活的配置**：基于 JSON 的配置和自定义测试用例
- **详细的报告**：JSON 输出包含详细的测试结果和计时信息
- **快速测试模式**：无需配置文件即可快速测试
- **工具调用模式**：直接调用工具进行调试和测试
- **模板生成**：自动生成配置模板

## 项目结构

```
mcplint/
├── cmd/
│   └── mcplint/                  # 主程序入口
│       └── main.go
├── config/                     # 配置模块
│   ├── config.go
│   ├── config_test.go
│   └── example.json
├── core/
│   ├── client/                 # HTTP 客户端模块
│   │   ├── client.go
│   │   └── client_test.go
│   ├── protocol/               # 协议模型
│   │   └── protocol.go
│   └── validator/             # 验证逻辑
│       ├── validator.go
│       ├── validator_test.go
│       ├── factory.go
│       └── v20250618/
│           ├── validator.go
│           └── validator_test.go
├── docs/                       # 文档
├── go.mod
└── README.md
```

## 安装

### 前置要求

- Go 1.21 或更高版本

### 从源码构建

```bash
go build -o mcplint ./cmd/mcplint
```

## 使用方法

### 快速测试模式（最快）

无需创建配置文件即可测试 MCP 服务器：

```bash
./mcplint -quick-test http://localhost:8080/mcp
```

使用自定义请求头：

```bash
./mcplint -quick-test http://localhost:8080/mcp -H "Authorization: Bearer token"
```

### 工具调用模式

直接调用特定的 MCP 工具：

```bash
./mcplint -call-tool -config config.json -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

从标准输入读取：

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./mcplint -call-tool -config config.json -d -
```

### 生成配置模板

生成模板配置文件：

```bash
./mcplint -generate-template my-config.json
```

### 完整验证模式

```bash
./mcplint -config config/example.json
```

### 命令行选项

- `-config`：配置文件路径（完整验证模式必需）
- `-quick-test`：快速测试模式，指定 MCP 服务器 URL
- `-call-tool`：工具调用模式，直接调用工具
- `-generate-template`：生成模板配置文件
- `-H`：HTTP 请求头（可多次使用）
- `-d`：工具调用模式的 POST 数据（JSON 字符串或 `-` 表示从标准输入读取）
- `-version`：显示版本信息
- `-help`：显示帮助信息
- `-verbose`：启用详细输出

### 配置文件格式

配置文件使用 JSON 格式：

```json
{
  "target": "http://localhost:8080",
  "protocol": "http",
  "version": "2025-06-18",
  "timeout": 30,
  "headers": {
    "Content-Type": "application/json"
  },
  "test_cases": [
    {
      "id": "test1",
      "description": "测试初始化方法",
      "request": {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "2025-06-18",
          "capabilities": {},
          "clientInfo": {
            "name": "test-client",
            "version": "1.0.0"
          }
        }
      },
      "expected": {
        "fields": {
          "result.protocolVersion": "2025-06-18"
        }
      }
    }
  ]
}
```

### 配置字段说明

- `target`：MCP 服务器 URL（必需）
- `protocol`：协议类型 - "http" 或 "stdio"（必需）
- `version`：MCP 规范版本（必需）
- `timeout`：请求超时时间，单位秒（默认：30）
- `headers`：自定义 HTTP 请求头（可选）
- `test_cases`：测试用例数组（必需）

### 测试用例字段

- `id`：唯一的测试用例标识符（必需）
- `description`：测试用例描述（必需）
- `request`：MCP 请求对象（必需）
- `expected`：预期响应验证（可选）
  - `status_code`：预期的 HTTP 状态码
  - `error_code`：预期的错误代码
  - `fields`：预期的字段值（使用点号表示法表示嵌套字段）

## 输出格式

工具输出 JSON 结果：

```json
{
  "version": "2025-06-18",
  "target": "http://localhost:8080",
  "total": 5,
  "passed": 4,
  "failed": 1,
  "test_cases": [
    {
      "id": "test1",
      "description": "测试初始化方法",
      "passed": true,
      "message": "所有检查通过",
      "elapsed_time": "15ms"
    }
  ],
  "timestamp": "2025-01-10T10:30:00Z"
}
```

## 跨平台编译

### Linux

```bash
GOOS=linux GOARCH=amd64 go build -o mcplint-linux-amd64 ./cmd/mcplint
```

### Windows

```bash
GOOS=windows GOARCH=amd64 go build -o mcplint-windows-amd64.exe ./cmd/mcplint
```

### macOS

```bash
GOOS=darwin GOARCH=amd64 go build -o mcplint-darwin-amd64 ./cmd/mcplint
GOOS=darwin GOARCH=arm64 go build -o mcplint-darwin-arm64 ./cmd/mcplint
```

### ARM 架构（如树莓派）

```bash
GOOS=linux GOARCH=arm64 go build -o mcplint-linux-arm64 ./cmd/mcplint
```

### 一次性编译所有平台

创建一个编译脚本 `build.sh`：

```bash
#!/bin/bash

echo "开始编译 MCPLint..."

# Linux
GOOS=linux GOARCH=amd64 go build -o bin/mcplint-linux-amd64 ./cmd/mcplint
echo "✓ Linux AMD64 编译完成"

# Windows
GOOS=windows GOARCH=amd64 go build -o bin/mcplint-windows-amd64.exe ./cmd/mcplint
echo "✓ Windows AMD64 编译完成"

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o bin/mcplint-darwin-amd64 ./cmd/mcplint
echo "✓ macOS Intel 编译完成"

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o bin/mcplint-darwin-arm64 ./cmd/mcplint
echo "✓ macOS Apple Silicon 编译完成"

# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o bin/mcplint-linux-arm64 ./cmd/mcplint
echo "✓ Linux ARM64 编译完成"

echo "所有平台编译完成！"
```

运行编译脚本：

```bash
chmod +x build.sh
./build.sh
```

## 使用示例

### 示例 1：快速测试本地服务器

```bash
# 测试本地运行的 MCP 服务器
./mcplint -quick-test http://127.0.0.1:8080/mcp
```

### 示例 2：使用认证头测试

```bash
# 使用 Bearer Token 认证
./mcplint -quick-test https://api.example.com/mcp \
  -H "Authorization: Bearer your-token-here"
```

### 示例 3：生成配置并运行完整测试

```bash
# 1. 生成配置模板
./mcplint -generate-template my-test.json

# 2. 编辑配置文件（修改 target、headers 等）
vim my-test.json

# 3. 运行完整测试
./mcplint -config my-test.json
```

### 示例 4：调用特定工具

```bash
# 列出所有可用工具
./mcplint -call-tool -config config.json \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 调用特定工具
./mcplint -call-tool -config config.json \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://example.com"}}}'
```

### 示例 5：从文件读取工具调用数据

```bash
# 创建请求文件
cat > request.json << EOF
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
EOF

# 使用文件内容调用工具
cat request.json | ./mcplint -call-tool -config config.json -d -
```

### 示例 6：批量测试多个配置

```bash
#!/bin/bash

# 测试所有配置文件
for config in config/*.json; do
  echo "正在测试: $config"
  ./mcplint -config "$config" > "results/$(basename $config .json)-result.json"
  echo "完成: $config"
done
```

### 示例 7：在 CI/CD 中使用

```yaml
# .github/workflows/test.yml
name: MCP 服务器测试

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: 设置 Go
        uses: actions/setup-go@v2
        with:
          go-version: '1.21'
      
      - name: 编译 MCPLint
        run: go build -o mcplint ./cmd/mcplint
      
      - name: 启动 MCP 服务器
        run: ./start-mcp-server.sh &
      
      - name: 等待服务器启动
        run: sleep 5
      
      - name: 运行测试
        run: ./mcplint -config config/test.json
      
      - name: 上传测试结果
        uses: actions/upload-artifact@v2
        with:
          name: test-results
          path: results/*.json
```

## 架构设计

### 核心组件

1. **配置模块**：处理配置加载和验证
2. **客户端模块**：用于发送 MCP 请求的 HTTP 客户端
3. **协议模块**：定义 MCP 规范接口和数据结构
4. **验证器模块**：MCP 合规性的核心验证逻辑
5. **工厂模块**：创建特定版本的验证器

### 设计模式

- **工厂模式**：用于创建特定版本的验证器
- **基于接口的设计**：提高可扩展性和可测试性
- **依赖注入**：实现组件之间的松耦合

## 测试

### 运行所有测试

```bash
go test ./... -v
```

### 运行特定模块的测试

```bash
go test ./config -v
go test ./core/client -v
go test ./core/validator -v
```

### 测试覆盖率

项目为所有模块维护高测试覆盖率，包含全面的单元测试。

## 开发

### 添加新的规范版本

1. 在 `core/validator/` 下创建新的版本目录
2. 实现 `MCPSpec` 接口
3. 在工厂中注册该版本
4. 添加全面的测试

### 代码风格

- 遵循 Go 最佳实践和约定
- 使用有意义的变量和函数名
- 为新功能编写全面的测试
- 记录公共 API

## 文档

- [用户指南](docs/USER_GUIDE.md) - 详细的使用说明和示例
- [开发者指南](docs/DEVELOPER_GUIDE.md) - 开发指南和架构说明
- [项目文档](docs/README.en.md) - 项目详细文档（英文版）

## 许可证

本项目按原样提供，用于 MCP 规范合规性测试。

## 贡献

欢迎贡献！请确保：
- 所有测试通过
- 代码遵循现有模式
- 新功能包含测试
- 文档已更新