nxtlinq-mcp-proxy 0.1.0__tar.gz

nxtlinq_mcp_proxy-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+recursive-include docs *.md *.svg *.py *.txt
+include mkdocs.yml
+include README.md PACKAGE.md
+recursive-include tests *.py
+prune examples
+prune site
+prune .nxtlinq
+global-exclude *.py[cod] .DS_Store *.env .env* *.local.json .pypirc

nxtlinq_mcp_proxy-0.1.0/PACKAGE.md

@@ -0,0 +1,66 @@
+# nxtlinq MCP Proxy
+
+Package an existing MCP server, deploy it on a private Docker network, and
+check nxtlinq tool permissions before forwarding calls. The original MCP
+implements the tools. Desktop Setup manages identity and tool permissions.
+
+## Requirements
+
+- uv on macOS or Linux; the guide uses uv to provide Python 3.11.
+- Docker with Compose and Buildx, running on the deployment host.
+- A dedicated nxtlinq thirdParty service API Key and Secret.
+- An Agent supporting Streamable HTTP MCP with an Authorization header.
+  Automatic Codex configuration is an optional integration.
+
+## Install
+
+Confirm `uv --version` works and that `docker info`,
+`docker compose version`, and `docker buildx version` succeed. The source
+distribution includes step-by-step environment installation guides at
+`docs/en/environment.md` and `docs/zh-TW/environment.md`; skip components
+that already pass these checks.
+
+In a new working directory, create a Python virtual environment with uv, then
+install the Proxy and its dependencies. uv downloads Python 3.11 if needed. For an
+existing installation, activate its environment and skip environment creation.
+
+```sh
+mkdir nxtlinq-tools
+cd nxtlinq-tools
+uv venv --python 3.11 .venv
+source .venv/bin/activate
+```
+
+Install from PyPI:
+
+```sh
+uv pip install 'nxtlinq-mcp-proxy[desktop]==0.1.0'
+```
+
+uv downloads the Proxy and its dependencies from PyPI. `[desktop]` includes Setup dependencies.
+
+Download: [Proxy 0.1.0](https://pypi.org/project/nxtlinq-mcp-proxy/0.1.0/#files).
+
+## Deploy
+
+```sh
+nxtlinq-mcp pack my-mcp-bundle
+nxtlinq-mcp init my-tools --bundle my-mcp-bundle
+cd my-tools
+nxtlinq-mcp setup
+```
+
+Choose the packaging method for your MCP. During initialization, select `other`
+for manual MCP configuration or `codex` for the optional automatic integration.
+Enter the service environment and credentials when prompted, review the discovered
+tools, and confirm registration. Complete Setup and enable the tools you need,
+then connect your Agent using the chosen connection option.
+
+Use a pinned npm/Python package, a custom Dockerfile, or an existing HTTP image.
+Optional recipes demonstrate Filesystem, Memory, and GitHub PAT/OAuth.
+Each deployment supports up to 16 MCP servers and one user's Setup session. Configure host folders and permitted API destinations for each MCP.
+The proxy governs calls through its MCP endpoint; independently accessible
+files, APIs, or application endpoints require their own access controls.
+
+English and Traditional Chinese guides are included in the source distribution
+under `docs/en` and `docs/zh-TW`.

nxtlinq_mcp_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: nxtlinq-mcp-proxy
+Version: 0.1.0
+Summary: Configure and deploy an isolated HTTP MCP behind nxtlinq authorization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dotenv<2,>=1
+Provides-Extra: desktop
+Requires-Dist: nxtid-sdk[desktop]==0.3.6; extra == "desktop"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9; extra == "docs"
+Provides-Extra: release
+Requires-Dist: build<2,>=1.2; extra == "release"
+Requires-Dist: twine<7,>=6; extra == "release"
+
+# nxtlinq MCP Proxy
+
+Package an existing MCP server, deploy it on a private Docker network, and
+check nxtlinq tool permissions before forwarding calls. The original MCP
+implements the tools. Desktop Setup manages identity and tool permissions.
+
+## Requirements
+
+- uv on macOS or Linux; the guide uses uv to provide Python 3.11.
+- Docker with Compose and Buildx, running on the deployment host.
+- A dedicated nxtlinq thirdParty service API Key and Secret.
+- An Agent supporting Streamable HTTP MCP with an Authorization header.
+  Automatic Codex configuration is an optional integration.
+
+## Install
+
+Confirm `uv --version` works and that `docker info`,
+`docker compose version`, and `docker buildx version` succeed. The source
+distribution includes step-by-step environment installation guides at
+`docs/en/environment.md` and `docs/zh-TW/environment.md`; skip components
+that already pass these checks.
+
+In a new working directory, create a Python virtual environment with uv, then
+install the Proxy and its dependencies. uv downloads Python 3.11 if needed. For an
+existing installation, activate its environment and skip environment creation.
+
+```sh
+mkdir nxtlinq-tools
+cd nxtlinq-tools
+uv venv --python 3.11 .venv
+source .venv/bin/activate
+```
+
+Install from PyPI:
+
+```sh
+uv pip install 'nxtlinq-mcp-proxy[desktop]==0.1.0'
+```
+
+uv downloads the Proxy and its dependencies from PyPI. `[desktop]` includes Setup dependencies.
+
+Download: [Proxy 0.1.0](https://pypi.org/project/nxtlinq-mcp-proxy/0.1.0/#files).
+
+## Deploy
+
+```sh
+nxtlinq-mcp pack my-mcp-bundle
+nxtlinq-mcp init my-tools --bundle my-mcp-bundle
+cd my-tools
+nxtlinq-mcp setup
+```
+
+Choose the packaging method for your MCP. During initialization, select `other`
+for manual MCP configuration or `codex` for the optional automatic integration.
+Enter the service environment and credentials when prompted, review the discovered
+tools, and confirm registration. Complete Setup and enable the tools you need,
+then connect your Agent using the chosen connection option.
+
+Use a pinned npm/Python package, a custom Dockerfile, or an existing HTTP image.
+Optional recipes demonstrate Filesystem, Memory, and GitHub PAT/OAuth.
+Each deployment supports up to 16 MCP servers and one user's Setup session. Configure host folders and permitted API destinations for each MCP.
+The proxy governs calls through its MCP endpoint; independently accessible
+files, APIs, or application endpoints require their own access controls.
+
+English and Traditional Chinese guides are included in the source distribution
+under `docs/en` and `docs/zh-TW`.

nxtlinq_mcp_proxy-0.1.0/README.md

@@ -0,0 +1,74 @@
+# nxtlinq MCP Proxy
+
+Deploy existing MCP servers on private Docker networks and check nxtlinq tool
+permissions before forwarding each call. Your Agent connects to a single MCP
+endpoint; downstream MCPs keep their original tools and account authentication.
+
+**Start here:** [English guide](docs/en/quickstart.md) · [繁體中文指南](docs/zh-TW/quickstart.md)
+
+[![Deployment topology](docs/assets/topology-en.svg)](docs/assets/topology-en.svg)
+
+See [Topology and request flow](docs/en/architecture.md) for the authorization,
+Setup, network, and resource boundaries.
+
+## Install and deploy
+
+Follow the [environment guide](docs/en/environment.md) to prepare uv and Docker
+Desktop or Colima, including Compose and Buildx. Skip components that already
+pass the checks.
+
+Then follow [Install and deploy](docs/en/quickstart.md):
+
+1. Install `nxtlinq-mcp-proxy[desktop]` with uv; dependencies are installed automatically.
+2. Package your MCP using `pack`, or supply an existing HTTP MCP image.
+3. Run `init` to configure service credentials, build the isolated deployment, and review/register tools.
+4. Open `setup` to configure identity and tool permissions.
+5. Connect your Agent and verify an allowed and a denied call.
+
+Download: [nxtlinq MCP Proxy on PyPI](https://pypi.org/project/nxtlinq-mcp-proxy/0.1.0/).
+The installation guide includes the complete uv command.
+
+## Product responsibilities
+
+| Component | Responsibility |
+| --- | --- |
+| Proxy | Authenticate the MCP connection, check tool permissions, forward allowed calls |
+| Deployment tooling | Build/run private MCP containers, configure mounts and permitted HTTPS destinations, verify isolation |
+| Desktop Setup | User identity and nxtlinq tool permissions |
+| Downstream MCP | Tool implementation, provider account login, data handling |
+| Agent | Select and request tools through the MCP connection |
+
+The primary interface is Streamable HTTP MCP with an Authorization header.
+[Automatic Codex configuration](docs/en/agents.md) is an optional convenience;
+other compatible clients use the same endpoint and authorization behavior.
+
+## Examples
+
+The [example catalogue](docs/en/examples.md) explains what each recipe demonstrates
+and the settings it needs:
+
+- **Filesystem:** host folder sharing, read/write permissions, and container paths.
+- **Memory:** persistent data across container recreation.
+- **External API / GitHub PAT:** outbound destinations and backend credentials.
+- **GitHub OAuth:** provider consent, callback routing, and an independent example login script.
+- **Application control:** container browsers or connections to host application protocols.
+- **Local computation:** tools that do not need external API access.
+
+Follow the downstream MCP's instructions for external account login. The
+[GitHub OAuth example](docs/en/authentication.md) provides its own login script.
+Use `nxtlinq-mcp setup` to manage nxtlinq identity and tool permissions.
+
+## Scope and operation
+
+A deployment supports 1–16 MCPs, one nxtlinq service, and one user's Setup session.
+Each backend has its own internal network, no published tool port, a read-only
+root filesystem, and only explicitly configured mounts and outbound destinations.
+
+The local endpoint is bound to loopback. The Agent runs on the deployment host;
+it is not contained by this deployment. Independent host file access, application
+control endpoints, other APIs, and Docker administration remain outside the tool
+permission boundary.
+
+See [Operations and troubleshooting](docs/en/operations.md) for startup, updates,
+folder sharing, tool registration, and diagnostics. See [Package an MCP](docs/en/packaging.md)
+for generic npm/Python packaging and custom Dockerfile requirements.

nxtlinq_mcp_proxy-0.1.0/docs/assets/topology-en.svg

@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="830" viewBox="0 0 1280 830" role="img" aria-labelledby="title desc">
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/></marker>
+</defs>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans CJK TC', sans-serif; fill: #e5eaf2; }
+.title { font-size: 26px; font-weight: 700; } .group { font-size: 13px; fill: #a3b1c8; letter-spacing: 1px; font-weight: 600; }
+.label { font-size: 18px; font-weight: 650; } .body { font-size: 14px; fill: #bdc9dc; } .small { font-size: 12px; fill: #aab9d0; }
+</style>
+<rect width="1280" height="830" rx="16" fill="#10151e"/>
+
+<title id="title">nxtlinq MCP Proxy — deployment topology</title>
+<desc id="desc">Agent and Setup connect to the Proxy. The Proxy checks nxtlinq permissions before forwarding calls to isolated MCP servers. Each MCP accesses only explicitly configured resources. Denied calls do not reach an MCP.</desc>
+<text x="30" y="42" class="title">nxtlinq MCP Proxy · deployment topology</text>
+<rect x="320" y="75" width="585" height="115" rx="10" fill="#1b2331" stroke="#7573b9" stroke-width="1.5"/>
+<text x="336" y="104" class="label">nxtlinq services</text>
+<text x="336" y="130" class="body">Identity · tool catalogue · user permissions</text>
+<text x="336" y="153" class="body">Service credentials stay on the Proxy side</text>
+<rect x="22" y="75" width="252" height="565" rx="12" fill="none" stroke="#506382" stroke-dasharray="5 5"/>
+<text x="37" y="99" class="group">DEPLOYMENT HOST / CLIENTS</text>
+<rect x="290" y="267" width="663" height="426" rx="12" fill="none" stroke="#506382" stroke-dasharray="5 5"/>
+<text x="305" y="291" class="group">DOCKER DEPLOYMENT</text>
+<rect x="38" y="125" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="154" class="label">nxtlinq-mcp CLI</text>
+<text x="54" y="180" class="body">init / up / down</text>
+<text x="54" y="203" class="body">Manage Docker deployment</text>
+<path d="M 258 175 L 282 175 L 282 267 L 290 267" fill="none" stroke="#a3b1c8" stroke-width="2" stroke-dasharray="5 5" marker-end="url(#arrow)"/>
+<text x="40" y="246" class="small">Build / start containers</text>
+<rect x="38" y="348" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="377" class="label">Agent</text>
+<text x="54" y="403" class="body">Any compatible MCP client</text>
+<text x="54" y="426" class="body">Codex auto-connect: optional</text>
+<rect x="38" y="511" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="540" class="label">Desktop Setup</text>
+<text x="54" y="566" class="body">Identity &amp; tool permissions</text>
+<text x="54" y="589" class="body">Open: nxtlinq-mcp setup</text>
+<rect x="310" y="340" width="253" height="247" rx="10" fill="#202b43" stroke="#87a4f3" stroke-width="1.5"/>
+<text x="326" y="369" class="label">nxtlinq MCP Proxy</text>
+<text x="326" y="395" class="body">MCP endpoint: 127.0.0.1:8765</text>
+<text x="326" y="418" class="body">Setup API: 127.0.0.1:8766</text>
+<text x="326" y="441" class="body">1. Identify the requested tool</text>
+<text x="326" y="464" class="body">2. Check user permission</text>
+<text x="326" y="487" class="body">3. Forward only if allowed</text>
+<text x="326" y="515" class="small">Host-mapped endpoints above</text>
+<rect x="326" y="533" width="220" height="34" rx="6" fill="#482c39"/>
+<text x="338" y="555" class="body" style="fill:#ffb2be">Denied → return error</text>
+<rect x="629" y="303" width="307" height="169" rx="12" fill="none" stroke="#59a793" stroke-dasharray="5 5"/>
+<text x="644" y="327" class="group">PRIVATE NETWORK A</text>
+<rect x="646" y="340" width="272" height="108" rx="10" fill="#1b2331" stroke="#59a793" stroke-width="1.5"/>
+<text x="662" y="369" class="label">MCP A</text>
+<text x="662" y="395" class="body">Original API-backed tools</text>
+<text x="662" y="418" class="body">Tool port is not published</text>
+<rect x="629" y="503" width="307" height="169" rx="12" fill="none" stroke="#59a793" stroke-dasharray="5 5"/>
+<text x="644" y="527" class="group">PRIVATE NETWORK B</text>
+<rect x="646" y="540" width="272" height="108" rx="10" fill="#1b2331" stroke="#59a793" stroke-width="1.5"/>
+<text x="662" y="569" class="label">MCP B</text>
+<text x="662" y="595" class="body">Original file / memory tools</text>
+<text x="662" y="618" class="body">Tool port is not published</text>
+<text x="984" y="289" class="group">CONFIGURED RESOURCES</text>
+<rect x="985" y="334" width="272" height="142" rx="10" fill="#1b2331" stroke="#ba9c68" stroke-width="1.5"/>
+<text x="1001" y="363" class="label">External APIs</text>
+<text x="1001" y="389" class="body">Allowed destinations only</text>
+<text x="1001" y="412" class="body">Via HTTPS egress proxy</text>
+<text x="1001" y="435" class="body">Credentials belong to the MCP</text>
+<rect x="985" y="540" width="272" height="112" rx="10" fill="#1b2331" stroke="#ba9c68" stroke-width="1.5"/>
+<text x="1001" y="569" class="label">Files / persistent data</text>
+<text x="1001" y="595" class="body">Selected host folder or volume</text>
+<text x="1001" y="618" class="body">Explicit read / write mode</text>
+<path d="M 258 395 L 310 395" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<text x="40" y="332" class="small">MCP calls / results</text>
+<path d="M 258 558 L 310 558" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)" stroke-dasharray="5 5"/>
+<text x="40" y="495" class="small">Settings / session state</text>
+<path d="M 437 340 L 437 190" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)" stroke-dasharray="5 5"/>
+<text x="452" y="223" class="body">Identity / permission requests</text>
+<text x="452" y="244" class="body">and service responses</text>
+<path d="M 563 395 L 646 395" fill="none" stroke="#74d8b6" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 563 499 L 599 499 L 599 587 L 646 587" fill="none" stroke="#74d8b6" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 918 395 L 985 395" fill="none" stroke="#e4bf7f" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 918 587 L 985 587" fill="none" stroke="#e4bf7f" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<text x="31" y="729" class="body">Blue: client and service traffic   ·   Green: authorized tool forwarding   ·   Gold: configured resource access</text>
+<text x="31" y="760" class="body">Separate private network per MCP. No direct Agent → downstream MCP tool endpoint.</text>
+<text x="31" y="786" class="small">Boundary: independently accessible host files, application endpoints and Docker admin access remain outside this control.</text>
+</svg>

nxtlinq_mcp_proxy-0.1.0/docs/assets/topology-zh.svg

@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="830" viewBox="0 0 1280 830" role="img" aria-labelledby="title desc">
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/></marker>
+</defs>
+<style>
+text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans CJK TC', sans-serif; fill: #e5eaf2; }
+.title { font-size: 26px; font-weight: 700; } .group { font-size: 13px; fill: #a3b1c8; letter-spacing: 1px; font-weight: 600; }
+.label { font-size: 18px; font-weight: 650; } .body { font-size: 14px; fill: #bdc9dc; } .small { font-size: 12px; fill: #aab9d0; }
+</style>
+<rect width="1280" height="830" rx="16" fill="#10151e"/>
+
+<title id="title">nxtlinq MCP Proxy — 部署拓樸</title>
+<desc id="desc">Agent 與 Setup 連到 Proxy。Proxy 檢查 nxtlinq 權限後，才轉送工具呼叫至隔離的 MCP。各 MCP 只能使用明確配置的資源，未授權呼叫不會到達 MCP。</desc>
+<text x="30" y="42" class="title">nxtlinq MCP Proxy · 部署拓樸</text>
+<rect x="320" y="75" width="585" height="115" rx="10" fill="#1b2331" stroke="#7573b9" stroke-width="1.5"/>
+<text x="336" y="104" class="label">nxtlinq 服務</text>
+<text x="336" y="130" class="body">身分驗證 · 工具清單 · 使用者權限</text>
+<text x="336" y="153" class="body">服務憑證保留於 Proxy 端</text>
+<rect x="22" y="75" width="252" height="565" rx="12" fill="none" stroke="#506382" stroke-dasharray="5 5"/>
+<text x="37" y="99" class="group">部署宿主 / 客戶端</text>
+<rect x="290" y="267" width="663" height="426" rx="12" fill="none" stroke="#506382" stroke-dasharray="5 5"/>
+<text x="305" y="291" class="group">DOCKER 部署</text>
+<rect x="38" y="125" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="154" class="label">nxtlinq-mcp CLI</text>
+<text x="54" y="180" class="body">init / up / down</text>
+<text x="54" y="203" class="body">設定與管理 Docker 部署</text>
+<path d="M 258 175 L 282 175 L 282 267 L 290 267" fill="none" stroke="#a3b1c8" stroke-width="2" stroke-dasharray="5 5" marker-end="url(#arrow)"/>
+<text x="40" y="246" class="small">建置 / 啟動容器</text>
+<rect x="38" y="348" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="377" class="label">Agent</text>
+<text x="54" y="403" class="body">相容的 MCP 客戶端</text>
+<text x="54" y="426" class="body">Codex 自動串接：選用</text>
+<rect x="38" y="511" width="220" height="98" rx="10" fill="#1b2331" stroke="#40516b" stroke-width="1.5"/>
+<text x="54" y="540" class="label">桌面 Setup</text>
+<text x="54" y="566" class="body">身分與工具權限設定</text>
+<text x="54" y="589" class="body">開啟：nxtlinq-mcp setup</text>
+<rect x="310" y="340" width="253" height="247" rx="10" fill="#202b43" stroke="#87a4f3" stroke-width="1.5"/>
+<text x="326" y="369" class="label">nxtlinq MCP Proxy</text>
+<text x="326" y="395" class="body">MCP 入口：127.0.0.1:8765</text>
+<text x="326" y="418" class="body">設定 API：127.0.0.1:8766</text>
+<text x="326" y="441" class="body">1. 辨識本次呼叫的工具</text>
+<text x="326" y="464" class="body">2. 檢查使用者權限</text>
+<text x="326" y="487" class="body">3. 允許才轉送至下游</text>
+<text x="326" y="515" class="small">以上為宿主映射入口</text>
+<rect x="326" y="533" width="220" height="34" rx="6" fill="#482c39"/>
+<text x="338" y="555" class="body" style="fill:#ffb2be">未授權 → 回傳拒絕</text>
+<rect x="629" y="303" width="307" height="169" rx="12" fill="none" stroke="#59a793" stroke-dasharray="5 5"/>
+<text x="644" y="327" class="group">私有網路 A</text>
+<rect x="646" y="340" width="272" height="108" rx="10" fill="#1b2331" stroke="#59a793" stroke-width="1.5"/>
+<text x="662" y="369" class="label">MCP A</text>
+<text x="662" y="395" class="body">原 MCP 提供 API 工具</text>
+<text x="662" y="418" class="body">工具連接埠不對宿主發布</text>
+<rect x="629" y="503" width="307" height="169" rx="12" fill="none" stroke="#59a793" stroke-dasharray="5 5"/>
+<text x="644" y="527" class="group">私有網路 B</text>
+<rect x="646" y="540" width="272" height="108" rx="10" fill="#1b2331" stroke="#59a793" stroke-width="1.5"/>
+<text x="662" y="569" class="label">MCP B</text>
+<text x="662" y="595" class="body">原 MCP 提供檔案 / 記憶工具</text>
+<text x="662" y="618" class="body">工具連接埠不對宿主發布</text>
+<text x="984" y="289" class="group">明確配置的資源</text>
+<rect x="985" y="334" width="272" height="142" rx="10" fill="#1b2331" stroke="#ba9c68" stroke-width="1.5"/>
+<text x="1001" y="363" class="label">外部 API</text>
+<text x="1001" y="389" class="body">只允許指定目的網域</text>
+<text x="1001" y="412" class="body">經由 HTTPS 出口代理</text>
+<text x="1001" y="435" class="body">憑證由下游 MCP 使用</text>
+<rect x="985" y="540" width="272" height="112" rx="10" fill="#1b2331" stroke="#ba9c68" stroke-width="1.5"/>
+<text x="1001" y="569" class="label">檔案 / 持久化資料</text>
+<text x="1001" y="595" class="body">指定宿主資料夾或 volume</text>
+<text x="1001" y="618" class="body">明確設定唯讀 / 可寫入</text>
+<path d="M 258 395 L 310 395" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<text x="40" y="332" class="small">MCP 呼叫 / 結果</text>
+<path d="M 258 558 L 310 558" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)" stroke-dasharray="5 5"/>
+<text x="40" y="495" class="small">設定 / 使用者狀態</text>
+<path d="M 437 340 L 437 190" fill="none" stroke="#84b9ff" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)" stroke-dasharray="5 5"/>
+<text x="452" y="223" class="body">身分 / 權限請求</text>
+<text x="452" y="244" class="body">與服務回應</text>
+<path d="M 563 395 L 646 395" fill="none" stroke="#74d8b6" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 563 499 L 599 499 L 599 587 L 646 587" fill="none" stroke="#74d8b6" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 918 395 L 985 395" fill="none" stroke="#e4bf7f" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<path d="M 918 587 L 985 587" fill="none" stroke="#e4bf7f" stroke-width="2" marker-end="url(#arrow)" marker-start="url(#arrow)"/>
+<text x="31" y="729" class="body">藍色：客戶端與服務互動　·　綠色：通過授權的工具轉送　·　金色：已配置的資源存取</text>
+<text x="31" y="760" class="body">每個 MCP 各自使用私有網路；Agent 不直接連線到下游 MCP 工具端點。</text>
+<text x="31" y="786" class="small">邊界：Agent 原有的宿主檔案、應用程式端點及 Docker 管理存取能力，不在此控管範圍。</text>
+</svg>

nxtlinq_mcp_proxy-0.1.0/docs/downloads/nxtlinq-mcp-preview.txt

@@ -0,0 +1,3 @@
+# Install the current PyPI release.
+--index-url https://pypi.org/simple
+nxtlinq-mcp-proxy[desktop]==0.1.0

nxtlinq_mcp_proxy-0.1.0/docs/en/agents.md

@@ -0,0 +1,71 @@
+# Connect an Agent
+
+nxtlinq MCP Proxy exposes a **Streamable HTTP MCP endpoint with an Authorization
+header**. Choose a client that supports both. The current local deployment uses
+a loopback URL, so the Agent runs on the deployment host.
+
+The initialization wizard offers two connection options:
+
+| Option | What it does |
+| --- | --- |
+| `codex` | Optional automatic configuration for Codex CLI |
+| `other` | Displays connection details for manual client configuration |
+
+The same Proxy, tool permissions, and private MCP deployment are used with either option.
+
+## Manual connection
+
+From the deployment directory, with your environment active:
+
+```sh
+nxtlinq-mcp connection --output connection.json
+```
+
+Copy `url` and `headers.Authorization` into your Agent's MCP configuration.
+Keep this file private. The command refuses to overwrite an existing file;
+use a new filename after a restart and update the client with the new credential.
+Complete Setup before calling tools.
+
+## Optional: automatic Codex configuration
+
+Codex is currently the provided automatic integration. To use it, install Codex
+CLI and verify `codex --version` in the terminal running the wizard, then select
+`codex` during `init`.
+
+The wizard adds the MCP connection while preserving existing model and other MCP
+settings. Start a new session with your usual command:
+
+```sh
+codex
+```
+
+For an already-running deployment, automatic configuration is also available via:
+
+```sh
+nxtlinq-mcp configure-codex
+```
+
+The Proxy performs the same authorization checks regardless of client approval
+settings. Approval inside the Agent does not grant nxtlinq permission.
+
+## Change the connection option
+
+From the existing deployment directory, run:
+
+```sh
+nxtlinq-mcp init .
+```
+
+Select `other` for manual configuration or `codex` for automatic configuration.
+Adding MCPs and syncing tools use the saved choice. Existing client connections
+remain until you remove them in that client.
+
+## Troubleshoot optional Codex configuration
+
+If Codex CLI is not found, install it and confirm `codex --version` works in the
+terminal running the wizard. From the existing deployment directory, run
+`nxtlinq-mcp init .` to retry. You can also choose manual configuration with `other`.
+
+If an MCP connection name is already used, run `nxtlinq-mcp init . --advanced`
+from that same directory and choose a different **Codex MCP server name**.
+The wizard preserves the existing connection.

nxtlinq_mcp_proxy-0.1.0/docs/en/architecture.md

@@ -0,0 +1,59 @@
+# Deployment topology
+
+[![nxtlinq MCP Proxy deployment topology](../assets/topology-en.svg)](../assets/topology-en.svg)
+
+Click the diagram to open it at full size. Ports shown are defaults; the wizard
+can choose available ports. The two private networks illustrate separate MCPs.
+
+## Where each component runs
+
+| Component | Location | Purpose |
+| --- | --- | --- |
+| `nxtlinq-mcp` CLI | Deployment host | Install/configure and manage the Docker deployment |
+| Agent and desktop Setup | Deployment host | Request tools and configure permissions |
+| Proxy service | Docker container | Check permissions and forward calls |
+| Each downstream MCP | Separate Docker container | Execute its tools |
+
+Installing the package with uv provides the CLI. `init` or `up` builds and starts
+the container services. The diagram’s `127.0.0.1:8765` and `:8766` addresses are
+**host-mapped endpoints**, not the containers’ internal listening addresses.
+
+## Tool call
+
+1. The Agent connects to the Proxy's Streamable HTTP endpoint with its connection credential.
+2. The Proxy checks the requested tool against the user's nxtlinq permissions.
+3. A denied call returns an error without invoking the downstream tool.
+4. An allowed call goes to the matching MCP on its private network; its result returns through the Proxy.
+
+Only the Proxy exposes the tool endpoint to the Agent. Each downstream MCP has
+its own internal Docker network and no published tool port.
+
+## Setup and service configuration
+
+The operator configures the deployment's service credentials and registers its
+tool catalogue. The user opens `nxtlinq-mcp setup` to complete identity and
+permission settings. Setup connects to the Proxy's separate local settings
+endpoint; the Proxy communicates with nxtlinq services. Service credentials are
+not handed to the Agent.
+
+## Resources used by a downstream MCP
+
+A Filesystem MCP needs an explicitly shared host folder. An API-backed MCP needs
+permitted HTTPS destinations and any credentials required by that API. Outbound HTTPS goes through
+an allowlisted egress proxy. Persistent data needs a configured volume and an MCP
+that writes to it. These are optional settings, not requirements for every MCP.
+
+External account login belongs to the downstream MCP. An OAuth example may add
+a callback-only relay; that relay does not expose its MCP tool endpoint. The
+[GitHub example](authentication.md) documents that additional flow.
+
+## Agent integrations
+
+Any compatible client can use the MCP endpoint and authorization header.
+[Codex automatic configuration](agents.md) is an optional convenience. It does
+not change how authorization or downstream isolation works.
+
+An Agent's own tools and separately accessible files, APIs, or application control
+endpoints remain outside this deployment's authorization boundary. A user with
+Docker administration rights can also change the deployment; Docker access must
+not be treated as part of an untrusted Agent's tool environment.

nxtlinq_mcp_proxy-0.1.0/docs/en/authentication.md

@@ -0,0 +1,52 @@
+# Example: GitHub OAuth
+
+[Choose another example](examples.md)
+
+The GitHub templates expose **`get_me` only**. GitHub authentication
+permits access to your account; nxtlinq Setup separately permits tool execution.
+
+## OAuth browser login
+
+Download the [GitHub OAuth example script](../examples/github_oauth_login.py){ download="github_oauth_login.py" }
+(save the link as `github_oauth_login.py`) into your working directory, beside
+the bundle and deployment directories. This script is specific to the GitHub
+recipe. Complete [installation](quickstart.md) and activate your Proxy environment
+before running it.
+
+```sh
+nxtlinq-mcp pack github-login --template github-oauth
+nxtlinq-mcp init github-tools --bundle github-login
+cd github-tools
+python ../github_oauth_login.py
+nxtlinq-mcp setup
+```
+
+The example script opens GitHub in your local browser and requests `read:user`. Complete
+authorization there, then run `setup` to enable `get_me` and
+[connect your Agent](agents.md). Ask it to identify the authenticated GitHub account.
+
+The browser returns to `http://localhost:8085/callback` to finish login.
+Port 8085 must be free. This address accepts login callbacks only; the backend's
+tool port remains private. One GitHub OAuth
+backend is supported per deployment, and concurrent deployments cannot share
+that callback port. The browser must run on the deployment host.
+
+Waiting expires after four minutes; the deployment and callback remain running.
+Run the example script again to check the result or obtain a fresh authorization attempt.
+The original MCP keeps OAuth tokens in memory, so backend recreation requires
+another login. Stopping containers does not revoke the app in your GitHub account.
+
+This helper supports only the GitHub OAuth example backend. For other MCPs,
+follow their authentication requirements when configuring credentials and
+allowed API destinations. The GitHub template allows `github.com` and
+`api.github.com` automatically.
+
+Sources: [GitHub account endpoint](https://docs.github.com/en/rest/users/users#get-the-authenticated-user),
+[original MCP OAuth implementation guide](https://github.com/github/github-mcp-server/blob/v1.12.2/docs/oauth-login.md).
+
+## Callback troubleshooting
+
+Keep the deployment running during browser consent. If the callback is refused,
+check that port 8085 is available and the browser runs on the deployment host.
+Rerun the example script to start a fresh attempt; a URL from a previous container
+cannot resume a new login. This is separate from `nxtlinq-mcp setup`.