@intentwake/mcp

@intentwake/mcp

Unified local stdio MCP server for IntentWake account workflows and complete file transfers.

The server proxies the authenticated hosted IntentWake MCP tool surface without reimplementing its account, list, wallet, funding, policy, billing, idempotency, authorization, or audit behavior. It adds three local-only semantic tools:

• upload_list_file streams an allowed local file into a canonical IntentWake list.
• append_list_file streams an allowed local file into a canonical append session.
• download_result_to_file saves an already-unlocked NDJSON or CSV result artifact locally. It never unlocks or charges.

File bytes move directly between the local process and IntentWake transfer endpoints. They do not enter MCP arguments, results, or model context.

Requirements

• Node.js 22 or newer.
• An IntentWake connection token with the scopes needed by the tools you call.
• One or more absolute local roots that you explicitly approve.

Configure

Run the server with:

npx -y @intentwake/mcp

Configure these values in your MCP client's user-level secret/environment settings, not in a project or tracked file and not as visible command arguments:

• INTENTWAKE_CONNECTION_TOKEN: the IntentWake connection bearer.
• INTENTWAKE_ALLOWED_ROOTS: approved absolute roots separated by : on macOS/Linux or ; on Windows.
• INTENTWAKE_MCP_URL: optional hosted control-plane URL override.
• INTENTWAKE_API_URL: optional public API URL override used for canonical CSV streams.
• INTENTWAKE_HOSTED_TOOL_POLICY: optional hosted manifest policy. The default, open, exposes every compatible hosted tool. allowlist pins the hosted surface to the names shipped with this package version.

With no allowed roots configured, every file operation is refused. There are no implicit current directory or Downloads defaults.

At startup the server negotiates one authenticated hosted MCP connection, validates the complete hosted manifest, and fails closed if the gateway is unavailable, incompatible, missing required tool annotations, or collides with a local tool. That same hosted connection handles proxied calls and the control-plane steps used by local file transfers. Hosted names, schemas, annotations, structured results, safe errors, and metadata pass through unchanged.

File safety

Source paths resolve to real paths inside an approved root and must be regular files. Directories, devices, outside paths, and symlink escapes are refused. Upload and append parts stream in bounded byte ranges and resume the same hosted session with the same idempotency key if transfer URLs expire.

Downloads default to overwrite=false. The bridge writes a unique sibling temporary file, computes byte count and SHA-256 while streaming, verifies expectations supplied by IntentWake, and atomically installs the completed file. Partial temporary files are removed after failures. If the bound destination directory moves outside its configured root during a transfer, the in-progress temporary file moves with that directory. The bridge rechecks directory identity and root ancestry before streaming, after staging, and at installation; it removes the temporary file through the bound directory and returns destination_changed without installing a result.

NDJSON downloads use an already-authorized result artifact URL. CSV downloads stream the existing authenticated IntentWake CSV response; the bridge does not transform result rows locally. Locked artifacts fail closed and must be unlocked separately through an explicit IntentWake operation.

The hosted HTTP MCP endpoint remains available for clients without local filesystem access.

Registration and upgrade

For a filesystem-capable client, register one user-scoped server named intentwake that runs npx -y @intentwake/mcp@0.2.3. That published unified release exposes the complete hosted account workflow and the three local-file tools. Do not register a second direct hosted server for the same client unless the client cannot run stdio.

For a remote or hosted client without local filesystem access, direct hosted HTTP MCP remains the supported fallback. Configure its bearer header with that client's environment-variable expansion for INTENTWAKE_CONNECTION_TOKEN; do not paste a token into a command, tracked config, or chat.

Existing intentwake-cloud and intentwake-files registrations are a temporary two-server setup. Inspect those registrations and any same-name registration in another scope before changing anything. Add or replace a registration only after the user confirms; verify that the unified server exposes hosted and local-file tools before the user removes either legacy registration.

After npm publication, verify the available package version without starting a server:

npm view @intentwake/mcp version

Use version 0.2.0 or later for the unified hosted-plus-local surface. Production defaults to https://mcp.intentwake.com/mcp. For staging, set INTENTWAKE_MCP_URL (and INTENTWAKE_API_URL when CSV downloads are needed) to the approved staging origins; never point a staging client at production by default.