weavatrix-online

# Weavatrix Online

**Take repository intelligence across a network without handing the network
your repository.**

[![npm](https://img.shields.io/npm/v/weavatrix-online)](https://www.npmjs.com/package/weavatrix-online)
[![CI](https://github.com/Weavatrix/weavatrix-online/actions/workflows/ci.yml/badge.svg)](https://github.com/Weavatrix/weavatrix-online/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Weavatrix/weavatrix-online/blob/main/LICENSE.md)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933)](https://nodejs.org/)

The explicit network boundary of the [Weavatrix ecosystem](https://weavatrix.com/ecosystem). Core and Refactor remain separate installs.

Weavatrix Online is the MIT-licensed MCP connector for Weavatrix Cloud and
compatible customer-controlled endpoints. It keeps analysis local, produces an
inspectable source-free payload, and requires an exact short-lived confirmation
before that payload can leave the machine.

The public Online profile exposes **7 MCP tools** for endpoint discovery,
advisories, malware review, architecture contracts, and controlled
synchronization. The local `weavatrix-js` graph engine is an implementation
detail: its tools are not re-exported, so installing Core, Refactor, and Online
together does not duplicate their catalogs in an agent's context.

Installing or starting Online does not synchronize anything. `preview_sync`
makes no network request; `sync_graph` accepts only the still-valid preview for
the same repository, destination, payload, and graph.

## Choose the right Weavatrix package

| Product | Install | Boundary |
| --- | --- | --- |
| `weavatrix` | npm or Cargo | Native local-first MCP product. Both package managers distribute the same local Weavatrix server and engine. |
| `weavatrix-rust` | Cargo | Protocol-independent Rust repository-intelligence engine for library and CLI use; it does not own MCP transport. |
| `weavatrix-refactor` | npm or Cargo | Native extension-only transactional refactoring; it uses the Rust graph engine internally. |
| `weavatrix-online` | npm | This optional network extension: source-free Cloud/self-hosted workflows over an internal local graph runtime. |

Online currently uses the JavaScript graph/runtime package internally:

```text
weavatrix-online 0.3.4
  └─ weavatrix-js 0.3.x (internal; no Core tools re-exported)
```

It does not proxy the native `weavatrix` executable, import
`weavatrix-refactor`, or copy either engine. Use `weavatrix` when the graph must remain entirely local. Use
`weavatrix-online` when endpoint status, remotely managed architecture
contracts, advisory refresh, or explicit source-free synchronization is part of
the workflow.

## Install and run

### Plugins for Cursor, Codex, Claude, and Grok

The repository now contains one portable plugin bundle at
`plugins/weavatrix-online` plus native marketplace manifests for all four
clients. The plugin starts the pinned npm release and includes an optional,
compact skill with one lazily loaded card per Online method.

```text
codex plugin marketplace add Weavatrix/weavatrix-online --sparse .agents/plugins plugins/weavatrix-online
codex plugin add weavatrix-online@weavatrix-online

claude plugin marketplace add Weavatrix/weavatrix-online --sparse .claude-plugin plugins
claude plugin install weavatrix-online@weavatrix-online

grok plugin marketplace add Weavatrix/weavatrix-online
```

Cursor can load the bundle locally from
`~/.cursor/plugins/local/weavatrix-online`; public marketplace discovery starts
after the listing is reviewed and approved.

### Direct MCP launch

Run the pinned release without a global install:

```powershell
npx -y weavatrix-online@0.3.4 C:\path\to\repository
```

The command starts a stdio MCP server. The first positional argument is the
repository to analyze. An existing graph can be supplied explicitly:

```powershell
npx -y weavatrix-online@0.3.4 C:\graphs\repository\graph.json C:\path\to\repository
```

The npm package is intentionally an executable MCP product; it does not
advertise a nonexistent JavaScript library entry point.

### Codex

```toml
[mcp_servers.weavatrix_online]
command = "npx"
args = ["-y", "weavatrix-online@0.3.4", "C:\\path\\to\\repository"]

[mcp_servers.weavatrix_online.env]
WEAVATRIX_SYNC_URL = "https://app.weavatrix.com/api/v1/graphs/sync"
WEAVATRIX_SYNC_TOKEN = "load-from-runtime-secret-storage"
```

### Claude Desktop

```json
{
  "mcpServers": {
    "weavatrix-online": {
      "command": "npx",
      "args": [
        "-y",
        "weavatrix-online@0.3.4",
        "C:\\path\\to\\repository"
      ],
      "env": {
        "WEAVATRIX_SYNC_URL": "https://app.weavatrix.com/api/v1/graphs/sync",
        "WEAVATRIX_SYNC_TOKEN": "load-from-runtime-secret-storage"
      }
    }
  }
}
```

Keep bearer tokens in the MCP client's runtime secret storage. Do not put them
in Git, a committed `.env`, release logs, or checked-in MCP configuration.

## The seven Online tools

| Tool | Network | Evidence and effect |
| --- | --- | --- |
| `online_status` | Yes | Discovers endpoint capabilities, payload versions, limits, and auth mode without repository evidence. |
| `refresh_advisories` | Yes | Inventories exact dependency coordinates, queries OSV, validates returned records, and atomically refreshes the local cache. |
| `scan_dependency_vulnerabilities` | No | Matches the current inventory against that cache. Missing, stale, partial, or mismatched coverage remains `NOT_CHECKED` or `PARTIAL`. |
| `scan_dependency_malware` | No | Performs bounded static review of installed dependency files. Findings require review and are never a compromise verdict. |
| `pull_architecture_contract` | Yes | Fetches the owner-approved target for the active opaque repository ID, validates it, and updates the local graph cache. |
| `preview_sync` | No | Serializes the exact allowlisted payload, hashes it, and issues a five-minute confirmation token. |
| `sync_graph` | Yes | Sends only the payload approved by `preview_sync`; `dry_run:false` and the matching token are mandatory. |

Install [Weavatrix Core](https://github.com/Weavatrix/weavatrix#readme)
for read-only repository intelligence and
[Weavatrix Refactor](https://github.com/Weavatrix/weavatrix-refactor#readme)
for guarded source changes. Their methods remain in their owning products.

## Typical workflows

Check endpoint compatibility before doing any repository work:

```json
{"name":"online_status","arguments":{"timeout_ms":10000}}
```

Refresh advisory evidence, then evaluate it locally:

```json
{"name":"refresh_advisories","arguments":{"timeout_ms":20000}}
{"name":"scan_dependency_vulnerabilities","arguments":{"max_age_days":30}}
```

Review the exact upload without sending it:

```json
{"name":"preview_sync","arguments":{"payload_version":3}}
```

After a human or trusted controller approves the displayed destination, section
summary, counts, size, and body hash, use the returned token:

```json
{
  "name": "sync_graph",
  "arguments": {
    "payload_version": 3,
    "dry_run": false,
    "confirm_token": "token-returned-by-preview_sync",
    "timeout_ms": 30000
  }
}
```

Changing the graph, repository, destination, payload, or expiry state invalidates
that approval. A rejected or unavailable endpoint leaves the graph local.

## Network and consent boundary

```text
local repository
      │
      ▼
local graph + derived evidence
      │
      ▼
preview_sync ── inspect destination, sections, counts, size, and SHA-256
      │
      ▼
explicit approval
      │
      ▼
sync_graph ── capability negotiation ── approved endpoint
```

The connector enforces:

- HTTPS for every non-loopback destination;
- loopback-only HTTP for local development;
- no credentials embedded in URLs;
- endpoint capability negotiation before upload;
- a bounded versioned payload allowlist;
- exact preview hashing and a short-lived confirmation token;
- honest `NOT_CHECKED` and `PARTIAL` states when evidence is incomplete.

The sync payload contains bounded graph topology and selected derived evidence.
It excludes source bodies, snippets, absolute host paths, environment values,
credentials, Git remotes, and fields outside the wire allowlist. “Source-free”
does not mean anonymous: review the displayed repository identity, destination,
counts, sections, and hash before approval.

## Configuration

| Variable | Required | Meaning |
| --- | --- | --- |
| `WEAVATRIX_SYNC_URL` | For Online network workflows | Cloud or compatible self-hosted sync endpoint. |
| `WEAVATRIX_SYNC_TOKEN` | For Cloud/authenticated endpoints | Scoped bearer token sent only to the approved endpoint. |
| `WEAVATRIX_CAPABILITIES_URL` | No | Explicit capability document; otherwise `/api/v1/capabilities` with legacy `/api/health` fallback. |
| `WEAVATRIX_ARCHITECTURE_URL` | No | Explicit owner-approved architecture-contract endpoint. |
| `WEAVATRIX_PRECISION` | No | Local semantic precision: `lsp` (default) or `off`. |
| `WEAVATRIX_GRAPH_HOME` | No | Override local graph/cache storage. |
| `WEAVATRIX_ADVISORY_STORE` | No | Override the local advisory-cache file. |

Compatible endpoints must implement the versioned capability and sync
contracts. Capability discovery itself sends no repository evidence.

## Security evidence without false certainty

Advisory refresh covers pinned npm, PyPI, Go, Maven/Gradle, and crates.io
coordinates found in bounded repository manifests. A clean zero is allowed only
when the current inventory matches a complete, current Online cache.

Malware review is static and bounded. It can identify evidence such as
download-and-execute lifecycle scripts, reverse-shell patterns, decoded
execution, miner indicators, credential-file reads, or suspicious exfiltration
endpoints. It cannot prove execution, provenance, credential exposure, safety,
or compromise.

Architecture contracts are validated locally before becoming active.

Report vulnerabilities privately th