# Claude Plugin Integration

## Overview

Stata-MCP provides official native plugin support for Claude Code, integrating two powerful components in `stata-toolbox@stata-plugin-lib` now:

1. **Stata-MCP Server**: Model Context Protocol server for Stata execution
2. **Stata LSP (Language Server Protocol)**: Advanced language support for Stata do-files

This plugin package, named **stata-toolbox**, delivers a unified development environment for empirical research, combining the analytical power of Stata with AI assistance and advanced IDE features.

## What is Claude Plugin?

Claude Plugin is a plugin system introduced in Claude Code that allows developers to package and distribute:

- **MCP Servers**: Model Context Protocol servers that expose tools to Claude
- **LSP Servers**: Language Server Protocol servers for enhanced editor support
- **Skills**: Skills for expand Claude agent abilities
- **Configuration**: Pre-configured settings for optimal integration

The plugin system enables one-command installation of complex development environments, replacing manual configuration with reproducible, version-controlled packages.

## Plugin Structure

> More plugin config schema could be found in [plugins-reference](https://code.claude.com/docs/en/plugins-reference#plugin-manifest-schema) from Claude. 

```
.claude-plugin/
├── marketplace.json          # Plugin registry manifest
└── plugins/
    └── stata-toolbox/       # Plugin package
        └── plugin.json        # Plugin configuration
```

### Marketplace Manifest (`marketplace.json`)

```json
{
  "name": "stata-plugin-lib",
  "owner": {
    "name": "Song Tan",
    "email": "sepinetam@gmail.com"
  },
  "plugins": [
    {
      "name": "stata-toolbox",
      "source": "./plugins/stata-toolbox",
      "description": "The official working package of Stata-MCP plugin, including mcp config and stata lsp."
    }
  ]
}
```

**Fields:**
- `name` (string): Marketplace library identifier (kebab-case, no spaces)
- `owner` (object): Author information
  - `name` (string): Author name
  - `email` (string): Contact email
- `plugins` (array): List of plugin packages
  - `name` (string): Plugin identifier
  - `source` (string): Relative path to plugin directory
  - `description` (string): Plugin functionality summary

### Plugin Configuration (`plugin.json`)

```json
{
  "name": "stata-toolbox",
  "version": "0.1.0",
  "description": "The official working package of Stata-MCP plugin, including mcp config and stata lsp.",
  "author": {
    "name": "Song Tan",
    "email": "sepinetam@gmail.com",
    "url": "https://www.sepinetam.com"
  },
  "homepage": "https://statamcp.com",
  "repository": "https://github.com/sepinetam/stata-mcp",
  "license": "AGPL-3.0",
  "keywords": ["stata", "econometrics", "empirical analysis"],
  "mcpServers": {
    ...
  },
  "lspServers": {
    ...
  }
}
```

**Configuration Sections:**

#### MCP Servers Configuration

```json
{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx", 
      "args": [
        "stata-mcp"
      ]
    }
  }
}
```

**command**: The command to execute the MCP server. Using `uvx` allows running installed Python packages directly without activating a virtual environment.

**args**: Array of command-line arguments passed to the command. `["stata-mcp"]` specifies the package name to run.

#### LSP Servers Configuration

```json
"lspServers": {
  "stata": {
    "command": "stata-language-server",
    "args": [],
    "extensionToLanguage": {
      ".do": "stata"
    },
    "settings": {
      "stata": {
        "setMaxLineLength": 120,
        "setIndentSpace": 4,
        "enableCompletion": true,
        "enableDocstring": true,
        "enableStyleChecking": true,
        "enableFormatting": true
      }
    }
  }
}
```

> **Notes**: You should install `stata-language-server` first via `pipx install "git+https://github.com/euglevi/stata-language-server.git"`. 

**command**: The LSP server binary executable. Must be available in the system PATH.

**args**: Array of command-line arguments passed to the LSP server. Empty array means no additional arguments.

**extensionToLanguage**: Maps file extensions to language identifiers. `.do` files are mapped to the `stata` language for proper LSP support.

**settings**: LSP-specific configuration object. The `stata` key contains Stata language server settings for code completion, formatting, and style checking.

## Installation

### Prerequisites

Before installing the plugin, ensure following requirements are met:

1. **Claude Code**: Install via official installer
   ```bash
   # macOS/Linux
   curl -fsSL https://claude.ai/install.sh | bash

   # Windows
   irm https://claude.ai/install.ps1 | iex
   ```

2. **Stata**: Valid Stata 17+ license with Stata MP installed

3. **Python Package**: `stata-mcp` package available
   ```bash
   # Verify installation
   uvx stata-mcp --usable
   ```

4. **Stata LSP**: Language server installed
   ```bash
   pipx install "git+https://github.com/euglevi/stata-language-server.git"
   ```

5. **uv**: Package runner (recommended)
   ```bash
   # Install via homebrew
   brew install uv

   # Or via official installer
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

### Installation Method

Add the marketplace registry and install the plugin:

```bash
# Add marketplace
claude plugin marketplace add sepinetam/stata-mcp

# Install plugin to user scope (default)
claude plugin install stata-toolbox

# Install to project scope (shared with team)
claude plugin install stata-toolbox --scope project

# Install to local scope (gitignored)
claude plugin install stata-toolbox --scope local
```

The plugin automatically uses the current directory as the working directory for Stata operations.

### Verification

After installation, verify the plugin is loaded:

```bash
# List installed plugins
claude plugin list
```

### How It Works

Once installed, the plugin provides seamless integration:

**1. Automatic Loading**
Claude Code automatically detects:
- `.claude-plugin/marketplace.json` → Plugin registry
- `plugins/stata-toolbox/plugin.json` → Plugin configuration

**2. MCP Tools**
The Stata-MCP server exposes tools that Claude can invoke:
- `stata_do`: Execute Stata code
- `write_dofile`: Create do-files
- `get_data_info`: Analyze datasets
- `help`: Get Stata command documentation
- And more...

**3. LSP Features**
The Stata LSP provides advanced editor support:
- **Syntax Highlighting**: Enhanced .do file coloring
- **Completion**: Auto-suggest Stata commands
- **Hover Documentation**: Mouse over commands for help
- **Error Detection**: Real-time syntax validation
- **Formatting**: Auto-format .do files

### Example Workflows

> This part is generated by AI, please review before use. If you want to achieve the best results, you should edit your `~/.claude/CLAUDE.md` with your own preferences. 

#### Paper Replication

```markdown
> Load the dataset from "source/data/CPS_2018.dta"
> Replicate Table 3 from Mincer (1974) using OLS regression
> Export the regression table to LaTeX format

Claude:
1. Uses get_data_info to understand dataset structure
2. Creates do-file with write_dofile
3. Executes with stata_do
4. Exports table to stata-mcp-result/
```

#### Quick Hypothesis Testing

```markdown
> Test whether education returns have increased post-2008 financial crisis
> Use difference-in-differences with college enrollment as treatment

Claude:
1. Generates DiD specification
2. Runs stata_do with event study design
3. Presents results with economic interpretation
```

## Comparison: Plugin vs Manual Configuration

### Manual Configuration

Traditional approach with command:
```bash
claude mcp add stata-mcp -- uvx stata-mcp
```

or requires manual `.mcp.json` editing:

```json
{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": ["stata-mcp"],
      "env": {
        "STATA_MCP_CWD": "/absolute/path/to/project"
      }
    }
  }
}
```

### Plugin-Based Configuration

**With Plugin:**

```bash
# Single command installation
claude plugin marketplace add sepinetam/stata-mcp
claude plugin install stata-toolbox
```

### Comparison

| Feature          | Manual Configuration                 | Plugin Installation                      |
|------------------|--------------------------------------|------------------------------------------|
| **Setup**        | Edit `.mcp.json` manually or command | One-command installation                 |
| **MCP Server**   | ✅                                    | ✅                                        |
| **LSP Server**   | ❌ Separate installation              | ✅ Included                               |
| **Team Sharing** | ✅                                    | ✅                                        |
| **Updates**      | Auto update the latest MCP           | Auto update MCP and manual update others |

## Architecture

### Plugin Loading Process

```
1. Claude Code Startup
   ↓
2. Scan for .claude-plugin/marketplace.json
   ↓
3. Parse plugin registry
   ↓
4. Load each plugin's plugin.json
   ↓
5. Register MCP servers
   ↓
6. Initialize LSP servers
   ↓
7. Apply plugin configurations
   ↓
8. Plugin ready for use
```

### Component Interaction

```
┌─────────────────────────────────────────────────────┐
│                   Claude Code                       │
└──────────────────────┬──────────────────────────────┘
                       │
         ┌─────────────┴────────────┐
         │                          │
    ┌────▼─────┐                ┌────▼─────┐
    │   MCP    │                │   LSP    │
    │  Server  │                │  Server  │
    └────┬─────┘                └────┬─────┘
         │                           │
    ┌────▼───────────────────────────▼────┐
    │         Stata-MCP Package           │
    │  - stata_do tool                    │
    │  - Data analysis tools              │
    │  - Help system                      │
    └─────────────────────────────────────┘
         │
    ┌────▼──────────┐
    │     Stata     │
    │  Executable   │
    └───────────────┘
```

## Troubleshooting

### Plugin Not Detected

**Symptom:** Plugin installed but Claude Code doesn't show tools

**Solutions:**
1. Restart Claude Code completely
2. Verify JSON syntax in marketplace.json and plugin.json
3. Check file permissions (must be readable)
4. Ensure plugin is installed correctly
5. Run `claude plugin list` to verify

### MCP Server Connection Failed

**Symptom:** Tools show error "Failed to connect to MCP server"

**Diagnosis:**
```bash
# Test MCP server independently
uvx stata-mcp --usable

# Check if Stata is accessible
stata-se --version

# Verify uvx installation
uvx --version
```

**Solutions:**
1. Install missing dependencies:
   ```bash
   pip install stata-mcp
   ```

2. Verify Stata installation path

3. Check environment variables are correctly set

### LSP Not Working

**Symptom:** No syntax highlighting or completion in .do files

**Diagnosis:**
```bash
# Check if stata-language-server is installed
which stata-language-server

# Test LSP server
stata-language-server --help
```

**Solutions:**
1. Install stata-language-server:
   ```bash
   npm install -g stata-language-server
   ```

2. Verify file extension mapping:
   ```json
   {
     "extensionToLanguage": {
       ".do": "stata"
     }
   }
   ```

3. Check LSP logs in Claude Code

## Best Practices

1. **Verify Installation**: Check system compatibility with `uvx stata-mcp --usable` before installing
2. **Environment Variables**: Use `.env` file or project settings for sensitive data
3. **Documentation**: Maintain project-specific CLAUDE.md with research instructions
4. **Version Updates**: Keep plugin updated for latest features and bug fixes

## Related Documentation

- [Configuration Guide](configuration.md) - Advanced configuration options
- [Security Documentation](security.md) - Security guard system
- [Monitoring Guide](monitoring.md) - Resource monitoring
- [MCP Tools Reference](mcp/tools.md) - Available tools
- [Usage Examples](usage.md) - Common workflows
- [Client Configuration](clients.md) - Alternative client setups

## License and Attribution

stata-toolbox plugin is part of the Stata-MCP project.

- **License**: AGPL-3.0
- **Copyright**: (c) 2026 Song Tan (Sepine Tam), Inc.
- **Authors**: Song Tan (sepinetam@gmail.com)

**Stata LSP**: Copyright by [euglevi](https://github.com/euglevi/stata-language-server) with [MIT License](https://github.com/euglevi/stata-language-server/blob/main/LICENSE)

The plugin integrates independently developed components:
- **Stata-MCP Server**: [GitHub Repository](https://github.com/sepinetam/stata-mcp)
- **Stata LSP**: [GitHub Repository](https://github.com/euglevi/stata-language-server)

---

**Document Version**: 1.0.0
**Last Updated**: 2025-02-12
**Maintainer**: Song Tan (sepinetam@gmail.com)
