企业官网建设流程全解析

mcp-agent 贡献指南：从环境搭建到代码质量门禁的完整开发工作流

【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent

本文基于仓库根目录下的 CONTRIBUTING.md 编写，系统梳理了向 mcp-agent 提交代码的完整流程：包括基于 uv 的开发环境搭建、Makefile 封装的质量门禁（format / lint / tests / coverage / schema）、面向 LLM 协作的 promptify 脚本，以及 Examples 与 VS Code 编辑器配置等。读者读完本文后，可以独立完成一次符合项目规范的 Pull Request：从 fork 分支、本地开发、自测，到提交前的完整检查项。

mcp-agent 是一个基于 Model Context Protocol（MCP）构建 Agent 的可组合框架（项目描述见 pyproject.toml：Build effective agents with Model Context Protocol using simple, composable patterns）。项目官方明确表示：欢迎所有类型的贡献——bug 修复、大型特性、文档、示例等，贡献者不一定是 AI 专家，甚至不一定是 Python 开发者。这意味着贡献门槛被刻意放低，但质量门禁却一丝不苟。下面按贡献的实际顺序展开。

贡献清单：提交 Pull Request 前的四步自检

CONTRIBUTING.md 将贡献流程收敛为一张清晰的 Checklist，任何贡献都通过 Pull Request 完成：

1. Fork 仓库，并创建以feature/为前缀的功能分支；
2. Lint、类型检查与格式化（Lint, typecheck, and format），对应下文「代码质量」小节；
3. 添加示例（Add examples）；
4. （理想情况）添加测试（Add tests）。

同时文档明确提醒：在开始大型贡献之前，应提前联系 mcp-agent 维护者（通过 GitHub issues 或 Discord），避免重复劳动或方向性偏差。这条约定与仓库中examples目录“用于端到端测试”的定位相辅相成——任何新特性都应有可运行的示例作为验证载体。

环境准备：uv + Python 3.10 是硬性前提

构建 mcp-agent 需要两样东西：

• [uv]（Python 包管理工具）：项目所有开发命令都基于uv run/uv sync执行；
• Python >= 3.10：查看本机版本用python -V；若未安装，可使用uv python install 3.10一键安装。

随后执行：

make sync

这条命令的本质在仓库根目录 Makefile 中可查证：

sync: uv sync --all-extras --all-packages --group dev

即同步全部 extras、全部 packages 以及 dev 依赖组。其中--all-extras会安装 pyproject.toml 中声明的全部可选依赖组：temporal（Temporal 持久化工作流）、anthropic/anthropic_bedrock/anthropic_vertex、openai/azure/google/bedrock/cohere（多模型提供商）、langchain/crewai（第三方框架集成）、redis（状态存储）等；--group dev则对应 pyproject.toml 的[dependency-groups] dev，包含ruff、pre-commit、pytest、pytest-asyncio、pytest-cov、boto3-stubs[bedrock-runtime]、trio等测试与质量工具。因此，make sync一次即可搭出完整的开发环境。

代码质量：make format 与 make lint 背后的 ruff 工具链

CONTRIBUTING.md 特别注明：Lint 和 Format 同时作为 pre-commit hook 运行（定义于 .pre-commit-config.yaml）。该配置仅包含一个仓库astral-sh/ruff-pre-commit（版本v0.8.4），挂载两个 hook：

• ruff（带--fix参数，自动修复）——执行 lint；
• ruff-format——执行格式化。

格式化：make format

make format

对应的 Makefile 目标为uv run scripts/format.py。查看 scripts/format.py 源码可知：它本质上只是ruff format的薄封装——通过subprocess调用ruff format（支持可选path参数限定范围），并借助typer提供 CLI 参数、用rich输出友好错误信息；若ruff未安装会给出明确提示并以退出码 1 结束。

Lint：make lint

make lint

文档强调：该命令会同时自动修复 lint 错误。依据在 scripts/lint.py 中：main(fix: bool = False, ...)在fix=True时向ruff check追加--fix参数，从而自动修复可修复的违规项；它还支持--watch（监听模式，文件变更即重新检查）和--path（指定检查路径）。

pre-commit 门禁

由于.pre-commit-config.yaml已定义上述两个 hook，在安装 pre-commit 的环境中，每次git commit都会自动执行 ruff 检查与格式化，确保进入版本库的每一行代码都符合规范。这解释了为什么 CONTRIBUTING.md 将 lint/format 列为 PR 前的第一道强制检查。

测试体系：make tests / coverage / coverage-report

make tests # 运行测试 make coverage # 带覆盖率运行 make coverage-report # 生成 HTML 覆盖率报告

三个目标在 Makefile 中的真实定义分别为：

tests: uv run pytest coverage: uv run coverage run --omit="src/mcp_agent/cli/**" -m pytest tests -m "not integration" uv run coverage xml -o coverage.xml uv run coverage report -m --fail-under=80 coverage-report: uv run coverage run --omit="src/mcp_agent/cli/**" -m pytest tests uv run coverage html

值得注意的几个实现细节：

• coverage目标运行时排除了src/mcp_agent/cli/**（CLI 子系统的代码不计入覆盖率），并通过-m "not integration"跳过 integration 标记的测试（如tests/integration/test_multithread_smoke.py），同时以 80% 为覆盖率下限（--fail-under=80，不达标即失败）；
• coverage-report则运行全部测试（含 integration）并输出 HTML 报告；
• pyproject.toml 中的[tool.pytest.ini_options]设置了pythonpath = ["."]，使 pytest 能直接导入src下的包。

仓库的测试布局（见 tests 目录）与源码结构一一对应：tests/agents/（Agent 及其并发/隔离语义）、tests/mcp/（连接管理器生命周期与并发）、tests/workflows/（orchestrator、router、swarm、parallel、evaluator_optimizer 等模式）、tests/executor/temporal/（Temporal 执行器）、tests/server/（App Server 与工具装饰器）、tests/tracing/与tests/utils/等。编写新功能测试时，可参照这些既有测试的组织方式放置到对应子目录。

Schema 生成：改动 config.py 后的必做事项

CONTRIBUTING.md 规定了一条强约束：如果修改了 src/mcp_agent/config.py，必须运行 schema 生成器，同步更新 schema/mcp-agent.config.schema.json：

make schema

对应 Makefile 的uv run scripts/gen_schema.py。这个脚本的机制值得展开——scripts/gen_schema.py 展示了 mcp-agent 如何让配置 Schema 与 Pydantic 模型保持单一事实来源：

1. load_settings_class()将src加入sys.path，并通过create_mock_modules()把opentelemetry、mcp_agent.logging、yaml等依赖模块替换为MockModule（任何属性访问都返回自身的桩对象），从而无需实例化真实依赖即可加载Settings类；
2. extract_model_info()用正则从源码中提取所有模型的类 docstring 与字段 description；
3. 调用Settings.model_json_schema()生成 Pydantic v2 的 JSON Schema，再把提取的描述递归注入$defs中的嵌套模型与根级properties；
4. 最后写入schema/mcp-agent.config.schema.json，并输出可直接粘贴到.vscode/settings.json的yaml.schemas建议。

这条链路保证了「源码字段注释 → JSON Schema → IDE 配置提示」三者一致。修改配置项却不更新 Schema，会导致下游 YAML 校验与 IDE 提示失准，因此被列为强制步骤。

LLM 辅助开发：promptify.py 与 LLMS.txt

CONTRIBUTING.md 为「让 LLM 参与开发 mcp-agent」提供了专门工具。scripts/目录下的 scripts/promptify.py 会把项目目录结构与文件内容合并为单个 Markdown 文件（prompt.md），作为 LLM 代码生成任务的上下文提示。

快速生成（默认参数）：

make prompt

其默认排除规则（见 Makefile）会剔除cli、utils、tracing、executor/temporal、core、logging、scripts、tests、.github、dist、examples/mcp*、data、*.jsonl、schema/以及CONTRIBUTING.md本身，聚焦核心业务代码。

自定义参数直接运行：

uv run scripts/promptify.py -i "**/agents/**" -i "**/context.py" -x "**/app.py"

其中-i REGEX仅包含指定文件，-x REGEX排除指定文件。从 scripts/promptify.py 源码看，它还会解析.gitignore（parse_gitignore）并将其中的模式纳入排除规则，且实现了对**/前缀模式的灵活匹配（pattern_match支持带与不带**/前缀的双重匹配），避免误伤路径。

此外，仓库根目录已存在现成的LLMS.txt文件，可直接作为提示词喂给 LLM，无需自行生成。

Examples 生态：新特性的最低交付要求

CONTRIBUTING.md 明确：Examples 用于端到端测试，并期望新功能配套 Python 单元测试；任何新特性或新的模型提供商集成（如新增 LLM 支持），至少应在 examples 目录补充示例用法。

仓库中的 examples 按类别组织（basic、mcp、usecases、cloud、temporal、tracing、workflows、model_providers等），每个示例自带 README 说明用途、架构与专属配置。通用运行模式如下：

# 1. 进入示例目录 cd examples/basic/mcp_basic_agent # 2. 安装依赖 uv pip install -r requirements.txt # 3. 配置密钥（如需要） cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml # 编辑 mcp_agent.secrets.yaml 填入你的 API keys # 4. 运行示例 uv run main.py

文档给出的两个快速上手示例：

• Basic Agent（examples/basic/mcp_basic_agent/）：一个「finder」Agent，具备 filesystem 与 fetch 能力，可回答本地文件或 URL 相关的问题，由 Agent 自主决策何时调用哪个 MCP 服务器；
• Researcher（examples/usecases/mcp_researcher/）：研究助手，具备搜索、网页抓取与 Python 解释器能力。

补充一点配置细节（来自示例 README）：密钥的提供有三种方式——mcp_agent.secrets.yaml（既有模式）、.env文件（受支持），以及MCP_APP_SETTINGS_PRELOAD环境变量（进程级安全预加载，推荐生产环境）。

编辑器配置：VS Code 开箱即用

CONTRIBUTING.md 为 VS Code 用户提供了开箱即用的编辑器配置，已实际写入仓库 .vscode/settings.json：

• editor.formatOnSave: true：保存即格式化；
• Python 文件的默认格式化器为charliermarsh.ruff（而非 Prettier），且关闭了 ruler 竖线；
• yaml.schemas将 schema/mcp-agent.config.schema.json 绑定到mcp-agent.config.yaml、mcp_agent.config.yaml、mcp-agent.secrets.yaml、mcp_agent.secrets.yaml四类文件，使配置文件获得完整补全与校验；
• .vscode/extensions.json 推荐安装esbenp.prettier-vscode与charliermarsh.ruff两个扩展。

这份配置让「改配置 → 即时校验」成为可能，也再次呼应了 Schema 生成步骤的必要性。

小结：一条可复现的贡献流水线

综合全文，mcp-agent 的贡献工作流可归纳为一条完整的流水线：

1. 准备：uv python install 3.10（如需）+make sync搭建全量开发环境；
2. 开发：创建feature/*分支，按需修改源码；改动config.py后运行make schema同步 JSON Schema；
3. 质量：make format+make lint（自动修复）通过 ruff 检查；pre-commit hook 会在提交时二次把关；
4. 验证：make tests运行全量测试；make coverage校验 80% 覆盖率下限（排除 CLI 子系统与 integration 测试）；
5. 示例与测试：新特性/新模型集成在 examples 添加示例（按类别放入对应子目录并补充 README），并尽可能在 tests 对应目录新增单元测试；
6. 提交：发起 Pull Request，大型改动提前与维护者沟通。

整个流程的核心思想是：降低贡献门槛（不要求 AI 专家），同时用自动化工具（uv、ruff、pytest、coverage、pre-commit、schema 生成）守住工程质量底线。这套「低门槛 + 强门禁」的组合，也正是 mcp-agent 能够持续吸收社区贡献的原因所在。

【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent