可同步命令行MCP服务器

本地开发与测试

先决条件

• Rust 1.70+ (rustup update)
• Python 3.8+（用于客户端测试）
• uv (brew install uv 在macOS上)

从源代码构建

1. 克隆仓库：

git clone https://github.com/your-org/syncable-cli-mcp-server.git
cd syncable-cli-mcp-server

2. 构建项目：

# 调试构建
cargo build

# 发布构建
cargo build --release

二进制文件将在以下位置可用：

• 调试：./target/debug/mcp-stdio 和 ./target/debug/mcp-sse
• 发布：./target/release/mcp-stdio 和 ./target/release/mcp-sse

测试MCP服务器

1. 测试Rust组件：

# 运行单元测试
cargo test

# 带日志运行
RUST_LOG=debug cargo test

2. 使用Python客户端进行手动测试：

首先，在终端中启动MCP服务器：

# 对于stdio模式
cargo run --bin mcp-stdio

# 对于SSE模式（在另一个终端中）
cargo run --bin mcp-sse

然后在另一个终端中设置Python环境：

# 设置Python环境
cd mcp-python-server-client

# 使用uv创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装依赖项
uv pip install -r requirements.txt
# 或者使用sync如果你有requirements.lock
uv sync

# 测试stdio模式
uv run python -m src.mcp_py_client_rust_server_stdio

# 测试SSE模式
uv run python src.mcp_py_client_rust_server_sse

3. 验证可用工具：

服务器启动时应显示可用工具。你应该看到：

• about_info
• analysis_scan
• security_scan
• dependency_scan

4. 测试每个工具：

# 例如使用stdio模式
cargo run --bin mcp-stdio

在另一个终端中：

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async def test_tools():
    async with stdio_client(
        StdioServerParameters(command="../target/debug/mcp-stdio")
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 测试about_info
            result = await session.call_tool("about_info", {})
            print("关于信息:", result)
            
            # 测试analysis_scan
            result = await session.call_tool("analysis_scan", 
                {"path": ".", "display": "矩阵"})
            print("分析扫描:", result)
            
            # 测试security_scan
            result = await session.call_tool("security_scan", {"path": "."})
            print("安全扫描:", result)
            
            # 测试dependency_scan
            result = await session.call_tool("dependency_scan", {"path": "."})
            print("依赖扫描:", result)

asyncio.run(test_tools())

5. 与LangGraph集成测试：

# 安装LangGraph依赖项
uv add langgraph openai python-dotenv langchain_mcp_adapters

# 测试stdio集成
uv run python -m src.langgraph_stdio_demo

# 测试SSE集成
uv run python -m src.langgraph_sse_demo

常见问题及调试

1. 端口已被占用（SSE模式）：

lsof -i :8000  # 检查端口8000是否被占用
kill -9 <PID>  # 如需，请终止进程

2. 找不到二进制文件（stdio模式）：

• 确保Python客户端中的二进制路径与你的构建位置匹配
• 检查cargo build是否成功
• 验证二进制文件权限（如需，使用chmod +x）

3. 启用调试日志：

# 对于Rust服务器
RUST_LOG=debug cargo run --bin mcp-stdio

# 对于Python客户端
uv python -c "import logging; logging.basicConfig(level=logging.DEBUG)"

自动发布流程使用release-plz

我们使用release-plz来自动化版本管理和发布。工作流配置在.github/workflows/release-plz.yml。

1. 设置：

# 安装release-plz
cargo install release-plz

# 配置GitHub令牌
export GITHUB_TOKEN=your_github_token
export CARGO_REGISTRY_TOKEN=your_crates_io_token

2. 检查发布状态：

# 预览将要发布的项目
release-plz check

3. 发布流程：

• 将更改推送到main分支
• GitHub Actions将自动：
  • 更新Cargo.toml中的版本
  • 生成变更日志条目
  • 创建发布PR或直接发布
  • 准备后推送至crates.io

4. 手动发布（如有需要）：

# 创建变更日志并提升版本
release-plz release

# 只更新变更日志
release-plz update-changelog

手动预发布检查清单

在发布到crates.io之前：

1. 所有测试通过：cargo test
2. 代码已格式化：cargo fmt --all -- --check
3. 无clippy警告：cargo clippy -- -D warnings
4. 文档是最新的：cargo doc --no-deps
5. 版本在以下位置已更新：
   • Cargo.toml
   • CHANGELOG.md
6. Python客户端示例工作正常
7. 已测试两种传输模式（stdio/SSE）

发布过程

仅在本地测试成功后：

# 登录到crates.io
cargo login

# 干运行
cargo publish --dry-run

# 实际发布
cargo publish