Metadata-Version: 2.4
Name: castrel-proxy
Version: 0.1.10
Summary: A lightweight remote command execution bridge client with MCP integration
Project-URL: Homepage, https://github.com/castrel-ai/castrel-proxy
Project-URL: Documentation, https://github.com/castrel-ai/castrel-proxy#readme
Project-URL: Repository, https://github.com/castrel-ai/castrel-proxy
Project-URL: Issues, https://github.com/castrel-ai/castrel-proxy/issues
Project-URL: Changelog, https://github.com/castrel-ai/castrel-proxy/blob/main/CHANGELOG.md
Author: Castrel Team
License: MIT License
        
        Copyright (c) 2025 Cloudwise
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: bridge,mcp,proxy,remote-execution,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: file-read-backwards>=2.0.0
Requires-Dist: httpx[socks]>=0.27.0
Requires-Dist: langchain-mcp-adapters>=0.2.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: typer>=0.20.1
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Castrel Proxy

[![CI](https://github.com/castrel-ai/castrel-proxy/workflows/CI/badge.svg)](https://github.com/castrel-ai/castrel-proxy/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/pypi/pyversions/castrel-proxy)](https://pypi.org/project/castrel-proxy/)

A lightweight remote command execution bridge client that connects to a server via WebSocket to receive and execute commands, with MCP (Model Context Protocol) integration.

## ✨ Features

- ✅ **Secure Pairing**: Pair with server using verification codes
- ✅ **Persistent Configuration**: Configuration saved in `~/.castrel/config.yaml`
- ✅ **Unique Identifier**: Generate stable client ID based on machine characteristics
- ✅ **WebSocket Connection**: Real-time bidirectional communication
- ✅ **Command Execution**: Execute shell commands with whitelist security
- ✅ **Document Operations**: Read, write, and edit files remotely
- ✅ **Auto Reconnect**: Automatically reconnect when connection is lost
- ✅ **Timeout Control**: Command execution timeout protection
- ✅ **MCP Integration**: Connect to local MCP services and sync tools information

## 📦 Installation

### Via pip

```bash
pip install castrel-proxy
```

### From source

```bash
git clone https://github.com/castrel-ai/castrel-proxy.git
cd castrel-proxy
pip install -e .
```

## 🚀 Quick Start

### 1. Pair with Server

```bash
castrel-proxy pair <verification_code> <server_url>
```

Example:
```bash
castrel-proxy pair eyJ0cyI6MTczNTA4ODQwMCwid2lkIjoiZGVmYXVsdCIsInJhbmQiOiIxMjM0NTYifQ https://server.example.com
```

### 2. Start Bridge Service

```bash
# Run in background (default)
castrel-proxy start

# Run in foreground
castrel-proxy start --foreground

# Press Ctrl+C to stop (foreground mode only)
```

### 3. Stop Bridge Service

```bash
# Stop background daemon
castrel-proxy stop
```

### 4. Check Status

```bash
castrel-proxy status
```

### 5. View Logs

```bash
# View last 50 lines (default)
castrel-proxy logs

# View last 100 lines
castrel-proxy logs -n 100

# Follow logs in real-time
castrel-proxy logs -f
```

## 🛠️ Managing Skills

**Create a skill scaffold:**
```bash
castrel-bridge-cli skill init my-skill -d "my custom skill"
```

**List local skills:**
```bash
castrel-bridge-cli skill list -v
```

**Validate a skill:**
```bash
castrel-bridge-cli skill validate my-skill --strict
```

**Package / Import a skill:**
```bash
castrel-bridge-cli skill package my-skill -o /tmp/my-skill.skill
castrel-bridge-cli skill import /tmp/my-skill.skill
```

**Sync skills to server:**
```bash
castrel-bridge-cli skill sync
```

### Skill Sync Troubleshooting

- `401/403`: Re-run `castrel-bridge-cli pair` and verify the code and workspace match.
- `skill_content_pull` fails with `content_hash` mismatch: Server content has changed — retry sync or check if server is caching an old hash.
- Import fails with "directory name does not match frontmatter name": Rename the directory to exactly match the `name` field in `SKILL.md`.
- Import fails with "forbidden file type": Remove `.pem/.key/.dll/.so` and other restricted files before importing.
- Skills not visible on server after sync: Confirm `castrel-bridge-cli skill list -v` shows local skills, then run `castrel-bridge-cli mcp-sync` or `skill sync`.

## 📖 Documentation

- [Installation Guide](docs/installation.md)
- [Configuration Guide](docs/configuration.md)
- [Daemon Mode Guide](docs/daemon-mode.md)
- [MCP Integration](docs/mcp-integration.md)
- [API Reference](docs/api-reference.md)
- [Protocol Specification](docs/protocol.md)
- [Migration Guide](MIGRATION_GUIDE.md)

## 🔧 Configuration

### Bridge Configuration (`~/.castrel/config.yaml`)

Pairing information is saved automatically:

```yaml
server_url: "https://server.example.com"
verification_code: "ABC123"
client_id: "a1b2c3d4e5f6"
workspace_id: "default"
paired_at: "2025-12-22T10:30:00Z"
```

### MCP Configuration (`~/.castrel/mcp.json`)

Configure MCP services (optional):

```json
{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    }
  }
}
```

See `examples/mcp.json.example` for more examples.

### Command Whitelist (`~/.castrel/whitelist.conf`)

Configure allowed commands for security:

```
# Add commands one per line
ls
cat
git
python
# etc.
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────┐
│           Bridge Client (Local)                 │
│                                                 │
│  ┌──────────────────────────────────────────┐  │
│  │         CLI Commands                     │  │
│  └──────────────────────────────────────────┘  │
│                    │                            │
│      ┌─────────────┼─────────────┐              │
│      │             │             │              │
│  ┌───▼────┐  ┌────▼─────┐  ┌───▼─────┐        │
│  │ Core   │  │   MCP    │  │ Network │        │
│  │ Config │  │  Manager │  │ Client  │        │
│  └────────┘  └──────────┘  └──────────┘        │
│                    │             │              │
│              ┌─────▼─────┐       │              │
│              │   MCP     │       │              │
│              │  Servers  │       │              │
│              └───────────┘  ┌────▼─────┐       │
│                             │ Command  │       │
│                             │ Executor │       │
│                             └──────────┘       │
└─────────────────────────────────────────────────┘
                              │
                              │ WebSocket
                              ▼
┌─────────────────────────────────────────────────┐
│            Bridge Server (Remote)               │
│  /api/v1/bridge/ws?client_id=xxx&code=yyy       │
└─────────────────────────────────────────────────┘
```

## 🛠️ Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/castrel-ai/castrel-proxy.git
cd castrel-proxy

# Install dependencies and sync environment
uv sync
```

### Run Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=castrel_proxy

# Run specific test file
pytest tests/test_core.py
```

### Code Quality

```bash
# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/
```

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔒 Security

For security concerns, please see [SECURITY.md](SECURITY.md) or contact security@example.com.

## 📮 Contact

- Issues: [GitHub Issues](https://github.com/castrel-ai/castrel-proxy/issues)
- Discussions: [GitHub Discussions](https://github.com/castrel-ai/castrel-proxy/discussions)

## 🙏 Acknowledgments

- Built with [Typer](https://typer.tiangolo.com/) for CLI
- Uses [aiohttp](https://docs.aiohttp.org/) for async WebSocket communication
- Integrates with [MCP](https://modelcontextprotocol.io/) for tool protocols
