awslabs/mcp项目开发者指南：从环境搭建到代码提交全流程解析

awslabs/mcp项目开发者指南：从环境搭建到代码提交全流程解析

mcp AWS MCP Servers — a suite of specialized MCP servers that bring AWS best practices directly to your development workflow 项目地址: https://gitcode.com/gh_mirrors/mcp15/mcp

项目概述

awslabs/mcp是一个基于Model Context Protocol（MCP）框架的服务端项目集合。MCP是一种用于构建和集成上下文感知模型服务的协议标准，该项目包含了多个实现不同功能的MCP服务器示例和模板。

开发环境准备

基础工具安装

在开始开发前，需要确保本地环境已安装以下工具：

1. pre-commit：用于在代码提交前自动执行代码质量检查
2. uv：Python虚拟环境和依赖管理工具
3. Python 3.10：项目要求的Python版本
4. Git：版本控制系统

对于需要与AWS服务交互的服务器，还需要配置AWS CLI：

aws configure --profile [your-profile]

按照提示输入AWS访问密钥、密钥ID、默认区域等信息。

项目初始化与配置

1. 获取项目代码

建议通过fork方式获取项目代码，这样可以方便后续的代码修改和提交。

2. 安装pre-commit钩子

在项目根目录执行：

pre-commit install

这将安装代码提交前的自动检查机制，确保代码质量。

开发新MCP服务器

使用模板创建新服务器

项目提供了cookiecutter模板，可快速生成新服务器骨架：

uvx cookiecutter --checkout cookiecutters --output-dir ./src --directory python

执行后会交互式询问服务器名称、描述等信息，完成后会在src目录下生成对应的服务器目录。

依赖管理

服务器依赖通过pyproject.toml管理，有两种添加方式：

1. 使用uv命令行工具：

uv add {dependency_name}

2. 直接编辑pyproject.toml文件：

dependencies = [
    "dependency1",
    "dependency2"
]

添加依赖后，创建虚拟环境并同步依赖：

uv venv && uv sync --all-groups

开发与测试

本地开发配置

开发时可以通过修改客户端JSON设置文件来指向本地服务器：

"awslabs.aws-documentation-mcp-server": {
    "command": "uv",
    "args": [
        "--directory",
        "/path/to/your/server",
        "run",
        "server.py"
    ],
    "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
    }
}

使用MCP Inspector测试

MCP提供了Inspector工具用于测试和调试服务器：

npx @modelcontextprotocol/inspector \
  uv \
  --directory /path/to/your/server \
  run \
  server.py

启动后可通过浏览器访问本地服务地址（如http://127.0.0.1:6274）进行测试。

单元测试

每个MCP服务器都应包含完整的单元测试，测试覆盖率应达到或超过项目现有水平。

运行测试命令：

uv run --frozen pytest --cov --cov-branch --cov-report=term-missing

测试应放在服务器的tests目录下，可参考现有服务器的测试结构。

文档编写

良好的文档是项目的重要组成部分，需要：

1. 确保README符合项目统一风格
2. 在docs/servers下为服务器添加新文档页
3. 更新mkdocs.yml中的导航配置
4. 本地预览文档：

mkdocs serve

代码提交与PR流程

提交规范

建议使用Conventional Commits规范提交信息：

类型(范围): 描述

[可选正文]

[可选脚注]

常见类型包括：

• feat：新功能
• fix：错误修复
• docs：文档变更
• style：代码格式调整
• refactor：代码重构
• test：测试相关
• chore：构建或辅助工具变更

处理检测到的密钥

如果pre-commit检测到可能的密钥泄露：

detect-secrets scan --baseline .secrets.baseline
detect-secrets audit .secrets.baseline

审计并确认检测结果后，更新基线文件。

创建Pull Request

完成本地开发和测试后：

1. 推送代码到个人fork仓库
2. 创建PR到主仓库
3. 关注CI测试结果并及时修复问题
4. 参与代码审查讨论

PR合并后，新服务器将由项目团队负责发布到相应的包管理器。

开发建议

1. 代码结构：参考现有服务器组织代码结构
2. 测试覆盖：确保新功能有对应的测试用例
3. 文档同步：代码变更时及时更新相关文档
4. 依赖管理：谨慎添加新依赖，优先使用项目已有依赖
5. 日志规范：使用统一的日志级别和格式

通过遵循这些指南，开发者可以高效地为awslabs/mcp项目贡献代码，构建符合MCP标准的高质量服务器实现。

mcp AWS MCP Servers — a suite of specialized MCP servers that bring AWS best practices directly to your development workflow 项目地址: https://gitcode.com/gh_mirrors/mcp15/mcp