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)

Node Wire uses a fail-closed connector allowlist. If NW_ALLOWED_CONNECTORS is missing or empty, no connectors are loaded even when they are enabled in config/connectors.yaml.

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 --all-extras --dev   # full dev + agents (matches CI)
uv sync --frozen --no-dev             # runtime only

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 . - 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 --all-extras --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¶

pytest tests/ -v

Integration tests are skipped unless the relevant environment variables (secrets) are set.