Metadata-Version: 2.5
Name: quilr-local-mcp-runtime
Version: 0.3.1
Summary: Native Python connector for gateway-governed local MCP tools
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.12
Requires-Dist: cryptography<49,>=46
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: packaging<27,>=24.2
Description-Content-Type: text/markdown

# Quilr native Python MCP connector

Connect approved local MCP tools to your organization's Quilr gateway. Python
MCPs run in Python; Node MCPs run in Node when Node is installed. The connector
itself requires only Python 3.12 or newer on macOS or Linux.

Use the exact version and gateway supplied by your administrator. Once this
release is published on PyPI, the one-command setup is:

```sh
uvx --from 'quilr-local-mcp-runtime==0.3.1' quilr-mcp connect --gateway 'https://YOUR-GATEWAY' --console 'https://YOUR-CONSOLE' --organization 'YOUR-ORGANIZATION-UUID' --client cursor
```

Alternatively, install persistently with `pipx install
'quilr-local-mcp-runtime==0.3.1'` or install the reviewed wheel into your own
virtual environment with `python -m pip install /path/to/reviewed.whl`, then run
the same `quilr-mcp connect` command. A wheel can be installed directly before
the release is published. Never run the connector as root.

The command configures the selected AI client and opens browser sign-in. Approve
your computer, then open or restart your AI app. Supported clients are Cursor,
Claude Code, Claude Desktop on macOS, and VS Code with the `code` command
installed. `--client other` prints the configuration for another stdio MCP host.

The installation stores a stable launcher and its installed dependencies under
your private connection directory; AI-client startup does not depend on keeping
the temporary uvx cache. It still needs the OS Python used to connect. Reconnect
after replacing that interpreter.

Ask your AI app to check your Quilr connection and list the permitted tools.
`quilr_connect` opens browser approval when needed; `quilr_connection_status`
checks sign-in and package preparation. Credentials never belong in chat.
Packages install lazily from reviewed, signed definitions. A **Preparing** result
means the requested tool has not executed; check status and retry once ready.

Python dependencies use a private virtual environment and hash-locked PyPI wheels.
Node dependencies use an npm lockfile with integrity checks and lifecycle scripts
disabled. Installing a connector through PyPI does not convert Node MCPs into
Python, and installing through npm does not convert Python MCPs into Node.

Tool requests and results pass through the existing gateway policy path. The
connector does not grant access beyond your organization's policy, intercept
built-in AI-client tools, or provide an OS sandbox. Each MCP runs as your OS user.
For tools with internal agents, gateway enforcement covers their exposed MCP
calls, not every internal browser or model operation.

Use the printed connection directory for advanced commands:

```sh
quilr-mcp status --state /absolute/connection-directory
quilr-mcp list --state /absolute/connection-directory
quilr-mcp doctor --state /absolute/connection-directory --package PACKAGE_ID
quilr-mcp disconnect --state /absolute/connection-directory
```

Disconnect revokes this connection and removes its local credential while
preserving package and workspace files. Optional `connect --workspace`,
`--python` and `--node` select local paths. Provider environment variables stay
local and are forwarded only when declared in the approved package.

Python and npm are alternative connector installations for the same gateway.
Use one connector per AI-app connection to avoid duplicate tool registrations.
They use the same enrollment and policy protocol.


## One gateway, multiple consoles

Use the command copied from the console you signed into. Version 0.3.1 adds
`--console https://YOUR-CONSOLE`: the connector opens that origin's
`/self-service?setup=local-mcp` page, remembers it for future sign-ins, and still
sends enrollment exchanges and tool requests only to `--gateway`. Two consoles
can share a gateway without overwriting each other's sign-in destination.
The organization remains bound to the pairing and verified during exchange.

An explicit console replaces any old gateway-wide setup URL for this connection.
Running connect again without `--console` preserves the saved choice. Supplying a
new console updates it without creating a second connection for the same gateway
and organization. Restart the AI app after reconnecting to load the new launcher.
Commands without a saved or explicit console keep the gateway's fallback URL.

The console must be an HTTPS origin, without a path, query, fragment or credentials.
Local development can use `--console http://localhost:3000` with
`--allow-loopback-http`; this never allows HTTP on a remote console. The browser
receives only the short-lived user code in a URL fragment, not the verifier or
connector token. Approve only connections you initiated.
