node-wire

<!-- SPDX-FileCopyrightText: 2026 AOT Technologies SPDX-License-Identifier: Apache-2.0 --> # 节点连接线 [](https://github.com/AOT-Technologies/node-wire/actions/workflows/pytest.yml) [](https://github.com/AOT-Technologies/node-wire/actions/workflows/codeql.yml) [](https://pypi.org/project/node-wire/) [](https://pypi.org/project/node-wire/) [](LICENSE) 节点连接线（Node Wire）是一个三层结构的Python平台，用于运行连接器适配器（例如Google Drive、SMTP、Stripe、FHIR等），并通过REST、gRPC或MCP对外提供服务。它提供了一致的执行合约，具备内置的验证、弹性和遥测功能。 ## 前置条件 开始之前，请确保您具备： | 需求 | 版本 | 说明 | |---|---|---| | Python | 3.11+ | 运行平台所需 | | `uv` 或 `pip` | 最新版本 | `uv` 推荐用于本地开发 | | Git | 任意近期版本 | 克隆仓库所需 | | Docker | 最新版本 | 构建MCP服务器镜像和 `docker-compose.mcp.yml` 所需 | | Node.js | 任意LTS版本 | 仅需用于MCP Inspector | ## 快速开始 ### 1. 安装 ```bash git clone https://github.com/AOT-Technologies/node-wire.git cd node-wire uv sync --frozen --all-extras --dev ``` *(需要 `uv`。参见 [安装](docs/installation.md) 中的锁定文件更新工作流。)* ### 2. 配置 复制示例环境文件并添加您的 `NW_ALLOWED_CONNECTORS`： ```bash # Linux/macOS/PowerShell cp sample.env .env # Windows (CMD) copy sample.env .env ``` *(编辑 `.env` 并设置 `NW_ALLOWED_CONNECTORS=http_generic` 或其他)* ### 3. 运行Grafana/OpenTelemetry（可选） 为了进行遥测可视化，在运行应用程序之前启动Grafana堆栈： ```bash cd grafana && docker compose up -d ``` ### 4. 运行 **Bash（Linux/macOS）：** ```bash # 使用 uv（推荐） MODE=API uv run node-wire # 使用 python MODE=API python -m bindings_entrypoint ``` **PowerShell（Windows）：** ```powershell # 使用 uv $env:MODE="API"; uv run node-wire # 使用 python $env:MODE="API"; python -m bindings_entrypoint ``` *(模式：`API`、`GRPC`、`MCP`)* 打开 [http://localhost:8000/docs](http://localhost:8000/docs) 以查看Swagger UI。 ### 5. 遊乐场 平台包含一个交互式网页遊乐场，位于 [http://localhost:8000/playground/](http://localhost:8000/playground/)（当REST API运行时可用）。 --- ## 构建软件包（轮） 在构建Docker镜像之前，构建Python软件包为二进制轮： ```bash bash scripts/build-packages.sh ``` 参见 [docs/packaging.md](docs/packaging.md) 以获取有关轮构建生命周期的详细信息。 --- ## 构建MCP服务器镜像 当您需要为各个MCP服务器（如Google Drive、SMTP、Stripe、Salesforce或Slack）构建Docker镜像时，请使用此工作流。 ### 构建前提 在构建镜像之前，请确保： - Docker已安装并可在您的shell路径上使用。 - 您正在从仓库根目录运行命令。 - 已首先构建本地轮。 参见 [docs/local-packages-to-images.md](docs/local-packages-to-images.md) 以获取完整的软件包->镜像工作流和每个镜像所需的轮工件。 ### 构建所有MCP服务器镜像 所有MCP服务器镜像均从仓库根目录使用自动化脚本构建： ```bash ./scripts/build-mcp-images.sh ``` 要标记为特定版本（默认为 `pyproject.toml` 中的版本）： ```bash ./scripts/build-mcp-images.sh --version 1.0.0 ``` 这会生成标记为 `latest` 和版本字符串的镜像： | 镜像名称 | 标签 | |---|---| | `nw-google-drive` | `nw-google-drive:latest`, `nw-google-drive:1.0.0` | | `nw-smartonfhir-epic` | `nw-smartonfhir-epic:latest`, `nw-smartonfhir-epic:1.0.0` | | `nw-smartonfhir-cerner` | `nw-smartonfhir-cerner:latest`, `nw-smartonfhir-cerner:1.0.0` | | `nw-smtp` | `nw-smtp:latest`, `nw-smtp:1.0.0` | | `nw-stripe` | `nw-stripe:latest`, `nw-stripe:1.0.0` | | `nw-salesforce` | `nw-salesforce:latest`, `nw-salesforce:1.0.0` | | `nw-slack` | `nw-slack:latest`, `nw-slack:1.0.0` | ### 手动构建单个镜像 要从仓库根目录手动构建单个镜像： ```bash # 仅限Google Drive docker build -f docker/google-drive/Dockerfile -t nw-google-drive:latest . # 仅限Epic FHIR docker build -f docker/fhir-epic/Dockerfile -t nw-smartonfhir-epic:latest . # 仅限Cerner FHIR docker build -f docker/fhir-cerner/Dockerfile -t nw-smartonfhir-cerner:latest . # 仅限SMTP docker build -f docker/smtp/Dockerfile -t nw-smtp:latest . # 仅限Stripe docker build -f docker/stripe/Dockerfile -t nw-stripe:latest . # 仅限Salesforce docker build -f docker/salesforce/Dockerfile -t nw-salesforce:latest . # 仅限Slack docker build -f docker/slack/Dockerfile -t nw-slack:latest . ``` > **注意：** 构建上下文必须是仓库根目录（`.`），以便 `COPY src/` 和 `COPY config/` 指令正确解析。 --- ## 使用Docker Compose运行MCP服务器 ### Compose前提 在启动MCP容器之前，请确保： - MCP服务器镜像已在本地构建。 - 您的 `.env` 文件已填充了您要运行的连接器所需的凭据。 `docker-compose.mcp.yml` 以stdio容器的形式启动所有MCP服务器，单个命令即可完成。这对于在配置ToolHive之前进行本地验证非常有用。每个服务都将其 `NW_ALLOWED_CONNECTORS` 固定为其自己的连接器，因此 `.env` 中的广泛值不会使每个连接器的镜像导入可选依赖项，而这些依赖项并不包含这些依赖项。 ```bash # 确保存在本地轮并且您的 .env 已填充，然后： docker compose -f docker-compose.mcp.yml up --build ``` 启动特定服务器： ```bash docker compose -f docker-compose.mcp.yml up --build nw-smartonfhir-epic ``` --- ## 文档 有关更详细的信息，请参阅以下指南： - **[架构](docs/architecture.md)** — 分层设计和数据流。 - **[安装](docs/installation.md)** — 详细设置和前提条件。 - **[配置](docs/configuration.md)** — 环境变量和 `connectors.yaml`。 - **[连接器指南](docs/connectors.md)** — 如何使用和构建连接器。 - **[MCP集成](docs/mcp.md)** — 将Node Wire与AI代理一起使用。 - **[故障排除](docs/troubleshooting.md)** — 常见错误和修复。 - **[MCP服务器和Docker](docs/mcp-servers.md)** — 将单个连接器部署为MCP服务器。 - **[打包和发布](docs/packaging.md)** — 轮构建和CI流程。 - **[发布回滚](docs/release-rollback.md)** — PyPI yank和纠正发布程序。 - **[代码质量和合规性](docs/code-quality-compliance.md)** — Ruff、Mypy、pre-commit、REUSE和依赖项合规性。 - **[隐私](docs/privacy.md)** — 数据处理和日志记录指南。 - **[HIPAA考虑因素](docs/compliance/hipaa-considerations.md)** — 在受监管的医疗保健环境中部署Node Wire。 - **[ToolHive代理场景](docs/toolhive_agent_scenario.md)** — 终端到终端的FHIR → Google Drive → 电子邮件工作流。 - **[变更日志](CHANGELOG.md)** — 发布历史。 ## 开发者文档 - 单个连接器MCP服务器（ToolHive）：[docs/mcp-servers.md](docs/mcp-servers.md) - 创建新连接器：[docs/connectors.md](docs/connectors.md) - 代码质量/合规性（Ruff、Mypy、REUSE、pip-audit）：[docs/code-quality-compliance.md](docs/code-quality-compliance.md) - 质量/安全门控（Bandit、CodeQL）：[docs/quality-security-gates.md](docs/quality-security-gates.md) --- ## 贡献 欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置、质量检查和PR约定，以及我们的 [行为准则](CODE_OF_CONDUCT.md)。 ## 安全 报告漏洞时，请遵循我们的 [安全策略](SECURITY.md)。不要为安全报告打开公共问题。 --- ## 许可证 该项目根据Apache License 2.0许可。有关详细信息，请参见LICENSE文件。