# Claude 插件集成
## 概述
Stata-MCP 为 Claude Code 提供官方原生插件支持，目前 `stata-toolbox@stata-plugin-lib` 中集成了两个强大组件：
1. **Stata-MCP 服务器**：用于 Stata 执行的模型上下文协议服务器
2. **Stata LSP（Language Server Protocol）**：Stata do 文件的高级语言支持
此插件包名为 **stata-toolbox**，提供统一的实证研究开发环境，将 Stata 的分析能力与 AI 辅助和高级 IDE 功能相结合。
## 什么是 Claude Plugin？
Claude Plugin 是 Claude Code 中引入的插件系统，允许开发者打包和分发：
- **MCP 服务器**：向 Claude 暴露工具的模型上下文协议服务器
- **LSP 服务器**：用于增强编辑器支持的语言服务器协议服务器
- **Skills**：扩展 Claude 智能体能力的技能
- **配置**：预配置的最佳集成设置
插件系统实现复杂开发环境的一键安装，用可复现、版本控制的包替代手动配置。
## 插件结构
> 更多插件配置模式可在 Claude 的 [plugins-reference](https://code.claude.com/docs/en/plugins-reference#plugin-manifest-schema) 中找到。
```
.claude-plugin/
├── marketplace.json # 插件注册表清单
└── plugins/
└── stata-toolbox/ # 插件包
└── plugin.json # 插件配置
```
### 市场清单（`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."
}
]
}
```
**字段：**
- `name`（string）：市场库标识符（kebab-case，无空格）
- `owner`（object）：作者信息
- `name`（string）：作者姓名
- `email`（string）：联系邮箱
- `plugins`（array）：插件包列表
- `name`（string）：插件标识符
- `source`（string）：插件目录的相对路径
- `description`（string）：插件功能摘要
### 插件配置（`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": {
...
}
}
```
**配置分区：**
#### MCP 服务器配置
```json
{
"mcpServers": {
"stata-mcp": {
"command": "uvx",
"args": [
"stata-mcp"
]
}
}
}
```
**command**：执行 MCP 服务器的命令。使用 `uvx` 允许直接运行已安装的 Python 包，无需激活虚拟环境。
**args**：传递给命令的命令行参数数组。`["stata-mcp"]` 指定要运行的包名。
#### LSP 服务器配置
```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
}
}
}
}
```
> **注意**：您应该先通过 `pipx install "git+https://github.com/euglevi/stata-language-server.git"` 安装 `stata-language-server`。
**command**：LSP 服务器二进制可执行文件。必须在系统 PATH 中可用。
**args**：传递给 LSP 服务器的命令行参数数组。空数组表示无额外参数。
**extensionToLanguage**：将文件扩展名映射到语言标识符。`.do` 文件映射到 `stata` 语言以获得正确的 LSP 支持。
**settings**：LSP 特定配置对象。`stata` 键包含 Stata 语言服务器设置，用于代码补全、格式化和样式检查。
## 安装
### 前提条件
在安装插件之前，请确保满足以下要求：
1. **Claude Code**：通过官方安装程序安装
```bash
# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows
irm https://claude.ai/install.ps1 | iex
```
2. **Stata**：有效的 Stata 17+ 许可证并安装了 Stata MP
3. **Python 包**：`stata-mcp` 包可用
```bash
# 验证安装
uvx stata-mcp --usable
```
4. **Stata LSP**：已安装语言服务器
```bash
pipx install "git+https://github.com/euglevi/stata-language-server.git"
```
5. **uv**：包运行器（推荐）
```bash
# 通过 homebrew 安装
brew install uv
# 或通过官方安装程序
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 安装方法
添加市场注册表并安装插件：
```bash
# 添加市场
claude plugin marketplace add sepinetam/stata-mcp
# 安装插件到用户范围（默认）
claude plugin install stata-toolbox
# 安装到项目范围（与团队共享）
claude plugin install stata-toolbox --scope project
# 安装到本地范围（gitignore）
claude plugin install stata-toolbox --scope local
```
插件自动使用当前目录作为 Stata 操作的工作目录。
### 验证
安装后，验证插件是否已加载：
```bash
# 列出已安装的插件
claude plugin list
```
### 工作原理
安装后，插件提供无缝集成：
**1. 自动加载**
Claude Code 自动检测：
- `.claude-plugin/marketplace.json` → 插件注册表
- `plugins/stata-toolbox/plugin.json` → 插件配置
**2. MCP 工具**
Stata-MCP 服务器暴露 Claude 可调用的工具：
- `stata_do`：执行 Stata 代码
- `write_dofile`：创建 do 文件
- `get_data_info`：分析数据集
- `help`：获取 Stata 命令文档
- 以及更多...
**3. LSP 功能**
Stata LSP 提供高级编辑器支持：
- **语法高亮**：增强的 .do 文件着色
- **补全**：自动建议 Stata 命令
- **悬停文档**：鼠标悬停在命令上获取帮助
- **错误检测**：实时语法验证
- **格式化**：自动格式化 .do 文件
### 示例工作流程
> 此部分由 AI 生成，使用前请审查。如果您想获得最佳结果，应该根据自己的偏好编辑 `~/.claude/CLAUDE.md`。
#### 论文复现
```markdown
> 从 "source/data/CPS_2018.dta" 加载数据集
> 使用 OLS 回归复现 Mincer (1974) 的表 3
> 将回归表导出为 LaTeX 格式
Claude：
1. 使用 get_data_info 了解数据集结构
2. 使用 write_dofile 创建 do 文件
3. 使用 stata_do 执行
4. 将表导出到 stata-mcp-result/
```
#### 快速假设检验
```markdown
> 检验 2008 年金融危机后教育回报是否增加
> 使用大学入学作为处理组的双重差分法
Claude：
1. 生成 DiD 规范
2. 使用事件研究设计运行 stata_do
3. 呈现带经济学解释的结果
```
## 比较：插件 vs 手动配置
### 手动配置
使用命令的传统方法：
```bash
claude mcp add stata-mcp -- uvx stata-mcp
```
或需要手动编辑 `.mcp.json`：
```json
{
"mcpServers": {
"stata-mcp": {
"command": "uvx",
"args": ["stata-mcp"],
"env": {
"STATA_MCP_CWD": "/absolute/path/to/project"
}
}
}
}
```
### 基于插件的配置
**使用插件：**
```bash
# 单命令安装
claude plugin marketplace add sepinetam/stata-mcp
claude plugin install stata-toolbox
```
### 比较
| 功能 | 手动配置 | 插件安装 |
|------------------|--------------------------------------|------------------------------------------|
| **设置** | 手动编辑 `.mcp.json` 或命令 | 一键安装 |
| **MCP 服务器** | ✅ | ✅ |
| **LSP 服务器** | ❌ 单独安装 | ✅ 包含 |
| **团队共享** | ✅ | ✅ |
| **更新** | 自动更新最新 MCP | 自动更新 MCP，手动更新其他 |
## 架构
### 插件加载流程
```
1. Claude Code 启动
↓
2. 扫描 .claude-plugin/marketplace.json
↓
3. 解析插件注册表
↓
4. 加载每个插件的 plugin.json
↓
5. 注册 MCP 服务器
↓
6. 初始化 LSP 服务器
↓
7. 应用插件配置
↓
8. 插件可供使用
```
### 组件交互
```
┌─────────────────────────────────────────────────────┐
│ Claude Code │
└──────────────────────┬──────────────────────────────┘
│
┌─────────────┴────────────┐
│ │
┌────▼─────┐ ┌────▼─────┐
│ MCP │ │ LSP │
│ Server │ │ Server │
└────┬─────┘ └────┬─────┘
│ │
┌────▼───────────────────────────▼────┐
│ Stata-MCP Package │
│ - stata_do tool │
│ - Data analysis tools │
│ - Help system │
└─────────────────────────────────────┘
│
┌────▼──────────┐
│ Stata │
│ Executable │
└───────────────┘
```
## 故障排除
### 插件未检测到
**症状：** 插件已安装但 Claude Code 不显示工具
**解决方案：**
1. 完全重启 Claude Code
2. 验证 marketplace.json 和 plugin.json 中的 JSON 语法
3. 检查文件权限（必须可读）
4. 确保插件正确安装
5. 运行 `claude plugin list` 验证
### MCP 服务器连接失败
**症状：** 工具显示错误 "Failed to connect to MCP server"
**诊断：**
```bash
# 独立测试 MCP 服务器
uvx stata-mcp --usable
# 检查 Stata 是否可访问
stata-se --version
# 验证 uvx 安装
uvx --version
```
**解决方案：**
1. 安装缺失的依赖：
```bash
pip install stata-mcp
```
2. 验证 Stata 安装路径
3. 检查环境变量是否正确设置
### LSP 不工作
**症状：** .do 文件中没有语法高亮或补全
**诊断：**
```bash
# 检查 stata-language-server 是否已安装
which stata-language-server
# 测试 LSP 服务器
stata-language-server --help
```
**解决方案：**
1. 安装 stata-language-server：
```bash
npm install -g stata-language-server
```
2. 验证文件扩展名映射：
```json
{
"extensionToLanguage": {
".do": "stata"
}
}
```
3. 检查 Claude Code 中的 LSP 日志
## 最佳实践
1. **验证安装**：安装前使用 `uvx stata-mcp --usable` 检查系统兼容性
2. **环境变量**：对敏感数据使用 `.env` 文件或项目设置
3. **文档**：维护带有研究指令的项目特定 CLAUDE.md
4. **版本更新**：保持插件更新以获取最新功能和错误修复
## 相关文档
- [配置指南](configuration.md) - 高级配置选项
- [安全文档](security.md) - 安全守卫系统
- [监控指南](monitoring.md) - 资源监控
- [MCP 工具参考](mcp/tools.md) - 可用工具
- [使用示例](usage.md) - 常见工作流程
- [客户端配置](clients.md) - 替代客户端设置
## 许可证和归属
stata-toolbox 插件是 Stata-MCP 项目的一部分。
- **许可证**：AGPL-3.0
- **版权**：(c) 2026 Song Tan (Sepine Tam), Inc.
- **作者**：Song Tan (sepinetam@gmail.com)
**Stata LSP**：由 [euglevi](https://github.com/euglevi/stata-language-server) 版权所有，采用 [MIT 许可证](https://github.com/euglevi/stata-language-server/blob/main/LICENSE)
该插件集成了独立开发的组件：
- **Stata-MCP Server**：[GitHub 仓库](https://github.com/sepinetam/stata-mcp)
- **Stata LSP**：[GitHub 仓库](https://github.com/euglevi/stata-language-server)
---
**文档版本**：1.0.0
**最后更新**：2025-02-12
**维护者**：Song Tan (sepinetam@gmail.com)
