project-mcp 0.1.0__tar.gz

project_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: project-mcp
+Version: 0.1.0
+Summary: Expose one local project as a token-protected MCP server for ChatGPT.
+Requires-Dist: fastapi>=0.138.1
+Requires-Dist: mcp[cli]>=1.28,<2
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.8
+Requires-Dist: uvicorn[standard]>=0.49.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Project MCP
+
+Expose one local project as a token-protected MCP server for ChatGPT.
+
+Project MCP is intentionally small:
+
+- one local project root
+- one fixed project token
+- one Streamable HTTP MCP endpoint at `/mcp`
+- Cloudflare quick tunnel for public HTTPS access
+- no login, no hosted relay, no ChatGPT widget UI
+
+## Quick Start
+
+Run without installing:
+
+```bash
+uvx project-mcp setup --root .
+uvx project-mcp start
+```
+
+Or install as a persistent tool:
+
+```bash
+uv tool install project-mcp
+project-mcp setup --root .
+project-mcp start
+```
+
+`start` prints a ChatGPT Server URL like:
+
+```text
+https://example.trycloudflare.com/mcp?project_mcp_token=pmcp_...
+```
+
+In ChatGPT Developer Mode, create an app/connector with:
+
+```text
+Connection: Server URL
+Authentication: None / No Authentication
+```
+
+## Commands
+
+```bash
+project-mcp setup --root . --port 8080
+project-mcp start --root .
+project-mcp start --read-only
+project-mcp start --no-bash
+project-mcp doctor
+project-mcp token rotate
+project-mcp settings show
+```
+
+Profiles are stored outside the repository:
+
+```text
+~/.project-mcp/workspaces/<sha256-realpath>.json
+```
+
+The token is fixed per device and project root until you rotate it.
+
+## Tools
+
+Project MCP exposes:
+
+- `server_config`
+- `workspace_info`
+- `tree`
+- `search`
+- `read_file`
+- `write_file`
+- `edit_file`
+- `show_changes`
+- `run_check`
+
+`--read-only` hides `write_file` and `edit_file`. `--no-bash` hides `run_check`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+uv build
+uv publish
+```

project_mcp-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Project MCP
+
+Expose one local project as a token-protected MCP server for ChatGPT.
+
+Project MCP is intentionally small:
+
+- one local project root
+- one fixed project token
+- one Streamable HTTP MCP endpoint at `/mcp`
+- Cloudflare quick tunnel for public HTTPS access
+- no login, no hosted relay, no ChatGPT widget UI
+
+## Quick Start
+
+Run without installing:
+
+```bash
+uvx project-mcp setup --root .
+uvx project-mcp start
+```
+
+Or install as a persistent tool:
+
+```bash
+uv tool install project-mcp
+project-mcp setup --root .
+project-mcp start
+```
+
+`start` prints a ChatGPT Server URL like:
+
+```text
+https://example.trycloudflare.com/mcp?project_mcp_token=pmcp_...
+```
+
+In ChatGPT Developer Mode, create an app/connector with:
+
+```text
+Connection: Server URL
+Authentication: None / No Authentication
+```
+
+## Commands
+
+```bash
+project-mcp setup --root . --port 8080
+project-mcp start --root .
+project-mcp start --read-only
+project-mcp start --no-bash
+project-mcp doctor
+project-mcp token rotate
+project-mcp settings show
+```
+
+Profiles are stored outside the repository:
+
+```text
+~/.project-mcp/workspaces/<sha256-realpath>.json
+```
+
+The token is fixed per device and project root until you rotate it.
+
+## Tools
+
+Project MCP exposes:
+
+- `server_config`
+- `workspace_info`
+- `tree`
+- `search`
+- `read_file`
+- `write_file`
+- `edit_file`
+- `show_changes`
+- `run_check`
+
+`--read-only` hides `write_file` and `edit_file`. `--no-bash` hides `run_check`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+uv build
+uv publish
+```

project_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "project-mcp"
+version = "0.1.0"
+description = "Expose one local project as a token-protected MCP server for ChatGPT."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.138.1",
+    "mcp[cli]>=1.28,<2",
+    "pydantic-settings>=2.14.2",
+    "rich>=15.0.0",
+    "typer>=0.26.8",
+    "uvicorn[standard]>=0.49.0",
+]
+
+[project.scripts]
+project-mcp = "project_mcp.cli:app"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.15.20",
+]

project_mcp-0.1.0/src/project_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Project MCP package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

project_mcp-0.1.0/src/project_mcp/app.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+import hmac
+from typing import Any, AsyncIterator
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse, Response
+
+from project_mcp.config import RuntimeConfig, load_runtime_config
+from project_mcp.mcp_server import create_mcp_server
+from project_mcp.profiles import load_profile, profile_as_public_dict
+from project_mcp.security import origin_allowed
+
+
+def _token_from_request(request: Request) -> str | None:
+    authorization = request.headers.get("authorization", "")
+    if authorization.startswith("Bearer "):
+        return authorization.removeprefix("Bearer ").strip()
+    query_token = request.query_params.get("project_mcp_token") or request.query_params.get("token")
+    return query_token
+
+
+def _token_matches(expected: str | None, actual: str | None) -> bool:
+    if not expected:
+        return True
+    if not actual:
+        return False
+    return hmac.compare_digest(expected, actual)
+
+
+def _cors_headers(origin: str | None) -> dict[str, str]:
+    headers = {
+        "Access-Control-Allow-Methods": "GET,POST,DELETE,OPTIONS",
+        "Access-Control-Allow-Headers": "authorization,content-type,mcp-session-id",
+        "Access-Control-Expose-Headers": "Mcp-Session-Id,MCP-Session-Id",
+    }
+    if origin:
+        headers["Access-Control-Allow-Origin"] = origin
+        headers["Vary"] = "Origin"
+    return headers
+
+
+def create_app(config: RuntimeConfig | None = None) -> FastAPI:
+    config = config or load_runtime_config()
+    mcp_app = create_mcp_server(config).streamable_http_app()
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+        async with mcp_app.router.lifespan_context(mcp_app):
+            yield
+
+    app = FastAPI(
+        title="Project MCP",
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+        lifespan=lifespan,
+    )
+
+    @app.middleware("http")
+    async def security_middleware(request: Request, call_next: Any) -> Response:
+        origin = request.headers.get("origin")
+        if not origin_allowed(origin, config.origin_allowlist):
+            return PlainTextResponse("Forbidden origin", status_code=403)
+        if request.method == "OPTIONS":
+            return Response(status_code=204, headers=_cors_headers(origin))
+        if not _token_matches(config.token, _token_from_request(request)):
+            return PlainTextResponse("Unauthorized", status_code=401, headers=_cors_headers(origin))
+        response = await call_next(request)
+        for key, value in _cors_headers(origin).items():
+            response.headers[key] = value
+        return response
+
+    @app.get("/healthz")
+    async def healthz() -> dict[str, object]:
+        return {
+            "ok": True,
+            "name": "Project MCP",
+            "root": str(config.real_root),
+            "port": config.port,
+            "auth_enabled": bool(config.token),
+            "read_only": config.read_only,
+            "bash_enabled": not config.no_bash,
+            "tunnel_mode": config.tunnel_mode,
+        }
+
+    @app.get("/setup", response_class=HTMLResponse)
+    async def setup_page() -> str:
+        return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Project MCP</title>
+  <style>
+    body {{ margin: 0; font: 14px/1.5 system-ui, sans-serif; color: #202123; background: #fff; }}
+    main {{ max-width: 760px; margin: 40px auto; padding: 0 20px; }}
+    code {{ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }}
+    .panel {{ border: 1px solid #e5e5e5; border-radius: 8px; padding: 16px; }}
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Project MCP</h1>
+    <div class="panel">
+      <p><strong>Root:</strong> <code>{config.real_root}</code></p>
+      <p><strong>MCP endpoint:</strong> <code>/mcp</code></p>
+      <p><strong>Auth:</strong> {"token protected" if config.token else "disabled"}</p>
+      <p><strong>Mode:</strong> read_only={config.read_only}, bash_enabled={not config.no_bash}</p>
+    </div>
+  </main>
+</body>
+</html>"""
+
+    @app.get("/admin/profile")
+    async def admin_profile() -> JSONResponse:
+        profile = load_profile(config.real_root)
+        return JSONResponse(
+            {
+                "ok": True,
+                "profile": profile_as_public_dict(profile) if profile else None,
+                "runtime": {
+                    "root": str(config.real_root),
+                    "port": config.port,
+                    "read_only": config.read_only,
+                    "bash_enabled": not config.no_bash,
+                },
+            }
+        )
+
+    app.mount("/", mcp_app)
+    return app
+
+
+app = create_app()

project_mcp-0.1.0/src/project_mcp/cli.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import os
+import queue
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from project_mcp.profiles import (
+    ensure_profile,
+    load_profile,
+    profile_as_public_dict,
+    profile_path,
+    rotate_profile_token,
+)
+
+
+app = typer.Typer(help="Expose one local project as a token-protected MCP server.")
+token_app = typer.Typer(help="Manage project tokens.")
+settings_app = typer.Typer(help="Show project settings.")
+app.add_typer(token_app, name="token")
+app.add_typer(settings_app, name="settings")
+console = Console()
+
+
+def _root_option(value: Path | None) -> Path:
+    return (value or Path.cwd()).expanduser().resolve()
+
+
+def _assert_port_available(host: str, port: int) -> None:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+        except OSError as exc:
+            raise typer.BadParameter(f"{host}:{port} is not available: {exc}") from exc
+
+
+def _health_url(port: int, token: str) -> str:
+    return f"http://127.0.0.1:{port}/healthz?project_mcp_token={token}"
+
+
+def _wait_for_health(port: int, token: str, timeout: float = 20.0) -> None:
+    deadline = time.monotonic() + timeout
+    url = _health_url(port, token)
+    while time.monotonic() < deadline:
+        try:
+            request = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+            with urllib.request.urlopen(request, timeout=1.5) as response:
+                if response.status == 200:
+                    return
+        except (urllib.error.URLError, TimeoutError):
+            time.sleep(0.25)
+    raise RuntimeError(f"Timed out waiting for local server at {url}")
+
+
+def _reader_thread(name: str, stream, output: queue.Queue[tuple[str, str]]) -> threading.Thread:
+    def run() -> None:
+        for line in iter(stream.readline, ""):
+            output.put((name, line.rstrip()))
+
+    thread = threading.Thread(target=run, daemon=True)
+    thread.start()
+    return thread
+
+
+def _wait_for_cloudflare_url(process: subprocess.Popen[str], timeout: float = 60.0) -> str:
+    output: queue.Queue[tuple[str, str]] = queue.Queue()
+    if process.stdout:
+        _reader_thread("stdout", process.stdout, output)
+    if process.stderr:
+        _reader_thread("stderr", process.stderr, output)
+    pattern = re.compile(r"https://[a-zA-Z0-9-]+\.trycloudflare\.com")
+    deadline = time.monotonic() + timeout
+    recent: list[str] = []
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            raise RuntimeError("cloudflared exited before publishing a tunnel URL.")
+        try:
+            _, line = output.get(timeout=0.5)
+        except queue.Empty:
+            continue
+        if line:
+            recent.append(line)
+            recent[:] = recent[-20:]
+            match = pattern.search(line)
+            if match:
+                return match.group(0)
+    tail = "\n".join(recent)
+    raise RuntimeError(f"Timed out waiting for Cloudflare tunnel URL.\n{tail}")
+
+
+def _terminate(process: subprocess.Popen[str] | None) -> None:
+    if not process or process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+
+
+@app.command()
+def setup(
+    root: Path = typer.Option(Path("."), "--root", help="Project root."),
+    port: int = typer.Option(8080, "--port", min=1, max=65535, help="Local HTTP port."),
+) -> None:
+    """Create or update the project profile while keeping its token stable."""
+    real_root = _root_option(root)
+    profile = ensure_profile(real_root, port=port)
+    path = profile_path(real_root)
+    console.print("[bold green]Project MCP profile ready[/bold green]")
+    console.print(f"Root: [cyan]{profile.root}[/cyan]")
+    console.print(f"Port: [cyan]{profile.port}[/cyan]")
+    console.print(f"Profile: [cyan]{path}[/cyan]")
+    console.print("Token: [dim]<fixed project token saved locally>[/dim]")
+
+
+@app.command()
+def start(
+    root: Path = typer.Option(Path("."), "--root", help="Project root."),
+    port: int | None = typer.Option(None, "--port", min=1, max=65535, help="Local HTTP port."),
+    no_bash: bool = typer.Option(False, "--no-bash", help="Hide run_check from MCP clients."),
+    read_only: bool = typer.Option(False, "--read-only", help="Hide write_file and edit_file."),
+) -> None:
+    """Start the local MCP server and expose it through a Cloudflare quick tunnel."""
+    real_root = _root_option(root)
+    profile = ensure_profile(
+        real_root,
+        port=port or (load_profile(real_root).port if load_profile(real_root) else 8080),
+        read_only=read_only,
+        no_bash=no_bash,
+    )
+    token = profile.project_token
+    if not token:
+        raise typer.BadParameter("Public tunnel mode requires a project token.")
+    cloudflared = shutil.which("cloudflared")
+    if not cloudflared:
+        console.print("[bold red]cloudflared was not found on PATH.[/bold red]")
+        console.print("Install it from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/")
+        raise typer.Exit(1)
+
+    _assert_port_available("127.0.0.1", profile.port)
+    env = {
+        **os.environ,
+        "PROJECT_MCP_ROOT": profile.root,
+        "PROJECT_MCP_HOST": "127.0.0.1",
+        "PROJECT_MCP_PORT": str(profile.port),
+        "PROJECT_MCP_TOKEN": token,
+        "PROJECT_MCP_READ_ONLY": "1" if profile.read_only else "0",
+        "PROJECT_MCP_NO_BASH": "1" if profile.no_bash else "0",
+        "PROJECT_MCP_TUNNEL_MODE": "cloudflare",
+    }
+    server: subprocess.Popen[str] | None = None
+    tunnel: subprocess.Popen[str] | None = None
+    try:
+        console.print("[cyan]Starting local MCP server...[/cyan]")
+        server = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "uvicorn",
+                "project_mcp.app:app",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                str(profile.port),
+            ],
+            env=env,
+            text=True,
+        )
+        _wait_for_health(profile.port, token)
+        local_base = f"http://127.0.0.1:{profile.port}"
+        console.print(f"[green]Local MCP ready:[/green] {local_base}/mcp")
+
+        console.print("[cyan]Opening Cloudflare quick tunnel...[/cyan]")
+        tunnel = subprocess.Popen(
+            [cloudflared, "tunnel", "--url", local_base],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        public_base = _wait_for_cloudflare_url(tunnel)
+        server_url = f"{public_base}/mcp?project_mcp_token={token}"
+        console.print("\n[bold green]Project MCP ready[/bold green]")
+        console.print(f"Workspace: [cyan]{profile.root}[/cyan]")
+        console.print(f"Server URL: [bold]{server_url}[/bold]")
+        console.print("ChatGPT App authentication: [bold]None / No Authentication[/bold]")
+        console.print("Press Ctrl-C to stop.")
+        while True:
+            if server.poll() is not None:
+                raise RuntimeError(f"Local MCP server exited with code {server.returncode}.")
+            if tunnel.poll() is not None:
+                raise RuntimeError(f"cloudflared exited with code {tunnel.returncode}.")
+            time.sleep(1)
+    except KeyboardInterrupt:
+        console.print("\nStopping Project MCP...")
+    except Exception as exc:
+        console.print(f"[bold red]Project MCP start failed:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+    finally:
+        _terminate(tunnel)
+        _terminate(server)
+
+
+@app.command()
+def doctor(root: Path = typer.Option(Path("."), "--root", help="Project root.")) -> None:
+    """Check local prerequisites and project profile state."""
+    real_root = _root_option(root)
+    profile = load_profile(real_root)
+    table = Table(title="Project MCP doctor")
+    table.add_column("Check")
+    table.add_column("Status")
+    table.add_column("Detail")
+    table.add_row("Python", "ok", sys.version.split()[0])
+    table.add_row("cloudflared", "ok" if shutil.which("cloudflared") else "missing", shutil.which("cloudflared") or "not found")
+    table.add_row("profile", "ok" if profile else "missing", str(profile_path(real_root)))
+    table.add_row("root", "ok" if real_root.is_dir() else "fail", str(real_root))
+    console.print(table)
+
+
+@token_app.command("rotate")
+def token_rotate(root: Path = typer.Option(Path("."), "--root", help="Project root.")) -> None:
+    """Rotate the fixed project token for this root."""
+    real_root = _root_option(root)
+    rotate_profile_token(real_root)
+    console.print("[bold green]Project token rotated.[/bold green]")
+    console.print("Update the ChatGPT Server URL before reconnecting.")
+
+
+@settings_app.command("show")
+def settings_show(root: Path = typer.Option(Path("."), "--root", help="Project root.")) -> None:
+    """Show the saved profile with the token redacted."""
+    real_root = _root_option(root)
+    profile = load_profile(real_root)
+    if not profile:
+        console.print("[yellow]No profile found. Run project-mcp setup first.[/yellow]")
+        raise typer.Exit(1)
+    console.print_json(data=profile_as_public_dict(profile))
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()