# RStudio MCP Server

A Model Context Protocol (MCP) server for RStudio Desktop integration, enabling seamless R package development, testing, and jamovi module development from VSCode and other MCP clients.

## Features

### R Package Development
- **Testing**: Run package tests with `devtools::test()` or individual test files with `testthat::test_file()`
- **Documentation**: Generate documentation with `devtools::document()` (roxygen2)
- **Building**: Build packages with `devtools::build()`
- **Checking**: Run R CMD check with `devtools::check()`
- **Loading**: Load package functions with `devtools::load_all()` for interactive development

### Jamovi Module Development
- **Build**: Build jamovi modules with `jmvtools::build()`
- **Check**: Validate jamovi modules with `jmvtools::check()`

### General R Capabilities
- **Code Execution**: Run arbitrary R code
- **Package Management**: Install and list packages
- **Workspace Inspection**: List and inspect R workspace objects

## Quick Start

### Automated Setup (Recommended)

Run the automated setup script to check prerequisites and configure everything:

```bash
# Clone the repository
git clone <repository-url>
cd rstudio-mcp-server

# Run automated setup
npm run setup
```

The setup script will:
- Check Node.js and R installation
- Install npm dependencies
- Build the server
- Verify R package requirements
- Guide you through MCP client configuration

### Manual Installation

If you prefer manual setup:

1. **Install Prerequisites**
   - Node.js v18 or higher ([nodejs.org](https://nodejs.org/))
   - R 3.6 or higher with Rscript in PATH
   - Git (for cloning)

2. **Clone and Build**
   ```bash
   git clone <repository-url>
   cd rstudio-mcp-server
   npm install
   npm run build
   ```

3. **Install R Packages**
   ```r
   install.packages(c("devtools", "testthat", "roxygen2"))
   ```

4. **Configure MCP Client** (see Configuration section below)

## Configuration

### For VSCode with Claude Code

Add to your Claude Code MCP settings file (usually `~/.config/claude-code/mcp_settings.json` on Linux/Mac or `%APPDATA%\claude-code\mcp_settings.json` on Windows):

```json
{
  "mcpServers": {
    "rstudio": {
      "command": "node",
      "args": ["/path/to/rstudio-mcp-server/build/index.js"]
    }
  }
}
```

### For Cline or Other MCP Clients

Add to the appropriate MCP settings file for your client:

```json
{
  "mcpServers": {
    "rstudio": {
      "command": "node",
      "args": ["/absolute/path/to/rstudio-mcp-server/build/index.js"]
    }
  }
}
```

## Available Tools

### r_execute
Execute arbitrary R code.

**Parameters:**
- `code` (required): The R code to execute
- `working_dir` (optional): Working directory for execution

**Example:**
```typescript
{
  "code": "summary(mtcars)",
  "working_dir": "/path/to/project"
}
```

### r_test_package
Run tests for an R package using devtools::test().

**Parameters:**
- `package_path` (required): Path to the R package directory
- `filter` (optional): Test filter pattern (regex)

**Example:**
```typescript
{
  "package_path": "/path/to/mypackage",
  "filter": "test-myfunction"
}
```

### r_test_file
Run a specific test file.

**Parameters:**
- `test_file` (required): Path to the test file

**Example:**
```typescript
{
  "test_file": "/path/to/mypackage/tests/testthat/test-myfunction.R"
}
```

### r_check_package
Run R CMD check on a package.

**Parameters:**
- `package_path` (required): Path to the R package directory
- `args` (optional): Additional arguments for R CMD check

**Example:**
```typescript
{
  "package_path": "/path/to/mypackage",
  "args": "--as-cran"
}
```

### r_document_package
Generate documentation for an R package using roxygen2.

**Parameters:**
- `package_path` (required): Path to the R package directory

### r_build_package
Build an R package.

**Parameters:**
- `package_path` (required): Path to the R package directory
- `binary` (optional): Build a binary package (default: false)

### r_load_all
Load all functions in a package for interactive development.

**Parameters:**
- `package_path` (required): Path to the R package directory

### r_install_package
Install an R package from CRAN or local path.

**Parameters:**
- `package` (required): Package name or path
- `dependencies` (optional): Install dependencies (default: true)

### r_list_packages
List all installed R packages.

### r_workspace_ls
List objects in the R workspace.

**Parameters:**
- `pattern` (optional): Pattern to filter object names

### jamovi_build_module
Build a jamovi module.

**Parameters:**
- `module_path` (required): Path to the jamovi module directory
- `install` (optional): Install the module after building (default: false)

### jamovi_check_module
Check a jamovi module for issues.

**Parameters:**
- `module_path` (required): Path to the jamovi module directory

## Usage Examples

### Quick Start Examples

Once configured, you can interact with R through natural language:

**Test R connection:**
- "Can you list all installed R packages?"
- "What version of R is running?"
- "Execute this R code: print(sessionInfo())"

**Package development:**
- "Run the tests for this package"
- "Generate documentation for my package"
- "Check if this package passes R CMD check"
- "Build this package"

**Code execution:**
- "Execute this R code: summary(mtcars)"
- "Install the tidyverse package"
- "Show me what objects are in the workspace"

### Detailed Workflows

#### 1. Starting a New Package

```
You: "I'm creating a new R package called 'datautils'. Can you help me set it up?"

Claude: [Guides you through using usethis::create_package()]

You: "Now document the package"

Claude: [Uses r_document_package tool]
Output: ✔ Writing 'NAMESPACE'
        ✔ Writing 'datautils.Rd'

You: "Check if it passes R CMD check"

Claude: [Uses r_check_package tool]
Output: ── R CMD check results ─────────────────────
        0 errors ✔ | 0 warnings ✔ | 0 notes ✔
```

#### 2. Test-Driven Development

```
You: "Run all tests in the package"

Claude: [Uses r_test_package tool]
Output: ✔ | F W S  OK | Context
        ✔ |         5 | validation
        ✔ |         8 | data-processing
        ✔ |         3 | output-formatting

You: "Run only tests matching 'validation'"

Claude: [Uses r_test_package with filter: "validation"]
Output: ✔ | F W S  OK | Context
        ✔ |         5 | validation

You: "Run the specific test file test-validation.R"

Claude: [Uses r_test_file tool]
Output: Test results for tests/testthat/test-validation.R
        ✔ | 5 tests passed
```

#### 3. Debugging Failing Tests

```
You: "Run the package tests"

Claude: [Uses r_test_package tool]
Output: ✖ | F W S  OK | Context
        ✖ |     1   4 | validation
        ────────────────────────────────────────────
        Failure (test-validation.R:15:3): input validation works
        Expected TRUE, got FALSE

You: "Can you execute this R code to debug:
     source('R/validation.R');
     validate_input(c(1, 2, NA))"

Claude: [Uses r_execute tool]
Output: Error: NA values not allowed

You: "Now I see the issue. Let me fix the code and re-run tests..."
```

#### 4. Package Release Workflow

```
You: "I'm ready to release my package. Let's go through the checklist."

Claude: "I'll help you verify everything:
        1. First, let's run the tests"
        [Uses r_test_package - shows all passing]

Claude: "2. Generating documentation"
        [Uses r_document_package]

Claude: "3. Running R CMD check"
        [Uses r_check_package with args: "--as-cran"]

Claude: "4. Building the package"
        [Uses r_build_package]
        Output: ✔ Building 'datautils_1.0.0.tar.gz'

You: "Perfect! Can you also check for any spelling issues?"

Claude: [Uses r_execute with "spelling::spell_check_package()"]
```

#### 5. Jamovi Module Development

```
You: "I'm working on a jamovi module. Can you check it for issues?"

Claude: [Uses jamovi_check_module tool]
Output: ✔ Checking module structure
        ✔ Validating .a.yaml files
        ✔ Checking R functions
        ✔ Verifying UI definitions

You: "Build and install the module"

Claude: [Uses jamovi_build_module with install: true]
Output: ✔ Building module
        ✔ Installing to jamovi
        Module 'mymodule' installed successfully

You: "Now I'll test it in jamovi..."
```

#### 6. Interactive Data Analysis

```
You: "Can you execute this analysis:
     library(dplyr)
     mtcars %>%
       group_by(cyl) %>%
       summarize(
         mean_mpg = mean(mpg),
         mean_hp = mean(hp)
       )"

Claude: [Uses r_execute tool]
Output: # A tibble: 3 × 3
          cyl mean_mpg mean_hp
        <dbl>    <dbl>   <dbl>
      1     4     26.7    82.6
      2     6     19.7   122.
      3     8     15.1   209.

You: "Now create a linear model of mpg vs hp"

Claude: [Uses r_execute tool]
Output: Call:
        lm(formula = mpg ~ hp, data = mtcars)

        Coefficients:
        (Intercept)           hp
           30.09886     -0.06823
```

#### 7. Package Installation and Management

```
You: "Install the ggplot2 package"

Claude: [Uses r_install_package tool]
Output: Installing package into '/home/user/R/library'
        ✔ Package 'ggplot2' successfully installed

You: "List all packages containing 'test' in the name"

Claude: [Uses r_list_packages tool, then filters]
Output: Packages matching 'test':
        - testthat (3.2.0)
        - testit (0.13)
        - covr (3.6.1)
```

#### 8. Working with Multiple Packages

```
You: "I have three packages I'm developing. Can you run tests on all of them?
     - /path/to/package1
     - /path/to/package2
     - /path/to/package3"

Claude: "I'll test each package:

Package 1:
[Uses r_test_package for package1]
✔ All 15 tests passed

Package 2:
[Uses r_test_package for package2]
✔ All 22 tests passed

Package 3:
[Uses r_test_package for package3]
✖ 2 tests failed
[Shows failure details]

Two packages passed, but package3 has failing tests. Would you like me to show the specific failures?"
```

#### 9. Development Environment Setup

```
You: "I'm setting up a new development machine. What R packages do I need?"

Claude: "Let me check what's installed"
        [Uses r_list_packages tool]

Claude: "I see you're missing some key development packages. I can install:
        - devtools (package development)
        - testthat (testing)
        - roxygen2 (documentation)
        - usethis (workflow automation)

        Should I install these?"

You: "Yes, please install them"

Claude: [Uses r_install_package for each package]
        ✔ All development packages installed
```

#### 10. CI/CD Preparation

```
You: "I want to make sure my package will pass CI checks. Run all quality checks."

Claude: "I'll run a comprehensive check:

1. Tests:
[Uses r_test_package]
✔ All 45 tests passed

2. Documentation:
[Uses r_document_package]
✔ Documentation up to date

3. R CMD check:
[Uses r_check_package with args: "--as-cran"]
✔ 0 errors | 0 warnings | 0 notes

4. Package build:
[Uses r_build_package]
✔ Package builds successfully

Your package is ready for CI! All checks passed."
```

### Common Use Cases

**Quick test after code changes:**
```
"Run the tests"
```

**Full pre-commit check:**
```
"Run tests, update docs, and run R CMD check"
```

**Install development dependencies:**
```
"Install devtools, testthat, and roxygen2"
```

**Debug a specific function:**
```
"Execute this code: debugonce(my_function); my_function(test_data)"
```

**Check test coverage:**
```
"Execute: covr::package_coverage()"
```

**Spell check documentation:**
```
"Execute: spelling::spell_check_package()"
```

## Development

Watch mode for development:
```bash
npm run watch
```

## Troubleshooting

### R not found
Make sure R and Rscript are in your system PATH:
```bash
which Rscript  # Linux/Mac
where Rscript  # Windows
```

**Windows PATH setup:**
1. Find your R installation (usually `C:\Program Files\R\R-4.x.x\bin`)
2. Add to PATH:
   - Search "Environment Variables" in Start menu
   - Edit "Path" under System variables
   - Add new entry: `C:\Program Files\R\R-4.x.x\bin`
   - Restart terminal/VSCode

**Multiple R versions:**
- Ensure the correct R version is first in PATH
- Check with: `Rscript --version`

### devtools/testthat not found
Install required R packages:
```r
install.packages(c("devtools", "testthat", "roxygen2"))
```

### jamovi tools not found

Installing `jmvtools` requires special considerations. See [JMVTOOLS_INSTALLATION.md](JMVTOOLS_INSTALLATION.md) for detailed instructions.

**Quick summary:**
- **Option 1**: Install Rtools (Windows) or build tools (Mac/Linux), then `install.packages("jmvtools")`
- **Option 2**: Use jamovi's bundled R (recommended for jamovi developers)
- **Option 3**: Install pre-built binaries

**Common issue**: `jmvtools` requires compilation tools:
```
Error: package 'jmvtools' is not available
```

See the dedicated jmvtools guide for platform-specific solutions.

### Build failures

**TypeScript errors:**
```bash
# Clean rebuild
rm -rf build node_modules
npm install
npm run build
```

**Permission errors:**
```bash
# Linux/Mac
chmod +x build/index.js

# Windows: Run terminal as Administrator if needed
```

### MCP client connection issues

**Server not appearing in MCP client:**
1. Verify JSON syntax in config file (use a JSON validator)
2. Use absolute paths (not relative: `~/` or `.\`)
3. Restart the MCP client completely
4. Check client logs for error messages

**Windows path format:**
```json
{
  "args": ["D:\\path\\to\\server\\build\\index.js"]  // Use double backslashes
  // OR
  "args": ["D:/path/to/server/build/index.js"]       // Use forward slashes
}
```

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT