letswork 0.1.0__tar.gz

letswork-0.1.0/.claude/settings.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/saicharanrajoju/Desktop/LetsWork diff --name-only HEAD)",
+      "Bash(git -C /Users/saicharanrajoju/Desktop/LetsWork status)",
+      "Bash(git -C /Users/saicharanrajoju/Desktop/LetsWork diff docs/spec.md)",
+      "Bash(git -C /Users/saicharanrajoju/Desktop/LetsWork diff tests/__init__.py)",
+      "Bash(git -C /Users/saicharanrajoju/Desktop/LetsWork diff src/server.py)"
+    ]
+  }
+}

letswork-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v

letswork-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

letswork-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Distribution
+*.tar.gz
+*.whl

letswork-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: letswork
+Version: 0.1.0
+Summary: Real-time collaborative coding via MCP — two developers, one codebase
+Author: Sai Charan Rajoju
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: textual[syntax]>=0.50.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LetsWork
+
+**Google Docs for AI-assisted coding** — real-time collaboration on a local codebase using two independent Claude subscriptions.
+
+## What is LetsWork?
+
+LetsWork is an MCP (Model Context Protocol) server that lets two developers work on the same local codebase simultaneously, each using their own Claude. One developer hosts, the other connects — with file-level locking to prevent conflicts.
+
+## How It Works
+
+1. Developer A (Host) runs `letswork start` in their project folder
+2. A secure HTTPS tunnel is created automatically via Cloudflare
+3. A one-time URL + secret token is generated
+4. Developer A shares both with Developer B (Guest)
+5. Developer B connects: `claude mcp add letswork --transport http <url>`
+6. Both can now read, write, and list files — with lock protection
+
+## Quick Start
+
+### Install
+```bash
+pip install letswork
+```
+
+### Requirements
+
+- Python >= 3.10
+- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed and available in PATH
+- Git (recommended for conflict safety)
+
+### Host (Developer A)
+```bash
+cd /path/to/your/project
+letswork start
+```
+
+You'll see:
+╔══════════════════════════════════════════════════╗
+║  LetsWork Session Active                        ║
+║                                                 ║
+║  URL:   https://abc123.trycloudflare.com        ║
+║  Token: a1b2c3d4e5f6...                         ║
+║                                                 ║
+║  Share both with your collaborator.             ║
+║  Press Ctrl+C to end session.                   ║
+╚══════════════════════════════════════════════════╝
+
+Share the URL and token with your collaborator via Slack, Discord, or text.
+
+### Guest (Developer B)
+```bash
+claude mcp add letswork --transport http <URL_FROM_HOST>
+```
+
+Use the token when prompted. You now have full access to the shared codebase through your own Claude.
+
+## MCP Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | List files and directories with lock status |
+| `read_file` | Read file contents (1MB limit) |
+| `write_file` | Write to a file (auto-locks if needed) |
+| `lock_file` | Lock a file for exclusive editing |
+| `unlock_file` | Release a file lock |
+| `get_status` | Show session info and active locks |
+
+## Security
+
+- Unguessable tunnel URL (random Cloudflare subdomain)
+- Cryptographic secret token (second auth layer)
+- All traffic encrypted via HTTPS
+- Path traversal prevention (no access outside project root)
+- No accounts, no signup, no persistent credentials
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `letswork start [--port PORT]` | Start session (default port: 8000) |
+| `letswork stop` | Stop instructions (use Ctrl+C in v1) |
+| `letswork status` | Status instructions (use get_status tool in v1) |
+
+## Architecture
+Developer A's Machine:
+[Local Codebase] ← [MCP Server] ← [Cloudflare Tunnel] ← HTTPS URL
+↑
+Developer B connects here
+with secret token
+
+## Constraints (v1)
+
+- Maximum 2 users per session (Host + Guest)
+- Text files only (no binary support)
+- 1MB file size limit per operation
+- File operations only (no shell access for Guest)
+
+## License
+
+MIT
+
+---
+
+Built with the [Model Context Protocol](https://modelcontextprotocol.io).

letswork-0.1.0/README.md

@@ -0,0 +1,104 @@
+# LetsWork
+
+**Google Docs for AI-assisted coding** — real-time collaboration on a local codebase using two independent Claude subscriptions.
+
+## What is LetsWork?
+
+LetsWork is an MCP (Model Context Protocol) server that lets two developers work on the same local codebase simultaneously, each using their own Claude. One developer hosts, the other connects — with file-level locking to prevent conflicts.
+
+## How It Works
+
+1. Developer A (Host) runs `letswork start` in their project folder
+2. A secure HTTPS tunnel is created automatically via Cloudflare
+3. A one-time URL + secret token is generated
+4. Developer A shares both with Developer B (Guest)
+5. Developer B connects: `claude mcp add letswork --transport http <url>`
+6. Both can now read, write, and list files — with lock protection
+
+## Quick Start
+
+### Install
+```bash
+pip install letswork
+```
+
+### Requirements
+
+- Python >= 3.10
+- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed and available in PATH
+- Git (recommended for conflict safety)
+
+### Host (Developer A)
+```bash
+cd /path/to/your/project
+letswork start
+```
+
+You'll see:
+╔══════════════════════════════════════════════════╗
+║  LetsWork Session Active                        ║
+║                                                 ║
+║  URL:   https://abc123.trycloudflare.com        ║
+║  Token: a1b2c3d4e5f6...                         ║
+║                                                 ║
+║  Share both with your collaborator.             ║
+║  Press Ctrl+C to end session.                   ║
+╚══════════════════════════════════════════════════╝
+
+Share the URL and token with your collaborator via Slack, Discord, or text.
+
+### Guest (Developer B)
+```bash
+claude mcp add letswork --transport http <URL_FROM_HOST>
+```
+
+Use the token when prompted. You now have full access to the shared codebase through your own Claude.
+
+## MCP Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | List files and directories with lock status |
+| `read_file` | Read file contents (1MB limit) |
+| `write_file` | Write to a file (auto-locks if needed) |
+| `lock_file` | Lock a file for exclusive editing |
+| `unlock_file` | Release a file lock |
+| `get_status` | Show session info and active locks |
+
+## Security
+
+- Unguessable tunnel URL (random Cloudflare subdomain)
+- Cryptographic secret token (second auth layer)
+- All traffic encrypted via HTTPS
+- Path traversal prevention (no access outside project root)
+- No accounts, no signup, no persistent credentials
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `letswork start [--port PORT]` | Start session (default port: 8000) |
+| `letswork stop` | Stop instructions (use Ctrl+C in v1) |
+| `letswork status` | Status instructions (use get_status tool in v1) |
+
+## Architecture
+Developer A's Machine:
+[Local Codebase] ← [MCP Server] ← [Cloudflare Tunnel] ← HTTPS URL
+↑
+Developer B connects here
+with secret token
+
+## Constraints (v1)
+
+- Maximum 2 users per session (Host + Guest)
+- Text files only (no binary support)
+- 1MB file size limit per operation
+- File operations only (no shell access for Guest)
+
+## License
+
+MIT
+
+---
+
+Built with the [Model Context Protocol](https://modelcontextprotocol.io).

letswork-0.1.0/docs/architecture.md

@@ -0,0 +1,73 @@
+# LetsWork — Architecture Decisions
+
+*Record of every architectural decision made during development.
+Read this at the start of every session to avoid contradicting past decisions.*
+
+---
+
+## Decision: Python as Implementation Language
+Date: Session 1
+Decision: Use Python for the entire project
+Reasoning: The official Anthropic MCP SDK is Python-first with the best documentation and examples. The target audience (developers using Claude) overwhelmingly uses Python. Click provides excellent CLI tooling in Python.
+Alternatives rejected: TypeScript (MCP SDK exists but Python SDK is more mature), Rust (no official MCP SDK), Go (no official MCP SDK)
+Impact: All source files are .py, packaging via PyPI, dependencies are Python packages
+
+## Decision: FastMCP as Server Framework
+Date: Session 1
+Decision: Use FastMCP from the official mcp Python SDK
+Reasoning: FastMCP is the high-level API provided by Anthropic's own MCP SDK. It handles protocol details, tool registration, and transport layers. Using the official SDK ensures compatibility with Claude Code and other MCP clients.
+Alternatives rejected: Building raw MCP protocol handling manually (unnecessary complexity), third-party MCP libraries (less maintained than official SDK)
+Impact: Server defined in src/server.py using @app.tool() decorators, transport handled by FastMCP
+
+## Decision: Cloudflare Tunnel for Networking
+Date: Session 1
+Decision: Use cloudflared (Cloudflare Tunnel) to expose the local MCP server
+Reasoning: Free tier sufficient, no port forwarding needed, no VPN needed, no DNS configuration, works behind NATs and firewalls, HTTPS by default. The tunnel creates a random subdomain on trycloudflare.com.
+Alternatives rejected: ngrok (requires account, has rate limits on free tier), localtunnel (less reliable), direct port forwarding (requires router config, not user-friendly), Tailscale (requires both users to install and configure)
+Impact: cloudflared is an external dependency that must be pre-installed. src/tunnel.py manages the subprocess lifecycle.
+
+## Decision: In-Memory File Locking
+Date: Session 1
+Decision: Use a Python dictionary for file lock tracking (path -> user_id)
+Reasoning: Simple, fast, no external dependencies. Locks only need to persist for the duration of a session. When the session ends, all locks are released automatically since the process exits.
+Alternatives rejected: File-system level locks with fcntl/msvcrt (cross-platform complexity, doesn't track user identity), Redis (overkill external dependency), SQLite (unnecessary persistence)
+Impact: LockManager class in src/filelock.py with a dict. Locks are lost if the process crashes — acceptable for v1 since Git is the safety net.
+
+## Decision: Secret Token Authentication
+Date: Session 1
+Decision: Generate a cryptographic random token per session using secrets.token_urlsafe
+Reasoning: Simple, no accounts needed, no persistent credentials. Combined with the unguessable tunnel URL, this provides two layers of security. Token is shared out-of-band (Slack, Discord, text).
+Alternatives rejected: OAuth (massive complexity for a CLI tool), API keys (requires persistent storage), mutual TLS (complex setup for end users)
+Impact: src/auth.py generates and validates tokens. Token is set once at session start and checked on every request.
+
+## Decision: Centralized Path Safety via safe_resolve
+Date: Session 4
+Decision: Create a single safe_resolve(path) function used by all MCP tools for path resolution and traversal prevention
+Reasoning: Initially each tool had inline path resolution logic (os.path.join, os.path.abspath, startswith check). This was duplicated across 5 tools. Extracting it into safe_resolve eliminates duplication and ensures a single point of security enforcement.
+Alternatives rejected: Keeping inline checks per tool (duplication, risk of inconsistency), middleware-level path check (FastMCP doesn't natively support pre-tool middleware)
+Impact: All tools call safe_resolve(path) first. Any path outside project_root raises ValueError.
+
+## Decision: Click for CLI Framework
+Date: Session 1
+Decision: Use Click for the command-line interface
+Reasoning: Click is the standard Python CLI library — well-documented, widely used, supports groups, commands, options, and help text out of the box. Minimal code for a professional CLI.
+Alternatives rejected: argparse (more verbose, less elegant), Typer (adds a dependency on top of Click), fire (too magic, less control)
+Impact: src/cli.py defines a Click group with start, stop, and status commands
+
+## Decision: Streamable HTTP Transport
+Date: Session 4
+Decision: Run the MCP server with transport="streamable-http"
+Reasoning: This is the transport mode required for remote MCP connections over HTTPS tunnels. The Guest connects via HTTP to the Cloudflare tunnel URL, which forwards to the local server.
+Alternatives rejected: stdio transport (only works for local connections, not over network), SSE transport (older protocol, streamable-http is the current standard)
+Impact: app.run() in cli.py uses transport="streamable-http" with host="127.0.0.1"
+
+## Decision: v1 Scope Boundaries
+Date: Session 1
+Decision: Limit v1 to exactly 2 users, text files only, 1MB limit, no directory creation/deletion, no shell access for Guest
+Reasoning: Shipping a focused, working tool is more important than feature completeness. Every constraint can be relaxed in v2 based on real user feedback. The core value proposition (two developers, one codebase, real-time) works within these constraints.
+Alternatives rejected: Building multi-user support from the start (complexity), supporting binary files (encoding complexity), adding shell access (security risk)
+Impact: All tools enforce these limits. Future scope documented in spec.md Section 9.
+
+---
+
+*Last updated: Session 5 — All architecture decisions documented*

letswork-0.1.0/docs/spec.md

@@ -0,0 +1,247 @@
+# LetsWork — Product Specification
+*Version 1.0 — Source of truth for what LetsWork does and how.*
+
+---
+
+## 1. Product Summary
+
+LetsWork is an MCP (Model Context Protocol) server that enables 
+two developers to collaborate on the same local codebase in 
+real time, each using their own Claude subscription independently.
+
+One developer (the Host) runs LetsWork in their project folder. 
+It starts an MCP server, creates a secure Cloudflare tunnel, 
+and generates a one-time URL + secret token. A second developer 
+(the Guest) adds that URL as an MCP server in their Claude Code. 
+Both can now read and write files in the same codebase with 
+file-level locking to prevent conflicts.
+
+---
+
+## 2. Users
+
+### Host (Developer A)
+- Has the codebase on their local machine
+- Runs `letswork start` to begin a session
+- Shares the generated URL + token with the Guest
+- Can read, write, list, and lock files
+- Can see which files the Guest has locked
+- Can end the session at any time
+
+### Guest (Developer B)
+- Does NOT have the codebase locally
+- Receives the URL + token from the Host
+- Connects via `claude mcp add letswork --transport http <url>`
+- Can read, write, list, and lock files
+- Can see which files the Host has locked
+- Connection ends when the Host stops the session
+
+---
+
+## 3. Core Features
+
+### 3.1 Session Management
+- Host runs `letswork start` in any project directory
+- A local MCP server starts on a random available port
+- A Cloudflare tunnel is created automatically (no config needed)
+- A unique session URL (HTTPS) is generated
+- A one-time secret token is generated for authentication
+- Host sees: URL, token, and session status in terminal
+- Session ends when Host runs `letswork stop` or Ctrl+C
+
+### 3.2 File Operations (MCP Tools)
+LetsWork exposes these MCP tools to both Host and Guest Claude:
+
+| Tool Name       | Parameters              | Description                         |
+|-----------------|-------------------------|-------------------------------------|
+| `read_file`     | `path: str`             | Read contents of a file             |
+| `write_file`    | `path: str, content: str` | Write content to a file           |
+| `list_files`    | `path: str` (optional)  | List files in directory (default: root) |
+| `lock_file`     | `path: str`             | Lock a file for exclusive editing   |
+| `unlock_file`   | `path: str`             | Release lock on a file              |
+| `get_locks`     | (none)                  | Show all currently locked files     |
+| `get_status`    | (none)                  | Show session info and connected users |
+
+### 3.3 File Locking
+- Before writing, a developer must lock the file
+- Only one developer can lock a file at a time
+- Attempting to lock an already-locked file returns an error 
+  with the name of the holder
+- Locks are released explicitly via `unlock_file` or 
+  automatically when the session ends
+- `get_locks` shows all active locks with holder identity
+- `write_file` automatically checks lock ownership before writing
+
+### 3.4 Authentication
+- On session start, a random secret token is generated 
+  (cryptographically secure, 32 characters)
+- Every request from the Guest must include this token
+- Invalid tokens are rejected with 401 Unauthorized
+- Token is single-use per session (new token each `letswork start`)
+- No accounts, no signup, no persistent credentials
+
+### 3.5 Tunneling
+- Cloudflare Tunnel (via `cloudflared`) creates a public 
+  HTTPS URL for the local MCP server
+- No port forwarding required
+- No VPN required
+- No DNS configuration required
+- Works behind NATs and firewalls
+- Free tier is sufficient
+- If `cloudflared` is not installed, LetsWork prints 
+  clear installation instructions and exits
+
+---
+
+## 4. CLI Interface
+
+### Commands:
+```
+letswork start [--port PORT]
+```
+- Starts MCP server + tunnel in current directory
+- Optional: specify port (default: auto-select available port)
+- Outputs: session URL, secret token, status
+```
+letswork stop
+```
+- Stops the MCP server and closes the tunnel
+- Releases all file locks
+- Ends the session cleanly
+```
+letswork status
+```
+- Shows: running/stopped, connected users, active locks, 
+  session duration, tunnel URL
+
+### Terminal Output on Start:
+```
+╔══════════════════════════════════════════════════╗
+║  LetsWork Session Active                        ║
+║                                                 ║
+║  URL:   https://abc123.trycloudflare.com        ║
+║  Token: a1b2c3d4e5f6...                         ║
+║                                                 ║
+║  Share both with your collaborator.              ║
+║  Press Ctrl+C to end session.                   ║
+╚══════════════════════════════════════════════════╝
+```
+
+---
+
+## 5. Security Model
+
+### Threat Model:
+- The tunnel URL is unguessable (random subdomain from Cloudflare)
+- The secret token adds a second layer of authentication
+- Both are required — URL alone is not enough
+- Token is transmitted out-of-band (Host sends it via 
+  Slack/Discord/text, not through the tunnel itself)
+- All traffic is encrypted via HTTPS (Cloudflare handles TLS)
+
+### What LetsWork does NOT protect against:
+- A malicious Guest who has the valid token 
+  (they have full read/write access by design)
+- Network-level attacks on Cloudflare's infrastructure
+- Files outside the project directory 
+  (LetsWork restricts paths to project root — see Section 6)
+
+### Path Traversal Prevention:
+- All file paths are resolved relative to the project root
+- Any path containing `..` or resolving outside the project 
+  directory is rejected with 403 Forbidden
+- Symlinks pointing outside the project directory are rejected
+
+---
+
+## 6. Constraints & Boundaries
+
+### What LetsWork IS:
+- A real-time file collaboration tool for two developers
+- An MCP server that any MCP-compatible client can connect to
+- A lightweight CLI tool with zero configuration
+
+### What LetsWork is NOT:
+- Not a version control system (use Git for that)
+- Not a code editor or IDE
+- Not a cloud storage service
+- Not a deployment tool
+- Not a multi-tenant platform (one Host, one Guest per session)
+
+### Technical Constraints:
+- Maximum 2 concurrent users per session (Host + Guest)
+- File operations only (no terminal/shell access for Guest)
+- No directory creation/deletion via MCP tools 
+  (only file read/write/list)
+- No binary file support in v1 (text files only)
+- Maximum file size: 1MB per read/write operation
+- Project root is the directory where `letswork start` was run
+
+---
+
+## 7. Dependencies
+
+| Dependency       | Purpose                    | Required? |
+|------------------|----------------------------|-----------|
+| Python >= 3.10   | Runtime                    | Yes       |
+| mcp SDK          | MCP server implementation  | Yes       |
+| cloudflared      | Tunnel creation            | Yes (external) |
+| click            | CLI framework              | Yes       |
+| secrets (stdlib) | Token generation           | Yes (built-in) |
+| fcntl / msvcrt   | File locking               | Yes (built-in) |
+| pathlib (stdlib) | Path resolution & safety   | Yes (built-in) |
+| git              | Conflict safety net        | Recommended |
+
+---
+
+## 8. Error Handling Summary
+
+| Situation                        | Behavior                              |
+|----------------------------------|---------------------------------------|
+| `cloudflared` not installed      | Print install instructions, exit      |
+| Port already in use              | Auto-select next available port       |
+| Invalid token from Guest         | Reject with 401 Unauthorized          |
+| File not found on read           | Return clear error message            |
+| Path traversal attempt           | Reject with 403 Forbidden             |
+| File locked by other user        | Return error with lock holder info    |
+| Write without holding lock       | Reject with error                     |
+| Tunnel connection drops          | Attempt reconnect, notify Host        |
+| Host stops session               | All locks released, Guest disconnected|
+| File exceeds 1MB                 | Reject with size limit error          |
+
+---
+
+## 9. Future Scope (v2+, Not for Current Build)
+
+These are explicitly NOT part of v1. Listed here only to 
+acknowledge them and prevent scope creep:
+
+- Multi-guest support (3+ developers)
+- Directory creation/deletion tools
+- Binary file support
+- Built-in diff/merge viewer
+- Chat between Host and Guest
+- Persistent sessions (survive restarts)
+- Web UI dashboard
+- Access control per file/directory
+- Audit log of all operations
+
+---
+
+## 10. Success Criteria for v1
+
+LetsWork v1 is complete when:
+1. `pip install letswork` works
+2. `letswork start` creates a working MCP server + tunnel
+3. A second developer can connect via the URL + token
+4. Both can read, write, list files through their Claude
+5. File locking prevents simultaneous edits
+6. Path traversal is blocked
+7. Session starts and stops cleanly
+8. Published on PyPI
+9. Listed on the official MCP Registry
+
+---
+
+*Last updated: Session 2 — Full specification written*
+#this is a comment