Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"mcpServers": {
"torproxy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--entrypoint",
"torproxy",
"hapheus/torproxy:latest",
"mcp"
]
}
}
}
8 changes: 7 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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" \
Expand Down
23 changes: 23 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down
4 changes: 4 additions & 0 deletions docs/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions server.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
"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"
},
"packages": [
{
"registryType": "oci",
"identifier": "docker.io/hapheus/torproxy:2.7.4",
"identifier": "docker.io/hapheus/torproxy:2.7.5",
"transport": {
"type": "stdio"
},
Expand Down
25 changes: 25 additions & 0 deletions smithery.yaml
Original file line number Diff line number Diff line change
@@ -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: ""
31 changes: 31 additions & 0 deletions tests/unit/test_contracts.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading