Skip to content

Installation Guide

Prerequisites

Requirement Version Notes
Python 3.11+ Required to run the platform
uv or pip Latest uv is recommended for local development
Git Any recent version Required to clone the repository
Docker Latest Required for MCP server image builds and docker-compose.mcp.yml
Node.js Any LTS Only needed for MCP Inspector

Installation Steps

1. Clone the repository

git clone https://github.com/AOT-Technologies/node-wire.git
cd node-wire

2. Configure

Copy the sample environment file and add your NW_ALLOWED_CONNECTORS: 

# Linux/macOS/PowerShell
cp sample.env .env

# Windows (CMD)
copy sample.env .env
(Edit .env and set NW_ALLOWED_CONNECTORS=http_generic or others. Unset or empty loads no connectors — fail-closed. Full reference: Configuration — Required Variables.)

By default the platform is single-tenant (every call resolves to __default__). To isolate callers by tenant, set NW_MULTITENANCY_ENABLED=true and point NW_TENANTS_PATH at a tenants.yaml file (defaults to config/tenants.yaml). See Configuration — Multi-tenancy.

3. Install dependencies

Using uv (recommended):

The repository commits uv.lock for reproducible installs. Use --frozen in CI and local dev:

uv sync --frozen --extra agents --dev   # full dev + agents (matches CI)
uv sync --frozen --no-dev               # runtime only
# Regenerating gRPC stubs only (scripts/generate-grpc-stubs.sh):
# uv sync --frozen --extra grpc-codegen

Plain uv sync --frozen (no --no-dev) still installs the dev dependency group — pyproject.toml sets default-groups = ["dev"] — so it is not a runtime-only install on its own.

When you change dependencies in pyproject.toml, regenerate and commit the lockfile:

uv lock

Using pip (unpinned; not recommended for reproducible builds): - Full install (including AI agents): pip install -e ".[agents]" - Minimal install (REST/gRPC only): pip install -e . - gRPC stub regeneration: pip install -e ".[grpc-codegen]" (optional; stubs are already committed) - Dev tooling (ruff/mypy/pytest/bandit): there is no dev extra — dev is a uv [dependency-groups] entry, not a pip install extra, so pip install -e ".[dev,agents]" fails. Use uv sync --frozen --extra agents --dev for the dev toolchain, or install ruff/mypy/pytest/bandit manually if you must stay on plain pip.

4. Verify the installation

uv run python -c "from importlib.metadata import version; print('node-wire', version('node-wire'))"

To confirm the REST API starts, run MODE=API uv run node-wire and open http://127.0.0.1:8000/health (default bind is 127.0.0.1; override with NW_REST_HOST if needed).

Running the Platform

Node Wire supports REST, gRPC, and MCP entry modes:

Mode Command Default port / transport Use case
REST API uv run node-wire 8000 HTTP clients, Swagger UI, playground
gRPC MODE=GRPC uv run node-wire 50051 gRPC clients
MCP python -m agents.mcp_entrypoint stdio or HTTP AI agents, ToolHive, Inspector

REST quick start

# Local development only
export NW_REST_AUTH_DISABLED=true

# Start the API
uv run node-wire

Once it is running:

  • Health check: GET http://localhost:8000/health
  • Swagger UI: http://localhost:8000/docs
  • Playground: http://localhost:8000/playground/

MCP notes

For MCP transport modes, Inspector usage, and multi-server deployment:

  • See mcp.md for transport setup and local MCP usage.
  • See packaging.md for pre-built per-connector Docker images and ToolHive deployment.
  • See mcp-servers.md to generate a custom standalone MCP host with nw-mcp-builder.

Development Setup

Code Quality (Linting & Formatting)

We use Ruff for linting/formatting and Mypy for type checking.

  • Check: ruff check .
  • Fix: ruff check --fix . && ruff format .
  • Types: mypy

mypy defaults to the [tool.mypy].files targets from pyproject.toml. To include tests explicitly, run mypy src tests.

Pre-commit Hooks

pre-commit install

Running Tests

uv run pytest tests/ -v
tests/playground/ (integration tests against real connector credentials) is excluded by default via --ignore=tests/playground in pyproject.toml's pytest addopts — run it explicitly with the relevant secret env vars set (see .github/workflows/pytest.yml's playground-integration job) if you need it: uv run pytest tests/playground/ --no-cov -v.