1. 基于 Claude Code 的 vibe coding 开发实践#

今天的代码开发主要采用 Claude Code 辅助完成。我不是简单让 AI 一次性生成完整模块，而是按照敏捷开发的方式，将 MCP Client Gateway 拆成多个可验证的小阶段逐步推进。

整体开发过程大致包括：

• 先明确当前阶段只做 MCP Client Gateway，不做完整 Agent Planner、不做 MCP Server、不做复杂多轮编排；
• 将模块拆分为 Server 配置管理、Client 生命周期管理、工具发现、工具调用、策略校验、参数校验、审计日志、健康检查等子任务；
• 每完成一个小模块后进行局部检查和接口验证；
• 在功能链路基本跑通后，整理技术文档、接口文档、测试方案和测试报告；
• 最后通过集成测试验证当前 MVP 链路是否可用。

这种 vibe coding 开发模式提升了今天的开发效率，也让我更清楚地体会到：AI coding 并不是让模型替代开发者直接完成所有代码，而是由我负责把控任务边界、模块拆分、架构取舍和验证标准，AI 负责辅助生成代码、补全结构和加速实现。

2. MCP Client Gateway 模块开发#

今天的主要开发内容是 MCP Client Gateway。该模块在智能体管理平台中的定位是“工具接入底座”，用于在完整 Agent 模块尚未搭建完成之前，先独立完成 MCP Client 的连接管理和工具调用能力。

当前阶段模块重点能力包括：

• MCP Server 连接配置管理；
• MCP Client 初始化与生命周期管理；
• 外部 MCP Server 工具列表发现；
• 工具元数据同步和本地缓存；
• 工具调用统一入口；
• 调用前参数 Schema 校验；
• 工具调用策略检查；
• 调用审计日志记录；
• Gateway 整体健康检查；
• 为后续 Agent Planner、Skill Router、Plan-and-Execute 模块预留标准调用接口。

从平台架构角度看，MCP Client Gateway 并不是完整 Agent 的替代品，而是 Agent 调用外部工具之前的一层标准化网关。后续 Agent 模块可以通过 Gateway 暴露的 REST API 调用工具，不需要直接依赖 MCP SDK，也不需要在每个 Agent 内部重复实现工具连接逻辑。

3. 技术方案与架构沉淀#

今天在开发完成后，对 MCP Client Gateway 的整体技术方案进行了文档沉淀。技术文档中明确了模块背景、建设目标、范围边界、技术选型、分层架构、核心流程、数据库设计、REST API 设计、异常处理、可观测性和后续 Agent 接入约定。

当前方案采用 Java 21、Spring Boot 3.3.5、Spring MVC、MCP Java SDK 0.9.0、MyBatis Plus、MySQL/H2、NetworkNT JSON Schema Validator 等技术组合。模块结构按照 controller、application、domain、infrastructure、dto、common 等层次拆分，使代码职责更加清晰。

今天也进一步明确了当前阶段的边界：本阶段重点是完成 MCP Client Gateway，不做完整 Agent Planner，不做 LLM 自动工具选择，不自研 MCP Server，不实现复杂多轮任务编排。这种边界控制可以避免前期开发范围过大，也能让当前模块更聚焦于工具接入和调用治理。

4. 接口设计与文档沉淀#

今天整理了 MCP Client Gateway 的接口文档，围绕 /api/mcp 基础路径设计了多类 REST API。

接口主要包括：

• MCP Server 管理接口：Server 列表查询、新增配置、更新配置、删除配置、启用/禁用；
• 连接测试接口：触发 MCP Client 连接和 initialize 握手；
• 工具发现接口：查询工具列表、查询工具详情、同步指定 Server 工具、同步全部工具；
• 工具调用接口：支持按 toolId 调用，也支持按 serverCode + toolName 调用；
• 健康检查接口：查询 Gateway 整体状态和单个 Server 健康状态；
• 调用日志接口：查询工具调用审计日志。

其中，按 serverCode + toolName 调用工具的接口被设计为后续 Agent 推荐使用方式。这样 Agent 在执行计划步骤时，不需要先感知数据库中的 toolId，而是可以根据工具名称和 Server 编码直接调用 Gateway 统一入口。

接口文档中也统一了响应格式和错误码，包括 Client 未连接、连接失败、工具不存在、工具被策略拒绝、参数不符合 JSON Schema、调用超时等异常场景，为后续前后端联调和问题排查提供了基础。

5. 数据库与调用审计能力设计#

今天梳理并沉淀了 MCP Client Gateway 所需的数据库表结构，主要包括：

• mcp_server_config：维护 MCP Server 连接配置；
• mcp_tool_definition：存储工具元数据、输入 Schema、风险等级等信息；
• mcp_tool_call_log：记录每次工具调用的 traceId、入参、出参、耗时、状态和异常信息；
• mcp_tool_policy：维护工具调用策略，包括允许、拒绝和审批等状态。

其中，调用审计日志是本模块的重要能力。它可以帮助后续追踪工具调用链路、定位异常问题，并为平台的工具治理、安全控制和后续运维分析提供基础数据。

6. 集成测试与本地验证#

今天完成了 MCP Client Gateway 的测试方案和测试报告整理，并进行了本地集成测试验证。测试采用 JUnit 5、Spring Boot Test、MockMvc、H2 内存数据库和 STDIO 子进程 MCP Server。

本次集成测试覆盖 7 个步骤：

1. 注册 STDIO MCP Server；
2. 测试连接并完成 MCP initialize 握手；
3. 同步工具列表；
4. 查询工具列表；
5. 调用 echo 工具；
6. 调用 add 工具；
7. 执行 Gateway 健康检查。

测试结果显示 7 个步骤全部通过，说明当前 MCP Client Gateway 的最小可用链路已经完成本地验证。测试覆盖了 REST API、应用服务层、MCP SDK 适配层、连接注册表、JSON Schema 校验、审计日志和自动建表等关键组件。

需要说明的是，本次测试主要验证 STDIO transport 链路。HTTP/SSE transport 已在技术方案中预留，但仍需要在真实网络环境下继续联调验证。

7. AI coding 上下文治理方法沉淀#

除了具体代码开发外，今天我还结合 Claude Code 的实际使用过程，总结了一套 Claude / Agent 上下文治理方法论。

这套方法的核心理解是：上下文治理不是简单压缩聊天记录，而是要把 Agent 工作所需的信息按照生命周期、重要性和使用频率进行分层管理。真正有效的 Agent 不是“什么都记住”，而是“只把当前决策必须依赖的信息放进主上下文”。

我整理的方法中，将上下文拆分为五层：

• L1 长期规则层：技术栈、代码规范、架构约束、禁止事项，可放入 CLAUDE.md 或 AGENTS.md；
• L2 任务边界层：本轮要做什么、不做什么、完成标准，可放入 docs/ai/current-task.md；
• L3 状态进度层：已完成、未完成、下一步，可放入 docs/ai/progress.md；
• L4 决策记录层：关键架构决策及原因，可放入 docs/ai/decisions.md；
• L5 交接压缩层：跨窗口或 compact 后继续工作的摘要，可放入 docs/ai/handoff-summary.md。

这套方法对今天的 MCP Client Gateway 开发也有直接启发。由于当前模块涉及多个文件、多层架构、接口设计和测试验证，如果不控制上下文，AI coding 很容易出现任务范围扩大、重复读取无关文件、把旧方案当成当前约束等问题。因此，在后续使用 Claude Code 或其他 Agent 工具进行开发时，需要通过 current-task、progress、decisions、handoff 等文件主动管理上下文。

8. 对企业 Agent 平台的启发#

今天整理上下文治理方案时，我也进一步联想到我们正在做的智能体管理平台。对于企业级 Agent 装配工厂来说，上下文治理不能只靠提示词临时约束，而应该成为平台能力的一部分。

后续平台可以考虑：

• 为每个 Agent 维护 Agent Context Registry，记录长期规则、当前任务、已加载 Skill、工具调用摘要、历史摘要和上下文预算；
• 对 Skill 采用分层加载机制，先加载 Skill Card，再按需加载 Manifest 和 Body；
• 区分 Profile Memory、Project Memory、Task Memory、Decision Memory、Tool Memory、Error Memory 等不同记忆类型；
• 对工具调用结果进行摘要化保存，避免大段日志和完整返回结果长期污染主上下文；
• 在任务切换、模块完成、测试通过、bug 修复、subagent 返回后触发自动压缩或交接摘要更新。

这部分沉淀不仅可以帮助我更高效地使用 Claude Code，也可以为后续设计企业内部 Agent 调度基座提供参考。

1. Agent 模块尚未完成，MCP 能力需要先行建设#

• 问题：当前智能体管理平台中的完整 Agent 模块尚未搭建，但项目需要先具备 MCP Client 的部署和工具接入能力。
• 处理：将 MCP Client 抽象为独立的 MCP Client Gateway，不依赖完整 Agent 推理流程，先完成工具连接、发现、调用和审计能力。
• 结果：形成了一个可独立运行、可本地验证、可供后续 Agent 调用的工具接入底座。

2. vibe coding 需要避免任务范围发散#

• 问题：使用 Claude Code 进行 AI coding 时，如果任务边界不清晰，模型容易把 MCP Client Gateway 扩展成完整 Agent、Skill 装配或 MCP Server 开发。
• 处理：在开发过程中明确当前阶段只做 MCP Client Gateway，并通过文档记录“不做事项”和模块边界。
• 结果：开发过程更聚焦，避免了过早引入 Agent Planner、LLM 自动工具选择和复杂任务编排。

3. MCP 工具调用需要统一治理#

• 问题：如果后续 Agent 或业务模块直接调用 MCP SDK，容易造成工具调用分散、权限控制不统一、审计日志缺失等问题。
• 处理：设计 Gateway 统一 REST API，由 McpToolInvokeService 统一完成策略检查、参数校验、工具调用和审计落库。
• 结果：后续 Agent 可以通过统一接口调用工具，工具权限、参数校验和调用日志都可以在 Gateway 层集中处理。

4. 传输方式验证范围有限#

• 问题：当前集成测试主要验证了 STDIO transport，HTTP/SSE transport 仍需要在真实网络环境下进一步验证。
• 处理：在技术文档和测试方案中明确当前验证范围，将 HTTP/SSE 联调作为后续版本计划。
• 结果：当前版本先保证 STDIO 最小链路稳定可用，同时为后续远程 MCP Server 接入预留扩展空间。

5. 大项目 AI coding 存在上下文污染风险#

• 问题：在长任务开发中，Claude Code 会持续加载对话历史、文件内容、命令输出、工具信息和阶段性尝试，容易导致上下文窗口变大、模型注意力被稀释、旧信息干扰当前任务。
• 处理：总结上下文治理方法，将长期规则、当前任务、阶段进度、架构决策和交接摘要分别放入不同文档，并使用 /clear、/compact、/context、subagent、slash command、skill 等机制控制上下文。
• 结果：形成了一套可复用的 AI coding 上下文管理方案，可用于后续 MCP Gateway、Agent 调度基座以及其他长任务开发场景。