108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a Rust-based MCP (Model Context Protocol) server that executes JavaScript, TypeScript, and Python code in isolated environments. The project provides both a command-line tool and a library for code execution with proper sandboxing and result capture.
|
|
|
|
## Key Commands
|
|
|
|
### Building and Running
|
|
```bash
|
|
# Build the project
|
|
cargo build
|
|
|
|
# Run with cargo
|
|
cargo run -- js -f fixtures/test_js.js
|
|
cargo run -- ts -f fixtures/test_ts.ts
|
|
cargo run -- python -f fixtures/test_python.py
|
|
|
|
# Install as binary
|
|
cargo install --path . --bin script_runner
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Clear cache
|
|
cargo run -- clear-cache all
|
|
```
|
|
|
|
### Common Development Commands
|
|
```bash
|
|
# Execute JavaScript with logs
|
|
cargo run -- --show-logs js -f fixtures/test_js.js
|
|
|
|
# Execute with parameters
|
|
cargo run -- --show-logs python -f fixtures/test_python_params.py -p '{"a":10, "b":20}'
|
|
|
|
# Execute inline code
|
|
cargo run -- js -c "function handler(input) { return 'Hello: ' + input.name; }" -p '{"name":"User"}'
|
|
|
|
# Use MCP integration
|
|
cargo run -- --use-mcp python -f fixtures/test_python.py
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
- **src/main.rs** - CLI entry point with command parsing using clap
|
|
- **src/lib.rs** - Library interface exporting public APIs
|
|
- **src/model/code_run_model.rs** - Core execution models and `CodeExecutor` struct
|
|
- **src/cache/** - Code caching system using blake3 hashing
|
|
- **src/mcp/** - MCP protocol server implementation
|
|
|
|
### Language Runners
|
|
- **src/deno_runner/js_runner.rs** - JavaScript execution via Deno
|
|
- **src/deno_runner/ts_runner.rs** - TypeScript execution via Deno
|
|
- **src/python_runner/python_runner.rs** - Python execution via uv with dependency analysis
|
|
- **src/python_runner/dependencies/** - Python dependency parsing and management
|
|
|
|
### Execution Flow
|
|
1. Code is processed and cached using blake3 hashing
|
|
2. Language-specific runner prepares the execution environment
|
|
3. Code is wrapped with logging capture and handler function execution
|
|
4. Results are captured and returned as `CodeScriptExecutionResult`
|
|
|
|
## Important Patterns
|
|
|
|
### Handler Function Convention
|
|
Scripts must expose a `handler` function (JS/TS) or `handler`/`main` function (Python) that returns the final result:
|
|
```javascript
|
|
function handler(input) {
|
|
return "Result: " + input.param;
|
|
}
|
|
```
|
|
|
|
### Parameter Passing
|
|
- JS/TS: Parameters passed directly to handler function
|
|
- Python: Parameters passed via `INPUT_JSON` environment variable
|
|
|
|
### Error Handling
|
|
- Uses `anyhow::Result` for error propagation
|
|
- Custom `app_error` module for application-specific errors
|
|
- Execution results include error information in `CodeScriptExecutionResult`
|
|
|
|
### Dependencies
|
|
- **Deno** for JavaScript/TypeScript execution
|
|
- **uv** for Python environment isolation
|
|
- **rmcp** crate for MCP protocol implementation
|
|
- **tokio** for async runtime
|
|
- **serde** for JSON serialization
|
|
|
|
## Development Notes
|
|
|
|
### Testing
|
|
- Test fixtures in `fixtures/` directory for all supported languages
|
|
- Integration tests in `src/tests/`
|
|
- Use `--show-logs` flag during development to see execution output
|
|
|
|
### Caching
|
|
- Code processing results are cached based on content hash
|
|
- Use `--clear-cache` to invalidate cache when debugging
|
|
- Cache files stored in system temp directory
|
|
|
|
### MCP Integration
|
|
- Can run as standalone MCP server via `script_runner` binary
|
|
- Supports SSE and HTTP transports
|
|
- Tools: `run_javascript`, `run_typescript`, `run_python` |