AI导哈

AI代理构建工具

MCP-Agents-book是一本关于使用MCP（模型上下文协议）构建AI代理的书籍，涵盖从本地原型到企业级部署的全过程，包括数据处理、分析和报告生成等功能。

  • by yanndebray
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 yanndebray/MCP-Agents-book

使用说明

MCP代理手册

使用MCP构建AI代理：从本地原型到企业部署🛠️

1.TL；博士

通过这本书，你将构建：

“一个从电子表格中读取销售数据、在MATLAB中运行高级分析并生成精美报告（Markdown→ PPT/Word/静态站点），可通过MCP工具从笔记本电脑部署到云端。”

本书涵盖：

  • 启动 代理循环 （Claude Desktop/带有工具调用的自定义OpenAI响应客户端），
  • 开发中 MCP服务器 向代理提供工具（电子表格、分析、报告），
  • 部署代理+工具 生产 （FastMCP云、MATLAB生产服务器、渲染、GitHub操作）。

2.书籍大纲

第一部分——基础：MCP和代理循环

  1. 为什么选择MCP？

    • 问题：为每个代理定制工具集成。
    • MCP被誉为“人工智能工具的USB-C”(模型上下文协议)
    • 服务器与客户端概述；JSON-RPC；工具模式。

  2. 代理与Claude和Responses循环

    • Claude Desktop作为零安装MCP客户端。 (人类)
    • 使用具有工具调用和结构化输出的OpenAI Responses构建一个最小的自定义代理。 (OpenAI平台)
    • 日志记录、重试和护栏。

  3. FastMCP底漆

    • 使用FastMCP在大约30行中构建一个“hello world”MCP服务器。 (FastMCP)
    • 为Claude和您的自定义响应客户端配置它。

第二部分-电子表格MCP

  1. 表格数据设计工具

    • 形状 product_sales 数据集；如何公开切片/过滤/搜索工具，而不是原始文件读取。
    • 工具设计模式：狭义、可组合的工具与大型功能。

  2. 使用FastMCP实现

    • Pandas+FastMCP适用于： get_sales, summarize_sales_by_year等等。
    • 验证、错误消息和模式设计。

  3. 部署到FastMCP云

    • 连接仓库，配置机密（例如，私有S3存储桶或数据库）。
    • 可观察性：JSON-RPC级别的跟踪工具调用。 (FastMCP)

第三部分——MCP分析（MATLAB）

  1. 使用MATLAB MCP核心服务器进行本地原型设计

    • 安装和配置MATLAB MCP核心服务器。 (迈斯沃克)

    • 将现有的MATLAB分析函数封装为MCP工具。

    • 使用Claude/Responses代理调用MATLAB：

      • 统计，
      • 预测，
      • 情景分析。

  2. 从桌面到服务器：MPS的MCP框架

    • 为什么MATLAB生产服务器适用于多用户、低延迟工作负载。 (迈斯沃克)
    • 通过MPS框架将MATLAB函数作为MCP工具发布。
    • 版本控制工具和处理模型和代码更新。

  3. 替代方案：将MATLAB编译为Docker/Render

    • 对于没有MPS的读者：使用编译器SDK生成运行时映像，并部署到微小MCP垫片后面的Render作为web服务。 (渲染)
    • 讨论MPS的优缺点（扩展、许可、启动时间）。

第四部分——MCP和子代理报告

  1. 设计报告MCP

  • 工具API：

    • generate_markdown_report(request_id, filters)
    • export_pptx(markdown_url | data)
    • export_static_site(markdown_url | data)

  • 编排模式：报告MCP应何时调用电子表格/分析MCP，而不是让主代理进行编排。

  1. 作为子代理进行深入研究

  • MCP使用的报告：

    • 克劳德或回应作为语境评论的“次要”代理（“深度研究”模式）。

  • 提示模式以实现一致的章节/标题输出。

  1. 格式化输出
  • Markdown+封面→ 静态网站（Hugo、MkDocs等）。
  • 使用python-pptx/python-docx生成幻灯片/报告，嵌入MATLAB工具生成的图表（保存到S3或Git LFS）。

第五部分——部署、CI/CD和操作

  1. GitHub操作管道

  • 工作流程：

    • 运行测试（Python+MATLAB），
    • 运行linting，
    • 构建文档，
    • 构建PPTX/Word工件，
    • 推送Docker镜像/触发FastMCP云部署。

  • 计划工作流以重新生成“周报”静态站点。

  1. 多环境配置
  • Dev（本地MCP核心服务器、本地FastMCP服务器）。
  • 暂存（FastMCP Cloud+MPS暂存）。
  • Prod（FastMCP Cloud+MPS Prod+渲染静态站点或GitHub页面）。
  1. 监控、安全和成本
  • FastMCP云和MPS日志的可观测性。 (完美)
  • 秘密管理（API密钥、DB信用）。
  • LLM使用的成本控制（费率限制、每份报告的预算）。
  1. 扩展架构
  • 额外的MCP服务器：CRM、票务、CFD结果等。
  • 多租户设置；组织级配置模式。
  • 如何重用模式 其他 书籍/演示。

3.书中的学习路径

每个部分都以一个“检查点”结束，阅读器在那里有：

  1. 在第一部分之后：

    • 一个正在工作的本地代理循环调用玩具FastMCP服务器。

  2. 第二部分之后：

    • 提供过滤视图的电子表格MCP product_sales.xlsx，可从克劳德和响应代理调用。

  3. 第三部分之后：

    • MATLAB分析工具可通过MCP调用，首先在本地（核心服务器）调用，然后在MPS或Render上调用。

  4. 第四部分之后：

    • 报告MCP，它从自然语言查询中生成端到端的Markdown+PPTX。

  5. 第五部分之后：

    • CI/CD管道、分阶段部署和可公开访问的生成报告静态站点。

4.技术栈

代理客户

  • 基于Claude的MCP客户端 （Claude Desktop）：通过标准MCP配置与您的三台服务器进行通信。 (人类)
  • 自定义OpenAI响应客户端：Node/Python客户端，使用Responses API+工具调用来实现相同的“代理循环”，但对计划、重试和日志记录有明确的控制。 (OpenAI平台)

服务器

  1. 电子表格MCP （快速MCP）

    • 建于 FastMCP Python框架（先本地，然后推送到FastMCP Cloud）。 (FastMCP)

    • 工具如：

      • list_dimensions()
      • get_sales(year: int, product: str | None, region: str | None)
      • summarize_by_product(year)

    • 支持Pandas阅读 product_sales.xlsx 从数据文件夹中。

  2. MCP分析

    • 本地开发人员： MATLAB MCP核心服务器，公开用于统计、预测、异常检测等的MATLAB函数。 (迈斯沃克)
    • 生产： MATLAB生产服务器的MCP框架，将MATLAB函数转换为MATLAB生产服务器上可扩展的MCP工具。 (迈斯沃克)
    • 可选变体：如果读者没有MPS，但有编译器SDK，则将Docker映像中的编译MATLAB组件作为web服务部署在Render上。 (渲染)

  3. 报告MCP

    • Python FastMCP服务器，其工具：

      • 呼叫 电子表格MCP + MCP分析.

      • 可选择调用“深度研究”子代理（Claude/Responses）进行市场评论。

      • 发射：

        • generate_markdown_report(...)
        • generate_powerpoint(...)
        • generate_word_report(...)
        • generate_static_site(...)

    • 使用python pptx/python docx/静态站点生成器作为实现细节（本书可以选择每种格式一个）。

基础设施

  • FastMCP云 用于生产中的电子表格+报表服务器（零配置、CI/CD、可观察性）。 (FastMCP)

  • MATLAB生产服务器 （本地或云端）通过MCP框架托管分析工具(迈斯沃克)

  • Render.com 用于：

    • 托管静态网站（如果不使用GitHub Pages），和/或
    • 将编译的MATLAB或辅助服务作为基于Docker的web服务托管。 (渲染)

  • GitHub 操作:

    • 对每台服务器和代理客户端运行测试。

    • 在合并/标记时，构建：

      • 来自最新Markdown的静态网站，
      • PPT/Word工件，
      • 用于Render/MPS的Docker镜像（如相关）。

5.回购结构

这是本书的回购结构：

mcp-agents-book/
  book/                     # Manuscript, notebooks, diagrams
  agents/
    claude-mcp-client/      # config files + example prompts
    responses-agent/        # Python/Node OpenAI Responses client
  servers/
    spreadsheet-fastmcp/
      server.py
      product_sales.xlsx
      tests/
    analysis-matlab-core/
      matlab/
        analyzeSales.m
        forecastDemand.m
      mcp-core-config/
      tests/
    analysis-mps-framework/
      matlab/
      mps-deploy/           # MPS MCP framework configs
    report-fastmcp/
      server.py
      templates/            # pptx/docx/html templates
      tests/
  infra/
    .github/
      workflows/
        ci.yml
        deploy-fastmcp.yml
        build-reports.yml
    render/
      Dockerfile-matlab-runtime
      render.yaml
  examples/
    01-local-loop/
    02-multi-server/
    03-deep-research/
    04-production-deploy/

每个目录都包含一章的代码起点/完成的解决方案。

相关 MCP