diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..9e977ee --- /dev/null +++ b/.mcp.json @@ -0,0 +1,16 @@ +{ + "mcpServers": { + "torproxy": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--entrypoint", + "torproxy", + "hapheus/torproxy:latest", + "mcp" + ] + } + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c5338e..558b7d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.7.5] — 2026-11-11 + +### Added +- **mcp**: Add root-level auto-discovery manifests `.mcp.json` (Cursor & cursor.directory) and `smithery.yaml` (Smithery.ai) for zero-config import and live healthcheck (#143) + ## [2.7.4] — 2026-11-10 ### Fixed @@ -235,7 +240,8 @@ Sprint 1 security & contract correctness release. --- -[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.4...HEAD +[Unreleased]: https://github.com/hapheus/torproxy/compare/v2.7.5...HEAD +[2.7.5]: https://github.com/hapheus/torproxy/compare/v2.7.4...v2.7.5 [2.7.4]: https://github.com/hapheus/torproxy/compare/v2.7.3...v2.7.4 [2.7.3]: https://github.com/hapheus/torproxy/compare/v2.7.2...v2.7.3 [2.7.2]: https://github.com/hapheus/torproxy/compare/v2.7.1...v2.7.2 diff --git a/README.md b/README.md index 6210057..6371c91 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,14 @@ Connect via HTTP/SSE: } ``` +Or use the root-level `.mcp.json` manifest auto-detected by Cursor and [cursor.directory](https://cursor.directory) on workspace open. + +### Smithery.ai Integration (`smithery.yaml`) +Install directly with zero configuration via [Smithery.ai](https://smithery.ai): +```bash +npx -y @smithery/cli install hapheus/torproxy --client claude +``` + ### Key Tools Available to Agents - `torproxy_fetch`: **Zero-config fetch** — execute HTTP/HTTPS or `.onion` requests strictly routed through Tor (no local curl or host proxy setup needed). - `torproxy_status`: Retrieve live bootstrap progress, egress IP, and GeoIP metadata. diff --git a/docker/Dockerfile b/docker/Dockerfile index f2abe07..93ac9ae 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -7,7 +7,7 @@ ARG PYTHON_VERSION=3.14 LABEL org.opencontainers.image.title="torproxy" \ org.opencontainers.image.description="A minimal HTTP proxy routed through Tor" \ - org.opencontainers.image.version="2.7.4" \ + org.opencontainers.image.version="2.7.5" \ org.opencontainers.image.licenses="MIT" \ org.opencontainers.image.source="https://github.com/hapheus/torproxy" \ org.opencontainers.image.url="https://github.com/hapheus/torproxy" \ diff --git a/docs/mcp.md b/docs/mcp.md index f36d878..6956ab5 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -92,6 +92,29 @@ Connect Claude Desktop to your running `torproxy` container over Stdio without e } ``` +#### Option C: Zero-Config Project Auto-Discovery (`.mcp.json`) +The repository includes a root-level `.mcp.json` automatically detected by Cursor and [cursor.directory](https://cursor.directory) for on-demand execution: +```json +{ + "mcpServers": { + "torproxy": { + "command": "docker", + "args": ["run", "-i", "--rm", "--entrypoint", "torproxy", "hapheus/torproxy:latest", "mcp"] + } + } +} +``` + +--- + +### Smithery.ai Integration (`smithery.yaml`) + +`torproxy` includes a root-level `smithery.yaml` configuration allowing zero-config import, automated live-healthcheck validation, and one-click installation via [Smithery.ai](https://smithery.ai): + +```bash +npx -y @smithery/cli install hapheus/torproxy --client claude +``` + --- ### Antigravity & Gemini CLI (`settings.json`) diff --git a/docs/releases.md b/docs/releases.md index b388578..289683e 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -91,6 +91,10 @@ If an upgraded image exhibits unexpected behavior in your environment: ## 6. Release Notes +### 2.7.5 (MCP Auto-Discovery Manifests for Cursor and Smithery.ai) + +- **Cursor & Smithery.ai Manifests (#143):** Added root-level auto-discovery manifest files `.mcp.json` and `smithery.yaml`, enabling zero-config integration in Cursor / cursor.directory and automated live-healthcheck evaluation on Smithery.ai. + ### 2.7.4 (MCP Registry OCI label requirement and live bootstrap resilience) - **MCP Registry OCI Label & Annotations (#141):** Added `LABEL io.modelcontextprotocol.server.name="io.github.hapheus/torproxy"` to `docker/Dockerfile` and OCI index/manifest annotations in `publish-dockerhub.yml`, satisfying the official MCP Registry verification requirement for OCI container packages. diff --git a/pyproject.toml b/pyproject.toml index 362d44c..66004fc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "torproxy" -version = "2.7.4" +version = "2.7.5" description = "A minimal HTTP and SOCKS5 proxy routed through the Tor network with local REST control API" readme = "README.md" requires-python = ">=3.10" diff --git a/server.json b/server.json index 571c39d..64de9ff 100644 --- a/server.json +++ b/server.json @@ -3,7 +3,7 @@ "name": "io.github.hapheus/torproxy", "title": "torproxy", "description": "Tor HTTP and SOCKS5 proxy with REST API and built-in MCP server.", - "version": "2.7.4", + "version": "2.7.5", "repository": { "url": "https://github.com/hapheus/torproxy", "source": "github" @@ -11,7 +11,7 @@ "packages": [ { "registryType": "oci", - "identifier": "docker.io/hapheus/torproxy:2.7.4", + "identifier": "docker.io/hapheus/torproxy:2.7.5", "transport": { "type": "stdio" }, diff --git a/smithery.yaml b/smithery.yaml new file mode 100644 index 0000000..e945744 --- /dev/null +++ b/smithery.yaml @@ -0,0 +1,25 @@ +# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml +startCommand: + type: stdio + configSchema: + type: object + properties: + torproxyApiToken: + type: string + description: "Optional secret token for authenticating REST and MCP requests." + commandFunction: |- + (config) => ({ + command: "docker", + args: [ + "run", + "-i", + "--rm", + "--entrypoint", + "torproxy", + ...(config?.torproxyApiToken ? ["-e", `TORPROXY_API_TOKEN=${config.torproxyApiToken}`] : []), + "hapheus/torproxy:latest", + "mcp" + ] + }) + exampleConfig: + torproxyApiToken: "" diff --git a/tests/unit/test_contracts.py b/tests/unit/test_contracts.py index ab63cae..a17198b 100644 --- a/tests/unit/test_contracts.py +++ b/tests/unit/test_contracts.py @@ -328,6 +328,37 @@ def test_version_single_source_of_truth(self): if pkg.get("registryType") == "oci": assert pkg["identifier"].endswith(f":{project_version}") + def test_mcp_auto_discovery_manifests_contract(self): + # ISSUE-143: verify .mcp.json and smithery.yaml auto-discovery manifests + mcp_json_path = os.path.join(REPO_ROOT, ".mcp.json") + assert os.path.exists(mcp_json_path), ".mcp.json must exist in repository root" + with open(mcp_json_path, "r", encoding="utf-8") as f: + mcp_data = json.load(f) + assert "mcpServers" in mcp_data + assert "torproxy" in mcp_data["mcpServers"] + server_cfg = mcp_data["mcpServers"]["torproxy"] + assert server_cfg["command"] == "docker" + assert server_cfg["args"] == [ + "run", + "-i", + "--rm", + "--entrypoint", + "torproxy", + "hapheus/torproxy:latest", + "mcp", + ] + + smithery_path = os.path.join(REPO_ROOT, "smithery.yaml") + assert os.path.exists(smithery_path), "smithery.yaml must exist in repository root" + with open(smithery_path, "r", encoding="utf-8") as f: + smithery_content = f.read() + assert "startCommand:" in smithery_content + assert "type: stdio" in smithery_content + assert "configSchema:" in smithery_content + assert "commandFunction:" in smithery_content + assert "hapheus/torproxy:latest" in smithery_content + assert "--entrypoint" in smithery_content + def test_compiled_artifacts_ignored_everywhere(self): # ISSUE-16: no .pyc/__pycache__ may leak into the repo or the image. gitignore_path = os.path.join(REPO_ROOT, ".gitignore") diff --git a/uv.lock b/uv.lock index 77da3a9..380bc10 100644 --- a/uv.lock +++ b/uv.lock @@ -842,7 +842,7 @@ wheels = [ [[package]] name = "torproxy" -version = "2.7.4" +version = "2.7.5" source = { editable = "." } [package.optional-dependencies]