MCP Automations

MCP 自动化

一个达到生产级标准的 Python Model Context Protocol 服务——包含 4 个可由大模型调用的工具、两种传输方式，并以两种不同方式部署。

	URL
源代码	https://github.com/wzltmp/mcp-automations
演示场（浏览器演示）	https://mcp-automations-5vgea2ynuyrvbzkcxm6yoh.streamlit.app/
MCP HTTP 服务	https://mcp-automations.fly.dev/mcp

# 30-second proof the server is up:
curl -X POST https://mcp-automations.fly.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,
       "params":{"protocolVersion":"2024-11-05",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'

项目简介

大多数“AI 工程师”作品集项目都是应用（RAG 聊天机器人、执行研究任务的 Agent）。这个项目构建的是底层的一层——大模型可调用的类型化工具，以及用于公开这些工具的传输机制。MCP 正逐渐成为大模型使用工具的标准（截至 2026 年初，SDK 月下载量约为 9,700 万次）；开发 MCP 服务，而不只是使用 MCP 服务，是一项稀缺技能。

如需深入了解设计决策——为什么采用两种传输方式、成本遥测如何运作、异常层级设计，以及我会如何改进——请参阅 WRITEUP.md。

工具

工具	模型	功能
summarize_url(url, n_bullets)	Haiku 4.5	获取网页，使用 trafilatura 提取干净文本，并返回含 N 个要点的摘要
repurpose_content(text, format)	Sonnet 4.6	将长篇文本改写为 Twitter 串文、LinkedIn 帖子或新闻简报
daily_digest(topic, n_results)	Haiku 4.5	使用 Tavily 搜索新闻，并生成附带引文的约 200 字摘要
find_competitors(domain, n)	Sonnet 4.6	根据公司域名识别 N 家可能的竞争对手

此外还有一个 MCP 资源（automations://catalog）和一个 MCP 提示词（daily_brief）——使用 MCP 的全部三种原语，而不只是工具。

每个工具都会返回一个类型化的 Pydantic 模型，其中附有每次调用的 Token 用量和美元成本。低成本任务使用 Haiku 4.5（输入每百万 Token 1 美元，输出每百万 Token 5 美元），写作密集型任务使用 Sonnet 4.6（输入每百万 Token 3 美元，输出每百万 Token 15 美元）。

将 Claude Desktop 连接到此服务

将以下配置之一添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%/Claude/claude_desktop_config.json（Windows），然后重启 Claude Desktop。

选项 A — 本地 stdio（无需网络，以子进程方式运行服务）：

{
  "mcpServers": {
    "mcp-automations": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/mcp-automations",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "TAVILY_API_KEY": "tvly-..."
      }
    }
  }
}

选项 B — 远程 HTTP（连接正在运行的 Fly 服务，无需本地配置）：

{
  "mcpServers": {
    "mcp-automations": {
      "url": "https://mcp-automations.fly.dev/mcp",
      "transport": "http"
    }
  }
}

然后可以向 Claude 提出类似 “用 3 个要点总结 https://www.paulgraham.com/greatwork.html” 的请求——它会自动调用 summarize_url。

本地运行

pip install -r requirements.txt

# Stdio (for Claude Desktop):
python -m mcp_server.server

# HTTP server (defaults to 0.0.0.0:8765):
MCP_TRANSPORT=http python -m mcp_server.server

# Streamlit playground:
streamlit run playground/app.py

需要 Python 3.13。需要在 .env 中设置 ANTHROPIC_API_KEY 和 TAVILY_API_KEY（参见 .env.example）。

架构

┌────────────────┐     stdio      ┌──────────────────────┐
│ Claude Desktop ├───────────────►│                      │
└────────────────┘                │                      │
                                  │   mcp_server/        │
┌────────────────┐    HTTP/JSON   │   server.py          │
│ Remote client  ├───────────────►│   (FastMCP)          │
└────────────────┘   (Fly.io)     │                      │
                                  │   4 tools            │
┌────────────────┐  direct call   │   1 resource         │
│ Streamlit UI   ├───────────────►│   1 prompt           │
└────────────────┘                └──────────┬───────────┘
                                             │
                                  ┌──────────┴───────────┐
                                  │ Anthropic + Tavily   │
                                  │ (lazy clients)       │
                                  └──────────────────────┘

三个入口共用同一组 Python 可调用对象。传输方式只是一个包装层。

仓库内容

mcp-automations/
├── mcp_server/
│   ├── server.py        # FastMCP server: 4 tools + 1 resource + 1 prompt
│   ├── models.py        # Pydantic I/O schemas (incl. per-call Cost telemetry)
│   └── exceptions.py    # MCPToolError + UpstreamAPIError / EmptyLLMResponseError / ExtractionError
├── playground/
│   └── app.py           # Streamlit UI with per-session call + spend caps
├── tests/               # offline unit tests (httpx/anthropic/tavily all mocked)
├── Dockerfile           # python:3.13-slim, MCP_TRANSPORT=http for Fly
├── fly.toml             # shared-cpu-1x, 256mb, auto-stop when idle
└── .github/workflows/   # ruff + strict mypy + pytest on every push

值得一提的生产级特性

• 每个工具响应都包含成本遥测（models.Cost）——附带 Token 数量和美元成本，客户端无需自行重新计算。
• 基于成本的模型路由——低成本任务使用 Haiku，写作任务使用 Sonnet。
• 领域专用异常层级——UpstreamAPIError、EmptyLLMResponseError、ExtractionError 在日志和 Streamlit UI 中分别处理。
• 两种传输方式，共用一套代码——通过 MCP_TRANSPORT=stdio|http 环境变量切换；HTTP 主机和端口从环境变量读取，因此同一镜像可在 Fly 上运行。
• 演示场的会话级滥用限制——每个会话最多调用 20 次 / 花费 0.50 美元；Anthropic 控制台另设每月 2 美元的硬性上限。
• CI 中严格执行 mypy、ruff 和 pytest，每次推送都会运行（.github/workflows/ci.yml）。

为什么选择 MCP

MCP 与传输协议无关，因此同一服务既能为本地 Claude Desktop 用户提供服务（stdio 子进程），也能用于托管的多租户部署（HTTPS）。它还提供了大多数演示都会跳过的三种原语：

• 工具 — 模型决定调用的函数（这里有 4 个）
• 资源 — 客户端可通过 URI 获取的只读数据（automations://catalog 会以 JSON 格式返回工具列表）
• 提示词 — 用户主动调用的服务端模板（daily_brief 会串联 daily_digest 和 repurpose_content）

使用这三种原语，表明你读过规范，而不只是照着快速入门操作。

状态

✅ 代码已发布到 GitHub，CI 正常 ✅ Streamlit Cloud 上的公开体验环境 ✅ Fly.io 上的公开 MCP HTTP 服务 ✅ 成本保护（每个会话的上限 + Anthropic 月度上限） ✅ 实际测试覆盖（23 个离线单元测试） ✅ 已收录于官方 MCP Registry，标识符为 io.github.wzltmp/mcp-automations ✅ 设计决策详述 ✅ 已被另一个 Agent 实际调用，而非仅用于演示 — langgraph-research-agent 的 read_node 会通过 HTTP 调用此服务的 summarize_url 工具（如果调用失败，则使用本地回退方案） 🚧 演示 gif + 截图（计划中） 🚧 通过 docker-compose 自托管 n8n（计划中）

许可证

MIT。