PyPI - project-mcp - Versions diffs - 0.1.0__py3-none-any.whl - Mend

project-mcp 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

project_mcp/__init__.py +5 -0
project_mcp/app.py +136 -0
project_mcp/cli.py +258 -0
project_mcp/config.py +95 -0
project_mcp/mcp_server.py +122 -0
project_mcp/profiles.py +106 -0
project_mcp/security.py +96 -0
project_mcp/workspace.py +392 -0
project_mcp-0.1.0.dist-info/METADATA +100 -0
project_mcp-0.1.0.dist-info/RECORD +12 -0
project_mcp-0.1.0.dist-info/WHEEL +4 -0
project_mcp-0.1.0.dist-info/entry_points.txt +3 -0

project_mcp/__init__.py ADDED Viewed

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

project_mcp/app.py ADDED Viewed

@@ -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/cli.py ADDED Viewed

@@ -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()

project_mcp/config.py ADDED Viewed

@@ -0,0 +1,95 @@
+from __future__ import annotations
+import os
+from pathlib import Path
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+DEFAULT_BLOCKED_GLOBS = (
+    ".git",
+    ".git/*",
+    "**/.git/*",
+    ".env",
+    ".env.*",
+    "**/.env",
+    "**/.env.*",
+    "*.pem",
+    "*.key",
+    "**/*.pem",
+    "**/*.key",
+    ".ssh",
+    ".ssh/*",
+    "**/.ssh/*",
+    "id_rsa",
+    "id_rsa.*",
+    "id_ed25519",
+    "id_ed25519.*",
+    "node_modules",
+    "node_modules/*",
+    "**/node_modules/*",
+    "dist",
+    "dist/*",
+    "**/dist/*",
+    "build",
+    "build/*",
+    "**/build/*",
+    ".next",
+    ".next/*",
+    "**/.next/*",
+    "coverage",
+    "coverage/*",
+    "**/coverage/*",
+    ".cache",
+    ".cache/*",
+    "**/.cache/*",
+    "__pycache__",
+    "__pycache__/*",
+    "**/__pycache__/*",
+)
+def project_home() -> Path:
+    raw = os.environ.get("PROJECT_MCP_HOME")
+    return Path(raw).expanduser() if raw else Path.home() / ".project-mcp"
+class RuntimeConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="PROJECT_MCP_", extra="ignore")
+    root: Path = Field(default_factory=Path.cwd)
+    host: str = "127.0.0.1"
+    port: int = 8080
+    token: str | None = None
+    read_only: bool = False
+    no_bash: bool = False
+    tunnel_mode: str = "cloudflare"
+    max_read_bytes: int = 180_000
+    max_write_bytes: int = 1_000_000
+    max_output_bytes: int = 120_000
+    max_search_results: int = 200
+    blocked_globs: str = ""
+    allowed_origins: str = "https://chatgpt.com,https://chat.openai.com"
+    @property
+    def real_root(self) -> Path:
+        root = self.root.expanduser().resolve()
+        if not root.exists():
+            raise ValueError(f"Project root does not exist: {root}")
+        if not root.is_dir():
+            raise ValueError(f"Project root is not a directory: {root}")
+        return root
+    @property
+    def all_blocked_globs(self) -> tuple[str, ...]:
+        extra = tuple(part.strip() for part in self.blocked_globs.split(",") if part.strip())
+        return (*DEFAULT_BLOCKED_GLOBS, *extra)
+    @property
+    def origin_allowlist(self) -> tuple[str, ...]:
+        return tuple(part.strip().rstrip("/") for part in self.allowed_origins.split(",") if part.strip())
+def load_runtime_config() -> RuntimeConfig:
+    return RuntimeConfig()

project_mcp/mcp_server.py ADDED Viewed

@@ -0,0 +1,122 @@
+from __future__ import annotations
+from typing import Any
+from mcp.server.fastmcp import FastMCP
+from project_mcp.config import RuntimeConfig
+from project_mcp import workspace as ops
+def create_mcp_server(config: RuntimeConfig) -> FastMCP:
+    instructions = "\n".join(
+        [
+            "Project MCP exposes one local project as token-protected MCP tools.",
+            "Start with workspace_info, then use tree/search/read_file for inspection.",
+            "Use write_file/edit_file only when the user asks for edits.",
+            "Use run_check only for test, lint, typecheck, build, or similar verification.",
+        ]
+    )
+    server = FastMCP(
+        "Project MCP",
+        instructions=instructions,
+        streamable_http_path="/mcp",
+        json_response=True,
+    )
+    @server.tool(structured_output=True)
+    def server_config() -> dict[str, Any]:
+        """Show safe Project MCP configuration without revealing the project token."""
+        return {
+            "root": str(config.real_root),
+            "host": config.host,
+            "port": config.port,
+            "auth_enabled": bool(config.token),
+            "read_only": config.read_only,
+            "bash_enabled": not config.no_bash,
+            "tunnel_mode": config.tunnel_mode,
+            "max_read_bytes": config.max_read_bytes,
+            "max_write_bytes": config.max_write_bytes,
+            "max_output_bytes": config.max_output_bytes,
+            "max_search_results": config.max_search_results,
+            "blocked_globs": list(config.all_blocked_globs),
+        }
+    @server.tool(structured_output=True)
+    def workspace_info() -> dict[str, Any]:
+        """Return the active project root and runtime modes."""
+        return ops.workspace_info(config)
+    @server.tool(structured_output=True)
+    def tree(
+        path: str = ".",
+        max_depth: int = 3,
+        include_hidden: bool = False,
+        max_entries: int = 800,
+    ) -> dict[str, Any]:
+        """List files and directories inside the project root."""
+        return ops.tree(config, path, max_depth, include_hidden, max_entries)
+    @server.tool(structured_output=True)
+    def search(
+        query: str,
+        path: str = ".",
+        regex: bool = False,
+        include_hidden: bool = False,
+        max_results: int | None = None,
+    ) -> dict[str, Any]:
+        """Search text files inside the project root."""
+        return ops.search(config, query, path, regex, include_hidden, max_results)
+    @server.tool(structured_output=True)
+    def read_file(
+        path: str,
+        start_line: int = 1,
+        end_line: int | None = None,
+        max_bytes: int | None = None,
+    ) -> dict[str, Any]:
+        """Read a UTF-8 text file with line numbers."""
+        return ops.read_file(config, path, start_line, end_line, max_bytes)
+    if not config.read_only:
+        @server.tool(structured_output=True)
+        def write_file(
+            path: str,
+            content: str,
+            create_dirs: bool = True,
+            overwrite: bool = True,
+        ) -> dict[str, Any]:
+            """Create or overwrite a UTF-8 text file and return a unified diff."""
+            return ops.write_file(config, path, content, create_dirs, overwrite)
+        @server.tool(structured_output=True)
+        def edit_file(
+            path: str,
+            old_text: str,
+            new_text: str,
+            replace_all: bool = False,
+            expected_replacements: int | None = None,
+        ) -> dict[str, Any]:
+            """Perform exact text replacement in a file and return a unified diff."""
+            return ops.edit_file(
+                config, path, old_text, new_text, replace_all, expected_replacements
+            )
+    @server.tool(structured_output=True)
+    def show_changes(include_diff: bool = True) -> dict[str, Any]:
+        """Show git status, diff stats, and optionally the working-tree diff."""
+        return ops.show_changes(config, include_diff)
+    if not config.no_bash:
+        @server.tool(structured_output=True)
+        def run_check(
+            command: str,
+            cwd: str = ".",
+            timeout_ms: int = 30_000,
+        ) -> dict[str, Any]:
+            """Run one safe allowlisted verification command in the project."""
+            return ops.run_check(config, command, cwd, timeout_ms)
+    return server

project_mcp/profiles.py ADDED Viewed

@@ -0,0 +1,106 @@
+from __future__ import annotations
+import hashlib
+import json
+import secrets
+from pathlib import Path
+from pydantic import BaseModel, Field
+from project_mcp.config import project_home
+class WorkspaceProfile(BaseModel):
+    root: str
+    port: int = 8080
+    project_token: str = Field(min_length=24)
+    tunnel: str = "cloudflare"
+    read_only: bool = False
+    no_bash: bool = False
+def real_project_root(root: str | Path) -> Path:
+    resolved = Path(root).expanduser().resolve()
+    if not resolved.exists():
+        raise FileNotFoundError(f"Project root does not exist: {resolved}")
+    if not resolved.is_dir():
+        raise NotADirectoryError(f"Project root is not a directory: {resolved}")
+    return resolved
+def generate_project_token() -> str:
+    return "pmcp_" + secrets.token_urlsafe(32)
+def profile_id(root: str | Path) -> str:
+    return hashlib.sha256(str(real_project_root(root)).encode("utf-8")).hexdigest()[:32]
+def workspaces_dir() -> Path:
+    return project_home() / "workspaces"
+def profile_path(root: str | Path) -> Path:
+    return workspaces_dir() / f"{profile_id(root)}.json"
+def load_profile(root: str | Path) -> WorkspaceProfile | None:
+    path = profile_path(root)
+    if not path.exists():
+        return None
+    return WorkspaceProfile.model_validate_json(path.read_text("utf-8"))
+def save_profile(profile: WorkspaceProfile) -> Path:
+    path = profile_path(profile.root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(profile.model_dump_json(indent=2) + "\n", "utf-8")
+    return path
+def ensure_profile(
+    root: str | Path,
+    *,
+    port: int = 8080,
+    read_only: bool | None = None,
+    no_bash: bool | None = None,
+) -> WorkspaceProfile:
+    real_root = real_project_root(root)
+    existing = load_profile(real_root)
+    if existing:
+        changed = False
+        if port and existing.port != port:
+            existing.port = port
+            changed = True
+        if read_only is not None and existing.read_only != read_only:
+            existing.read_only = read_only
+            changed = True
+        if no_bash is not None and existing.no_bash != no_bash:
+            existing.no_bash = no_bash
+            changed = True
+        if changed:
+            save_profile(existing)
+        return existing
+    profile = WorkspaceProfile(
+        root=str(real_root),
+        port=port,
+        project_token=generate_project_token(),
+        read_only=bool(read_only) if read_only is not None else False,
+        no_bash=bool(no_bash) if no_bash is not None else False,
+    )
+    save_profile(profile)
+    return profile
+def rotate_profile_token(root: str | Path) -> WorkspaceProfile:
+    profile = ensure_profile(root)
+    profile.project_token = generate_project_token()
+    save_profile(profile)
+    return profile
+def profile_as_public_dict(profile: WorkspaceProfile) -> dict[str, object]:
+    data = json.loads(profile.model_dump_json())
+    data["project_token"] = "<redacted>"
+    return data

project_mcp/security.py ADDED Viewed

@@ -0,0 +1,96 @@
+from __future__ import annotations
+import fnmatch
+from pathlib import Path
+class ProjectMcpError(Exception):
+    """User-safe error surfaced through MCP tool results."""
+def posix_rel(path: Path) -> str:
+    return path.as_posix() or "."
+def is_subpath(child: Path, parent: Path) -> bool:
+    try:
+        child.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+class PathGuard:
+    def __init__(self, root: Path, blocked_globs: tuple[str, ...]):
+        self.root = root.expanduser().resolve()
+        self.blocked_globs = blocked_globs
+    def display_path(self, path: Path) -> str:
+        try:
+            rel = path.relative_to(self.root)
+        except ValueError:
+            rel = path
+        text = rel.as_posix()
+        return text or "."
+    def is_blocked(self, rel_path: str) -> bool:
+        rel = rel_path.replace("\\", "/").lstrip("./")
+        if not rel or rel == ".":
+            return False
+        name = rel.rsplit("/", 1)[-1]
+        return any(
+            fnmatch.fnmatchcase(rel, pattern) or fnmatch.fnmatchcase(name, pattern)
+            for pattern in self.blocked_globs
+        )
+    def assert_not_blocked(self, rel_path: str) -> None:
+        if self.is_blocked(rel_path):
+            raise ProjectMcpError(f"Path is blocked by safety rules: {rel_path}")
+    def resolve(self, input_path: str | Path = ".", *, for_write: bool = False) -> tuple[Path, str]:
+        raw = Path(input_path).expanduser()
+        candidate = raw if raw.is_absolute() else self.root / raw
+        abs_path = candidate.resolve(strict=False)
+        if not is_subpath(abs_path, self.root):
+            raise ProjectMcpError(f"Path escapes project root: {input_path}")
+        rel_path = self.display_path(abs_path)
+        self.assert_not_blocked(rel_path)
+        if abs_path.exists():
+            real_target = abs_path.resolve()
+            if not is_subpath(real_target, self.root):
+                raise ProjectMcpError(f"Path resolves outside project root: {input_path}")
+            self.assert_not_blocked(self.display_path(real_target))
+        if for_write:
+            parent = abs_path.parent
+            while not parent.exists() and parent != parent.parent:
+                parent = parent.parent
+            real_parent = parent.resolve()
+            if not is_subpath(real_parent, self.root):
+                raise ProjectMcpError(f"Write path resolves outside project root: {input_path}")
+            self.assert_not_blocked(self.display_path(real_parent))
+        return abs_path, rel_path
+    def assert_text_file(self, path: Path, max_bytes: int) -> None:
+        if not path.is_file():
+            raise ProjectMcpError(f"Not a file: {self.display_path(path)}")
+        size = path.stat().st_size
+        if size > max_bytes:
+            raise ProjectMcpError(f"File is too large ({size} bytes). Limit: {max_bytes} bytes.")
+        with path.open("rb") as handle:
+            sample = handle.read(min(4096, size))
+        if b"\0" in sample:
+            raise ProjectMcpError("Refusing to read binary file.")
+def origin_allowed(origin: str | None, allowlist: tuple[str, ...]) -> bool:
+    if not origin:
+        return True
+    normalized = origin.rstrip("/")
+    if normalized.startswith("http://127.0.0.1") or normalized.startswith("http://localhost"):
+        return True
+    return normalized in allowlist

project_mcp/workspace.py ADDED Viewed

@@ -0,0 +1,392 @@
+from __future__ import annotations
+import difflib
+import os
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Iterable
+from project_mcp.config import RuntimeConfig
+from project_mcp.security import PathGuard, ProjectMcpError
+def make_guard(config: RuntimeConfig) -> PathGuard:
+    return PathGuard(config.real_root, config.all_blocked_globs)
+def trim_text(text: str, max_bytes: int) -> tuple[str, bool]:
+    data = text.encode("utf-8", errors="replace")
+    if len(data) <= max_bytes:
+        return text, False
+    return data[:max_bytes].decode("utf-8", errors="replace") + "\n...[truncated]", True
+def unified_diff(old: str, new: str, rel_path: str, max_bytes: int = 80_000) -> dict[str, object]:
+    if old == new:
+        return {"changed": False, "additions": 0, "deletions": 0, "diff": f"No changes in {rel_path}."}
+    lines = list(
+        difflib.unified_diff(
+            old.splitlines(),
+            new.splitlines(),
+            fromfile=f"a/{rel_path}",
+            tofile=f"b/{rel_path}",
+            lineterm="",
+        )
+    )
+    additions = sum(1 for line in lines if line.startswith("+") and not line.startswith("+++"))
+    deletions = sum(1 for line in lines if line.startswith("-") and not line.startswith("---"))
+    diff, truncated = trim_text("\n".join(lines), max_bytes)
+    if truncated:
+        diff += f"\n...[diff truncated to {max_bytes} bytes]"
+    return {"changed": True, "additions": additions, "deletions": deletions, "diff": diff}
+def workspace_info(config: RuntimeConfig) -> dict[str, object]:
+    root = config.real_root
+    return {
+        "root": str(root),
+        "name": root.name,
+        "read_only": config.read_only,
+        "bash_enabled": not config.no_bash,
+    }
+def tree(
+    config: RuntimeConfig,
+    path: str = ".",
+    max_depth: int = 3,
+    include_hidden: bool = False,
+    max_entries: int = 800,
+) -> dict[str, object]:
+    guard = make_guard(config)
+    target, rel = guard.resolve(path)
+    if not target.is_dir():
+        raise ProjectMcpError(f"Not a directory: {rel}")
+    lines = [rel if rel == "." else f"{rel}/"]
+    entries = 0
+    truncated = False
+    def visible(entry: Path) -> bool:
+        name = entry.name
+        if not include_hidden and name.startswith("."):
+            return False
+        return not guard.is_blocked(guard.display_path(entry.resolve(strict=False)))
+    def walk(directory: Path, prefix: str, depth: int) -> None:
+        nonlocal entries, truncated
+        if depth >= max_depth or truncated:
+            return
+        children = sorted(
+            (child for child in directory.iterdir() if visible(child)),
+            key=lambda item: (not item.is_dir(), item.name.lower()),
+        )
+        for index, child in enumerate(children):
+            if entries >= max_entries:
+                truncated = True
+                return
+            last = index == len(children) - 1
+            branch = "`-- " if last else "|-- "
+            child_prefix = "    " if last else "|   "
+            suffix = "/" if child.is_dir() else ""
+            lines.append(f"{prefix}{branch}{child.name}{suffix}")
+            entries += 1
+            if child.is_dir():
+                walk(child, prefix + child_prefix, depth + 1)
+    walk(target, "", 0)
+    if truncated:
+        lines.append(f"...[tree truncated after {entries} entries]")
+    return {"path": rel, "entries": entries, "truncated": truncated, "tree": "\n".join(lines)}
+def iter_files(guard: PathGuard, root: Path, include_hidden: bool = False) -> Iterable[Path]:
+    for current, dirs, files in os.walk(root):
+        current_path = Path(current)
+        filtered_dirs = []
+        for dirname in dirs:
+            candidate = current_path / dirname
+            rel = guard.display_path(candidate.resolve(strict=False))
+            if (not include_hidden and dirname.startswith(".")) or guard.is_blocked(rel):
+                continue
+            filtered_dirs.append(dirname)
+        dirs[:] = filtered_dirs
+        for filename in files:
+            candidate = current_path / filename
+            rel = guard.display_path(candidate.resolve(strict=False))
+            if (not include_hidden and filename.startswith(".")) or guard.is_blocked(rel):
+                continue
+            yield candidate
+def search(
+    config: RuntimeConfig,
+    query: str,
+    path: str = ".",
+    regex: bool = False,
+    include_hidden: bool = False,
+    max_results: int | None = None,
+) -> dict[str, object]:
+    if not query:
+        raise ProjectMcpError("query is required.")
+    guard = make_guard(config)
+    target, rel = guard.resolve(path)
+    max_results = max(1, min(max_results or config.max_search_results, config.max_search_results))
+    pattern = re.compile(query) if regex else None
+    results: list[dict[str, object]] = []
+    files = [target] if target.is_file() else iter_files(guard, target, include_hidden)
+    for file_path in files:
+        if len(results) >= max_results:
+            break
+        try:
+            guard.assert_text_file(file_path, config.max_read_bytes)
+            lines = file_path.read_text("utf-8", errors="replace").splitlines()
+        except (OSError, UnicodeError, ProjectMcpError):
+            continue
+        for line_no, line in enumerate(lines, start=1):
+            matched = bool(pattern.search(line)) if pattern else query in line
+            if matched:
+                results.append(
+                    {"path": guard.display_path(file_path), "line": line_no, "text": line[:500]}
+                )
+                if len(results) >= max_results:
+                    break
+    return {"path": rel, "query": query, "regex": regex, "count": len(results), "results": results}
+def read_file(
+    config: RuntimeConfig,
+    path: str,
+    start_line: int = 1,
+    end_line: int | None = None,
+    max_bytes: int | None = None,
+) -> dict[str, object]:
+    guard = make_guard(config)
+    target, rel = guard.resolve(path)
+    limit = min(max_bytes or config.max_read_bytes, config.max_read_bytes)
+    guard.assert_text_file(target, limit)
+    text = target.read_text("utf-8", errors="replace")
+    lines = text.splitlines()
+    total = len(lines)
+    start = max(1, start_line)
+    end = min(total, end_line or total)
+    if end < start:
+        raise ProjectMcpError("end_line must be >= start_line.")
+    selected = lines[start - 1 : end]
+    width = len(str(end))
+    numbered = "\n".join(f"{idx:>{width}} | {line}" for idx, line in enumerate(selected, start))
+    return {
+        "path": rel,
+        "start_line": start,
+        "end_line": end,
+        "total_lines": total,
+        "bytes": target.stat().st_size,
+        "truncated": start > 1 or end < total,
+        "text": numbered,
+    }
+def write_file(
+    config: RuntimeConfig,
+    path: str,
+    content: str,
+    create_dirs: bool = True,
+    overwrite: bool = True,
+) -> dict[str, object]:
+    if config.read_only:
+        raise ProjectMcpError("write_file is disabled because PROJECT_MCP_READ_ONLY=1.")
+    guard = make_guard(config)
+    target, rel = guard.resolve(path, for_write=True)
+    data = content.encode("utf-8")
+    if len(data) > config.max_write_bytes:
+        raise ProjectMcpError(
+            f"Write content is too large ({len(data)} bytes). Limit: {config.max_write_bytes} bytes."
+        )
+    existed = target.exists()
+    old = ""
+    if existed:
+        guard.assert_text_file(target, max(config.max_read_bytes, config.max_write_bytes))
+        if not overwrite:
+            raise ProjectMcpError(f"File already exists and overwrite=false: {rel}")
+        old = target.read_text("utf-8", errors="replace")
+    if create_dirs:
+        target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, "utf-8")
+    diff = unified_diff(old, content, rel)
+    return {"path": rel, "bytes": len(data), "existed": existed, **diff}
+def edit_file(
+    config: RuntimeConfig,
+    path: str,
+    old_text: str,
+    new_text: str,
+    replace_all: bool = False,
+    expected_replacements: int | None = None,
+) -> dict[str, object]:
+    if config.read_only:
+        raise ProjectMcpError("edit_file is disabled because PROJECT_MCP_READ_ONLY=1.")
+    if not old_text:
+        raise ProjectMcpError("old_text must not be empty.")
+    guard = make_guard(config)
+    target, rel = guard.resolve(path, for_write=True)
+    guard.assert_text_file(target, max(config.max_read_bytes, config.max_write_bytes))
+    before = target.read_text("utf-8", errors="replace")
+    occurrences = before.count(old_text)
+    if occurrences == 0:
+        raise ProjectMcpError(f"old_text was not found in {rel}.")
+    if not replace_all and occurrences != 1:
+        raise ProjectMcpError(
+            f"old_text matched {occurrences} times. Use a more specific snippet or replace_all=true."
+        )
+    replacements = occurrences if replace_all else 1
+    if expected_replacements is not None and expected_replacements != replacements:
+        raise ProjectMcpError(
+            f"Expected {expected_replacements} replacements but would perform {replacements}."
+        )
+    after = before.replace(old_text, new_text, -1 if replace_all else 1)
+    after_bytes = len(after.encode("utf-8"))
+    if after_bytes > config.max_write_bytes:
+        raise ProjectMcpError(
+            f"Edited file would be too large ({after_bytes} bytes). Limit: {config.max_write_bytes} bytes."
+        )
+    target.write_text(after, "utf-8")
+    diff = unified_diff(before, after, rel)
+    return {"path": rel, "replacements": replacements, "bytes": after_bytes, **diff}
+def run_git(config: RuntimeConfig, args: list[str], timeout: int = 15) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=config.real_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        timeout=timeout,
+        check=False,
+    )
+    output, _ = trim_text(result.stdout.strip() or "(no output)", config.max_output_bytes)
+    return output
+def show_changes(config: RuntimeConfig, include_diff: bool = True) -> dict[str, object]:
+    if not shutil.which("git"):
+        return {"git_available": False, "status": "git not found", "diff": ""}
+    status = run_git(config, ["status", "--short"])
+    stat = run_git(config, ["diff", "--stat"])
+    diff = run_git(config, ["diff", "--"], timeout=30) if include_diff else ""
+    return {"git_available": True, "status": status, "stat": stat, "diff": diff}
+SAFE_ALLOWED_PREFIXES = (
+    "pytest",
+    "python -m pytest",
+    "python3 -m pytest",
+    "uv run pytest",
+    "npm test",
+    "npm run test",
+    "npm run lint",
+    "npm run typecheck",
+    "npm run build",
+    "npm run check",
+    "pnpm test",
+    "pnpm run test",
+    "pnpm run lint",
+    "pnpm run typecheck",
+    "pnpm run build",
+    "pnpm run check",
+    "yarn test",
+    "yarn run test",
+    "yarn run lint",
+    "yarn run typecheck",
+    "yarn run build",
+    "yarn run check",
+    "bun test",
+    "bun run test",
+    "bun run lint",
+    "bun run typecheck",
+    "bun run build",
+    "go test",
+    "cargo test",
+    "cargo check",
+    "cargo clippy",
+    "ruff check",
+    "uv run ruff check",
+)
+SAFE_BLOCKED_PATTERNS = (
+    r"(^|\s)(rm|mv|cp|dd|sudo|chmod|chown|kill|pkill|curl|wget|ssh|scp|rsync|docker|podman)\s+",
+    r"(^|\s)git\s+(push|reset|clean|checkout|switch|restore)\b",
+    r"(^|\s)(npm|pnpm|yarn)\s+publish\b",
+    r"(^|\s)(cat|grep|rg|head|tail|sed|perl)\s+",
+    r"[;&|<>`]",
+    r"\$\(",
+    r"\n",
+    r"(^|\s)(/|~(?:/|\s|$))",
+    r"(^|\s)\.\.(?:/|\s|$)",
+    r"(^|[\s:])(?:\.env|\.git|node_modules|\.ssh)(?:[/\s:]|$)",
+)
+def compact_command(command: str) -> str:
+    return " ".join(command.strip().split())
+def assert_safe_command(command: str) -> str:
+    normalized = compact_command(command)
+    if not normalized:
+        raise ProjectMcpError("command is required.")
+    for pattern in SAFE_BLOCKED_PATTERNS:
+        if re.search(pattern, normalized):
+            raise ProjectMcpError(f"Command is blocked in safe mode: {normalized}")
+    if not any(normalized == prefix or normalized.startswith(prefix + " ") for prefix in SAFE_ALLOWED_PREFIXES):
+        raise ProjectMcpError(f"Command is not in the safe allowlist: {normalized}")
+    return normalized
+def run_check(
+    config: RuntimeConfig,
+    command: str,
+    cwd: str = ".",
+    timeout_ms: int = 30_000,
+) -> dict[str, object]:
+    if config.no_bash:
+        raise ProjectMcpError("run_check is disabled because PROJECT_MCP_NO_BASH=1.")
+    normalized = assert_safe_command(command)
+    guard = make_guard(config)
+    cwd_path, cwd_rel = guard.resolve(cwd)
+    if not cwd_path.is_dir():
+        raise ProjectMcpError(f"cwd is not a directory: {cwd_rel}")
+    started = time.time()
+    result = subprocess.run(
+        ["/bin/bash", "-lc", normalized],
+        cwd=cwd_path,
+        env={
+            "PATH": os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
+            "HOME": os.environ.get("HOME", ""),
+            "TERM": "dumb",
+            "NO_COLOR": "1",
+            "CI": "1",
+        },
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=max(1, min(timeout_ms // 1000, 180)),
+        check=False,
+    )
+    stdout, stdout_truncated = trim_text(result.stdout, config.max_output_bytes)
+    stderr, stderr_truncated = trim_text(result.stderr, config.max_output_bytes)
+    return {
+        "command": normalized,
+        "cwd": cwd_rel,
+        "exit_code": result.returncode,
+        "duration_ms": int((time.time() - started) * 1000),
+        "stdout": stdout,
+        "stderr": stderr,
+        "truncated": stdout_truncated or stderr_truncated,
+    }

project_mcp-0.1.0.dist-info/METADATA ADDED Viewed

@@ -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.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,12 @@
+project_mcp/__init__.py,sha256=XQWQ1z0PB7abTrG_1VYq7fRlJm0zFDXwg7TreJOX24k,77
+project_mcp/app.py,sha256=bUNDk7l7yK9OtzDYZzF5PdtoITe-NlvjAivoHJ5cpw0,4815
+project_mcp/cli.py,sha256=ea93hIs-PNMgCRZhEY3--mYtoaPQBnDv9YWhfKFB6-o,9570
+project_mcp/config.py,sha256=i70Y_-BRNNXFSSIrXbF6Vt1e-MFmKYC8PkiblY74SKE,2333
+project_mcp/mcp_server.py,sha256=XmjsbPrO7vD5yVudU1oiWIb5n5IpLKJEK_KmrD52cjA,4360
+project_mcp/profiles.py,sha256=RuyXOhtHj0qycYI6IiBdhMcSK4yQFQAAxYlbvhCdb1U,3001
+project_mcp/security.py,sha256=87QDhFK-qGZiSsSH4ufIWv5r6TFPqMdUqOxdTKx6XiA,3395
+project_mcp/workspace.py,sha256=LiM_PaeLiEAcgClzRcJuz-3InkQbbjvf00saWN3B1aA,13698
+project_mcp-0.1.0.dist-info/WHEEL,sha256=8ZlpUMJ7mlDirmlHRhDirEx_nPnARrwDjeE92mlk68E,81
+project_mcp-0.1.0.dist-info/entry_points.txt,sha256=Xs0NDw7irn5vTIifA69kyT6wRg-WVoxZkjevk2b4L2g,53
+project_mcp-0.1.0.dist-info/METADATA,sha256=aWIw5_vm0immRQ5Az-Y4Q25kWoqIqGb-Q67SnZF-kqY,1938
+project_mcp-0.1.0.dist-info/RECORD,,

project_mcp-0.1.0.dist-info/WHEEL ADDED Viewed

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.21
+Root-Is-Purelib: true
+Tag: py3-none-any

project_mcp-0.1.0.dist-info/entry_points.txt ADDED Viewed

@@ -0,0 +1,3 @@
+[console_scripts]
+project-mcp = project_mcp.cli:app