AI导哈

文档生成与分析工具栈

MCP Lab提供基于Docker的多功能文档生成与分析工具栈，支持Excel、Word、PDF文件创建、数据分析及任务管理，适用于自动化办公和数据处理场景。

  • by davidlarrimore
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 davidlarrimore/mcp-playground

使用说明

MCP实验室-Docker化演示栈

该仓库提供了一个完整的MCP（模型上下文协议）演示栈，其中包含在Docker上运行的7个专业服务。它包括核心实用程序（时间、文件系统、内存、电子邮件）以及统一的文档生成器（Excel、Word、PDF）和分析/演示工具。

✨ 新 在一个MCP端点中提供涵盖Excel工作簿、Word报告和PDF创建的统一文档服务，以及PowerPoint演示文稿和带图表生成的数据分析。所有生成的文档都包含签名的下载URL，便于共享。

特性

核心服务（5）：

  • ⏰ 时间和时区操作
  • 📁 文件系统操作（读/写/管理文件）
  • 🧠 持久内存存储
  • 📧 通过MailHog发送带有附件的电子邮件
  • ✅ 使用SQLite支持的存储进行任务管理

文档生成（3）：

  • 📄 文档MCP-在一个服务中创建Excel工作簿、Word报告或HTML到PDF
  • 📊 PowerPoint-使用幻灯片、表格和图像创建演示文稿
  • 📈 分析-合并数据、计算统计数据、创建图表
  • 🔗 签名下载-所有生成文件的安全、有时间限制的下载URL

集成：

  • 🔌 用于统一访问的MCPO OpenAPI代理
  • 🐳 完整的Docker编写设置
  • 🌐 开放式WebUI兼容（MCP流式HTTP）
  • 📂 跨所有服务共享工作区

里面是什么

  • 主机端口上的MailHog（SMTP接收器+web UI） 2005 （UI）/ 2025 （SMTP）
  • 参考MCP服务器（容器名称）： time-mcp, filesystem-mcp, memory-mcp
  • 自定义电子邮件HTTP服务： email-mcp （职位 /send)
  • 任务管理服务: task-mcp -具有CRUD操作的SQLite支持的任务注册表
  • 文档生成服务: document-mcp, analytics-mcp
  • 封装所有MCP服务器的MCPO OpenAPI代理
  • FastMCP 2.0为自定义MCP接口供电（桥接到流式HTTP）
  • 共享Docker网络： mcp-net
  • 附件和文件系统文件的共享数据装载： ./docs

快速入门

  1. 复制环境默认值，并根据需要调整端口/路径：
cp .env.example .env
  1. 构建并启动堆栈（桥接stdio→HTTP映像是在本地构建的）：
make up
  1. 尾梁：
make logs

  1. 访问MailHog用户界面： http://localhost:2005

  2. 停止一切：

make down
  1. 完全拆卸（容器+体积）：
make nuke

服务端点（开发配置文件）

  • 时间MCP： http://localhost:${TIME_MCP_PORT:-2001}
  • 文件系统MCP： http://localhost:${FILESYSTEM_MCP_PORT:-2002}
  • 内存MCP： http://localhost:${MEMORY_MCP_PORT:-2003}
  • 电子邮件MCP： http://localhost:${EMAIL_MCP_PORT:-2004}
  • MailHog用户界面： http://localhost:${MAILHOG_WEB_PORT:-2005}
  • 文件MCP: http://localhost:${DOCUMENT_MCP_PORT:-2006}
  • 任务MCP: http://localhost:${TASK_MCP_PORT:-2007}
  • 分析MCP: http://localhost:${ANALYTICS_MCP_PORT:-2009}
  • Python SDK MCP: http://localhost:${PYTHON_SDK_MCP_PORT:-2011}
  • MCPO OpenAPI代理： http://localhost:${MCPO_PORT:-2010}
  • 下载服务: http://localhost:${DOWNLOAD_SERVICE_PORT:-8080}

参考MCP映像作为stdio服务器提供。Compose构建轻量级包装器（时间桥、文件系统桥、内存桥），使用 supergateway 以公开可流式传输的HTTP端点。

自定义电子邮件服务（现在支持MCP）

  • 基于FastMCP 2.0（stdio工具通过桥接到可流式HTTP supergateway 在 /mcp)
  • 集装箱： email-mcp
  • MCP端点： http://localhost:${EMAIL_MCP_PORT:-2004}/mcp （通过超级网关流式传输HTTP）
  • HTTP便利API（不变）： POST /send
  • 健康： GET /healthz
  • 环境： SMTP_HOST, SMTP_PORT, SMTP_FROM_DEFAULT, ATTACH_ROOT, LOG_LEVEL
  • 体积：装载 ./docs 只读 /attachments 因此，您可以附加场景文件。
  • 附件：使用传递对象 path （相对于 /attachments)；普通字符串也有效，但必须在以下情况下解决 /attachments 否则你会得到400分。示例 {"path": "bp_crossings_central.xlsx"}.

请求示例：

curl -X POST http://localhost:2004/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["ops@example.com"],
    "subject": "Week 8 invite",
    "body_text": "See you Thursday at noon ET.",
    "attachments": [{"path": "CourseOutlineWeek8.pdf", "filename": "Week8Outline.pdf"}]
  }'

文档生成服务

两个MCP服务提供专业的文档创建和数据分析功能。所有服务共享 ./docs 工作空间，基于FastMCP 2.0构建。

文件MCP(document-mcp)

  • 集装箱： document-mcp
  • 端口： ${DOCUMENT_MCP_PORT:-2006}
  • MCP端点： http://localhost:2006/mcp
  • 健康： GET /healthz
  • 工具：
    • save_uploaded_file -将上传的文件保存到工作区（base64）
    • create_excel_workbook -使用格式化的工作表、图表（条形图/折线图）和自动调整大小创建Excel文件
    • create_word_report -创建包含标题、章节、表格、项目符号和格式的Word文档
    • create_pdf_from_html -使用可选的CSS样式将HTML（字符串或文件）转换为PDF

分析MCP(analytics-mcp)

  • 集装箱： analytics-mcp
  • 端口： ${ANALYTICS_MCP_PORT:-2009}
  • MCP端点： http://localhost:2009/mcp
  • 健康： GET /healthz
  • 工具：
    • save_uploaded_file -将上传的文件保存到工作区（base64）
    • list_data_files -列出具有可选全局模式的可用CSV/Excel文件
    • merge_excel_files -将多个CSV/Excel文件合并到一个数据集中
    • calculate_summary_stats -使用可选分组计算统计数据
    • generate_chart -从数据创建条形图、折线图或饼图
    • create_presentation -使用幻灯片、要点、表格和图像创建PowerPoint演示文稿

Python SDK演示MCP(python-sdk-mcp)

  • 集装箱： python-sdk-mcp
  • 端口： ${PYTHON_SDK_MCP_PORT:-2011}
  • MCP端点： http://localhost:2011/mcp
  • 健康： GET /healthz
  • 与官方合作建造 mcp Python SDK（Streamable HTTP），无需网关即可展示本机资源、工具和提示。
  • 工具/资源：
    • list_workspace_files -使用可选递归和隐藏文件对共享工作区进行全局搜索
    • read_text_file -带截断和可选签名下载URL的安全文本阅读器
    • create_note -用简单的封面写下标记笔记 /workspace/notes
    • 资源 workspace://index -最近文件的快速索引
    • 提示 summarize_file_prompt -推动模型调用的模板 read_text_file 第一

下载服务

所有文档生成服务都会自动为生成的文件创建签名的下载URL。这些网址：

  • 安全（HMAC-SHA256签名）
  • 24小时后过期（可配置）
  • 可以在浏览器/脚本中共享或直接使用

文档生成的示例响应：

{
  "path": "report.pdf",
  "absolute_path": "/workspace/report.pdf",
  "size": 12345,
  "download_url": "http://localhost:8080/download?file=...&signature=...",
  "download_expires_at": 1234567890,
  "download_expires_in": 86400
}

看 docs/SIGNED_DONLOADS.md 获取完整的技术文档 文档/下载_URLS_USAGE.md 有关Open WebUI集成示例。

共享工作区

  • 所有文档服务装载 ./docs 作为他们的工作空间 /workspace
  • 由一个服务创建的文件可供所有其他服务立即访问
  • 重要提示： 在工具调用中使用文件路径时，不要包括 docs/ 前缀（例如，use "report.xlsx" 不 "docs/report.xlsx")

任务管理服务

任务MCP(task-mcp)

  • 集装箱： task-mcp
  • 端口： ${TASK_MCP_PORT:-2007}
  • MCP端点： http://localhost:2007/mcp
  • 健康： GET /healthz
  • 数据库：SQLite存储在持久卷中 task-data
  • 工具：
    • task_create -使用标题、描述、优先级、元数据和project_id创建新任务
    • task_get -按ID获取单个任务
    • task_list -列出带有筛选（状态、项目id）和排序的任务
    • task_update -更新任务字段（状态、优先级、描述等）
    • task_delete -永久删除任务
    • task_pop_next -获取最高优先级的待处理任务并标记为in_process
    • task_stats -获取任务统计信息（按状态计数）

任务架构：

  • id -自动递增整数（主键）
  • title -任务标题（必填）
  • description -可选任务描述
  • status -任务状态： pending, in_progress, done, cancelled
  • priority -整数优先级（较高=更重要，默认为0）
  • metadata -自定义字段、标签等的可选JSON元数据。
  • project_id -可选项目/组标识符
  • created_at, updated_at -ISO时间戳

示例用法：

// Create a task
task_create({
  "title": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "priority": 10,
  "metadata": {"tags": ["security", "backend"], "estimated_hours": 8},
  "project_id": "api-v2"
})

// List high-priority pending tasks
task_list({"status": "pending", "order_by_priority": true, "limit": 5})

// Update task status
task_update({"task_id": 5, "status": "in_progress"})

// Pop next task for processing
task_pop_next({"project_id": "api-v2"})

处理上传的文件

当用户通过Open WebUI聊天上传文件时，请使用 save_uploaded_file 工具（在所有4个服务中都可用）将它们保存到工作区：

{
  "filename": "data.xlsx",
  "content_base64": "<base64-encoded file content>"
}

看 docs/QUICK_START.md 和 docs/MCP_USAGE_GUIDE.md 查看详细的使用示例。

本地（venv）电子邮件服务

在没有Docker的情况下运行电子邮件服务（使用 .env 如果存在）。FastMCP 2.x需要Python>=3.10；集 PYTHON_BIN 如果你需要指向特定的口译员：

make email-local

这创造了 .venv，安装 email-mcp/requirements.txt，并运行 python -m email_mcp.server。请停止：

make email-local-stop

文件系统+附件

  • 将文件放在下面 docs/.文件可在容器内找到，网址为 ${FILESYSTEM_ROOT} （默认值 /docs)以及电子邮件服务 ${ATTACH_ROOT} （默认值 /attachments).
  • 文件系统MCP现在使用上游 @cyanheads/filesystem-mcp-server 包裹着 supergateway，仅限于 ${FILESYSTEM_ROOT} 以避免逃逸主机目录。
  • 核心工具（有关完整模式，请参阅上游文档）： list_files, read_file, write_file, update_file, delete_file, delete_directory, create_directory, move_path, copy_path，加 set_filesystem_default 用于会话相对路径。 write_file 覆盖或创建根目录下的文本文件；与...结合 copy_path 如果你需要复制现有的二进制文件。
  • 容器将默认文件系统路径初始化为 ${FILESYSTEM_ROOT}，因此相对路径可以通过MCPO/Open WebUI开箱即用。

制定目标

  • make up –启动所有服务
  • make down –停止服务
  • make logs –跟踪容器日志
  • make ps –查看容器状态
  • make rebuild –重建图像（拉取基础层）
  • make nuke –删除容器和卷（清除内存数据）
  • make email-local –在本地venv中运行电子邮件服务
  • make email-local-stop –停止本地电子邮件进程

MCPO OpenAPI代理（封装所有MCP服务器）

  • 集装箱： mcpo
  • 基本URL: http://localhost:${MCPO_PORT:-2010}
  • 路线（每个工具）： /time, /filesystem, /memory, /email, /document, /analytics, /python-sdk 生成的OpenAPI文档位于 /<tool>/docs （例如。， http://localhost:2010/analytics/docs)和模式 /<tool>/openapi.json.
  • 连接方式：代理同一Docker网络上所有MCP服务的Streamable HTTP端点。
  • 通过MCPO可访问的所有MCP服务：
    • 核心服务： time-mcp, filesystem-mcp, memory-mcp, email-mcp, task-mcp
    • 文档+数据服务： document-mcp, analytics-mcp, python-sdk-mcp
  • 打开WebUI集成：添加 开放应用程序接口 服务器指向 http://localhost:2010/<tool>/openapi.json （或 http://mcpo:8000/<tool>/openapi.json 如果Open WebUI在上运行 mcp-net).如果您想要单独的OpenAPI服务器，请按每个工具重复，或者使用MCP Streamable HTTP类型一次性添加所有服务器。

Open WebUI布线注意事项

  • Docker网络被命名为 mcp-net （在中明确设置 docker-compose.yml).
  • 确保Open WebUI加入 mcp-net 或者可以到达 localhost 在映射的端口上。
  • 如果Open WebUI在单独的Compose项目中运行，请将其连接到 mcp-net 在该网络存在之后：
    • docker network create mcp-net （仅限第一次）
    • docker network connect mcp-net <openwebui_container>
  • 在Open WebUI中添加指向上述主机名/端口的工具服务器。

打开WebUI设置

  • 网络：（a）在主机上运行Open WebUI并使用上面的localhost端口，或（b）将其容器连接到 mcp-net 因此，它可以解析服务名称。例子： docker network connect mcp-net <openwebui_container>.
  • 在Open WebUI中→ 设置→ 工具（外部工具）→ 添加工具服务器：
    • 类型： MCP (Streamable HTTP)
    • 选项1-个人服务 （名称/URL对）：
      • time → http://time-mcp:8000/mcp （或 http://host.docker.internal:2001/mcp)
      • filesystem → http://filesystem-mcp:8000/mcp （或 http://host.docker.internal:2002/mcp)
      • memory → http://memory-mcp:8000/mcp （或 http://host.docker.internal:2003/mcp)
      • email → http://email-mcp:8000/mcp （或 http://host.docker.internal:2004/mcp)
      • document → http://document-mcp:8000/mcp （或 http://host.docker.internal:2006/mcp)
      • task → http://task-mcp:8000/mcp （或 http://host.docker.internal:2007/mcp)
      • analytics → http://analytics-mcp:8000/mcp （或 http://host.docker.internal:2009/mcp)
      • python-sdk → http://python-sdk-mcp:8000/mcp （或 http://host.docker.internal:2011/mcp)
    • 选项2-通过MCPO（推荐）:
      • 单个URL: http://mcpo:8000/mcp （或 http://host.docker.internal:2010/mcp)
      • 这将通过一个端点公开所有服务
  • 点击每个的“测试连接”；您应该看到返回的工具列表。
  • 要使用OpenAPI代理，请添加指向以下位置的OpenAPI服务器 http://localhost:2010/<tool>/openapi.json （或 http://mcpo:8000/<tool>/openapi.json 上 mcp-net)，在哪里 <tool> 是 time, filesystem, memory, email, excel, word, pdf，或 analytics.

打开WebUI连接字段（每个工具）

  • 类型： MCP Streamable HTTP
  • 网址：
    • 如果主机上有Open WebUI： http://localhost:<port>/mcp (2001/2002/2003/2004)
    • 如果Open WebUI在Docker中，但 不 上 mcp-net: http://host.docker.internal:<port>/mcp
    • 如果打开WebUI mcp-net: http://time-mcp:8000/mcp, http://filesystem-mcp:8000/mcp, http://memory-mcp:8000/mcp, http://email-mcp:8000/mcp
  • 认证：无（留空）
  • 标题：留空
  • ID：可选（将生成Open WebUI）
  • 姓名：您喜欢的任何简称（例如。， time, filesystem, memory, email)
  • 说明：可选
  • 函数名称筛选器列表：除非需要隐藏函数，否则请留空

快速验证检查

运行这些之后 make up:

  • 健康端点（所有服务）：
    # Core services
curl http://localhost:2001/healthz  # time
curl http://localhost:2002/healthz  # filesystem
curl http://localhost:2003/healthz  # memory
curl http://localhost:2004/healthz  # email

# Document generation services
curl http://localhost:2006/healthz  # document
curl http://localhost:2007/healthz  # task
curl http://localhost:2009/healthz  # analytics

# Python SDK demo
curl http://localhost:2011/healthz  # python-sdk-mcp
    每个人都应该返回： ok （python sdk-mcp返回JSON {"status":"ok"})
  • MCPO OpenAPI文档（验证所有服务）：
    curl -I http://localhost:2010/time/docs
curl -I http://localhost:2010/analytics/docs
curl -I http://localhost:2010/document/docs
    每个都应该返回HTTP 200
  • 文件系统容器看到演示数据：
    docker compose --env-file .env exec filesystem-mcp ls /docs
  • 已挂载内存持久路径：
    docker compose --env-file .env exec memory-mcp ls /data
  • 电子邮件发送路径（点击MailHog）：
    curl -X POST http://localhost:2004/send \
  -H "Content-Type: application/json" \
  -d '{"to":["ops@example.com"],"subject":"Ping","body_text":"hello"}'
    然后打开MailHog UI(http://localhost:2005)并确认消息出现。

通过MCPO/OpenAPI发送电子邮件

发送HTML电子邮件：

  • 使用 body_html HTML电子邮件的有效HTML标记字段
  • 使用 body_text 纯文本电子邮件字段
  • 不要将HTML标记放入 body_text -使用 body_html 仅用于HTML内容
  • 至少一个 body_text 或 body_html 必须提供

HTML电子邮件示例：

{
  "to": ["user@example.com"],
  "subject": "Border Patrol Monthly Report - March 2024",
  "body_html": "<html><body><h1>Monthly Report</h1><p>See attached files for detailed analysis.</p></body></html>",
  "attachments": [
    {"path": "bp_crossings_central.xlsx"},
    {"path": "bp_crossings_east.xlsx"}
  ]
}

附件要求：

  • 这 /email/send 路由期望附件作为对象 path （可选 filename)
  • 路径必须位于 /attachments 容器内部（映射自 ./docs 默认情况下）
  • 只有当绝对路径位于该根下时，它们才会被归一化；其他任何东西都会以400的速度失败

调试提示

  • 检查服务日志： docker compose --env-file .env logs <service> -f
  • 验证来自电子邮件容器的MailHog SMTP连接：
    docker compose --env-file .env exec email-mcp nc -z mailhog 1025
  • 验证附加路径：容器应在以下位置看到文件 ${ATTACH_ROOT}；使用 docker compose exec email-mcp ls /attachments.

相关 MCP