Hello World Tangle Blueprint 🌐

Tangle Network 的 MCP Blueprint 🌐

� 项目概述与用途

本项目是 Tangle Network 的 Blueprint，旨在运行远程 MCP（Model Context Protocol）服务。申请此 Blueprint 的新实例时，用户会获得一个包含指定配置文件的新服务实例，从而能够无缝部署和管理 MCP 服务。

Blueprint 是 Tangle Network 上 AVS 的规范。AVS 是一种链下服务，可在用户指定的时间段内运行任意计算。此 MCP Blueprint 提供了强大的抽象层，可在不同运行时环境中部署和管理 MCP 服务，让开发者能够创建可复用的 MCP 服务基础设施。

有关 Tangle Network Blueprint 的更多详情，请参阅项目文档。

⚙️ 配置详情

此 Blueprint 支持多种运行时配置，并自动管理端口。所有运行时都会在内部转换为 SSE（Server-Sent Events），以支持基于 HTTP 的通信：

支持的运行时

• JavaScript 中的 STDIO 传输（bun 运行时）：使用 bunx 执行 MCP 服务；如有需要，会自动安装 bun
• Python 中的 STDIO 传输（python3）：使用 uvx 执行 MCP 服务；如有需要，会自动安装 uv
• Docker 容器：在 Docker 容器中运行 MCP 服务，支持智能端口发现、自动分配端口和注入环境变量

端口管理与传输转换

此 Blueprint 会自动分配端口，并将所有运行时配置转换为 SSE 传输：

自动端口管理：

• 使用系统可用端口检测功能自动分配端口
• 自动向所有 MCP 服务注入 PORT 环境变量
• MCP 服务必须绑定到 PORT 环境变量指定的端口
• Blueprint 请求中无需手动配置端口

传输转换：

• 为 Web 客户端提供基于 HTTP 的通信
• 在 STDIO 和 SSE 传输之间双向转发消息
• 通过 Server-Sent Events 实时流式传输
• 提供用于提交客户端消息的 POST 端点

🔐 身份验证工作流

身份验证工作流使用脚本 generate-auth-token.ts，通过质询—响应机制生成访问令牌：

1. 质询请求：客户端向 /v1/auth/challenge 发送公钥和密钥类型
2. 质询响应：服务端返回一个设有过期时间的加密质询
3. 生成签名：客户端使用其私钥为质询签名
4. 令牌验证：客户端向 /v1/auth/verify 端点提交签名
5. 访问令牌：服务端返回一个有时限的访问令牌

访问 MCP 服务 URL 时，通过 Authorization 标头进行身份验证。令牌格式为 {token_id}|{token_string}。

📋 更新日志与重大变更

⚠️ 重大变更：近期更新引入了自动端口管理。有关详细的迁移说明和示例，请参阅 CHANGELOG.md。

主要变更：

• 从配置中移除了 portBindings 字段
• 新增自动注入 PORT 环境变量的功能
• MCP 服务现在必须从 PORT 环境变量读取端口

🚀 使用示例与演示

示例配置

fixtures 目录包含不同运行时类型的示例配置：

• fixtures/00_mcp_python3.json：Python MCP 服务配置
• fixtures/01_mcp_js.json：使用 Context7 包的 JavaScript MCP 服务
• fixtures/02_mcp_local_docker.json：使用 Redis 环境的本地 Docker MCP 服务
• fixtures/03_tangle_mcp_docker.json：Tangle 专用 Docker MCP 配置

注意：所有示例配置均使用不带 portBindings 的新格式。端口分配由 blueprint 自动处理。

本地设置

如需在本地运行设置，请按照 DEMO.md 中的详细说明操作。演示涵盖以下内容：

1. 在本地启动 Tangle 网络
2. 启动 blueprint 服务
3. 请求新的 blueprint 实例
4. 接受服务请求
5. 启动 MCP 服务
6. 生成身份验证令牌
7. 使用 MCP Inspector 进行测试

内部工作流

如需详细了解内部工作流，请参阅 mcp-blueprint-flowchart.md，其中提供了全面的流程图，展示了：

• 用户请求流程和配置处理
• 运行时检测和包管理
• 将 STDIO 传输转换为 SSE
• 服务初始化和端点提供
• 身份验证和客户端连接处理

🔄 工作流说明

blueprint 流程遵循以下高级工作流：

1. 接收请求：接收包含配置参数的远程 MCP 请求
2. 配置处理：分析运行时类型、包／镜像和环境变量
3. 端口分配：自动分配可用端口，并将其作为 PORT 环境变量注入
4. 运行时初始化：
   • Python：安装／使用 uv 进行包管理和执行
   • JavaScript：安装／使用 bun 进行包管理和执行
   • Docker：拉取镜像、检查暴露的端口，并通过智能端口绑定创建容器
5. 传输设置：将 STDIO 通信转换为 SSE，以兼容 HTTP
6. 端点公开：提供包含 /sse 和 /message 端点的 HTTP URL
7. 身份验证：通过基于令牌的身份验证系统保护访问
8. 客户端交互：支持 MCP 客户端通过 HTTP/SSE 进行连接和通信

📋 前置条件

运行此项目之前，您需要在计算机上安装以下软件：

• Rust
• Forge
• Node.js（用于运行身份验证令牌生成器）

您还需要安装 cargo-tangle，这是我们用于创建和部署 Tangle Blueprints 的命令行工具：

如需安装 Tangle CLI，请运行以下命令：

支持 Linux、MacOS 和 Windows（WSL2）

cargo install cargo-tangle --git https://github.com/tangle-network/blueprint

✨ 主要功能

自动端口管理

• 零配置：无需在配置文件中指定端口绑定
• 防止冲突：自动分配端口，避免端口冲突
• 注入环境变量：自动向 MCP 服务提供 PORT 环境变量
• 通用兼容性：适用于所有运行时类型（Python、JavaScript、Docker）
• 智能 Docker 处理：自动发现 Docker 镜像暴露的端口，并仅在需要时配置端口映射

增强安全性和可靠性

• 简化配置：通过自动端口管理缩小攻击面
• 进程生命周期管理：妥善清理进程和管理容器
• 错误处理：全面处理端口分配失败

🛠️ 开发

安装好前置条件后，即可构建和部署此项目：

cargo build

用于构建项目，以及

cargo tangle blueprint deploy

用于将蓝图部署到 Tangle 网络。

MCP 服务开发者快速参考

为此蓝图开发 MCP 服务时：

1. 从环境变量读取端口：始终使用 process.env.PORT（JS）或 os.environ['PORT']（Python）
2. 绑定到所有网络接口：使用 0.0.0.0 或 127.0.0.1 作为主机
3. 不配置端口：移除服务中的所有硬编码端口
4. 本地测试：将环境变量设为 PORT=3000 以进行本地测试

# Testing your MCP server locally
export PORT=3000
your-mcp-server-command

📜 许可证

可选择采用以下任一许可证：

• Apache License，版本 2.0 （LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）
• MIT license （LICENSE-MIT 或 http://opensource.org/licenses/MIT）

由你自行决定。

📬 反馈与贡献

欢迎提供反馈并参与贡献，帮助改进此蓝图。 请在我们的 GitHub 仓库中提交 issue 或 pull request。 如果你 fork 并扩展了此蓝图，也请告知我们！

除非你明确声明另有规定，否则你有意提交以纳入本作品的任何贡献（如 Apache-2.0 许可证中所定义）都将按照上述方式采用双重许可，且不附加任何条款或条件。