Claude 插件集成

概述

Stata-MCP 为 Claude Code 提供官方原生插件支持，目前 stata-toolbox@stata-plugin-lib 中集成了两个强大组件：

Stata-MCP 服务器：用于 Stata 执行的模型上下文协议服务器
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 中找到。

.claude-plugin/
├── marketplace.json          # 插件注册表清单
└── plugins/
    └── stata-toolbox/       # 插件包
        └── plugin.json        # 插件配置

市场清单（`marketplace.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`）

{
  "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 服务器配置

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

command：执行 MCP 服务器的命令。使用 uvx 允许直接运行已安装的 Python 包，无需激活虚拟环境。

args：传递给命令的命令行参数数组。["stata-mcp"] 指定要运行的包名。

LSP 服务器配置

"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 语言服务器设置，用于代码补全、格式化和样式检查。

安装

前提条件

在安装插件之前，请确保满足以下要求：

Claude Code：通过官方安装程序安装 ```bash # macOS/Linux curl -fsSL https://claude.ai/install.sh | bash

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

Stata：有效的 Stata 17+ 许可证并安装了 Stata MP
Python 包：stata-mcp 包可用 bash # 验证安装 uvx stata-mcp --usable
Stata LSP：已安装语言服务器 bash pipx install "git+https://github.com/euglevi/stata-language-server.git"
uv：包运行器（推荐） ```bash # 通过 homebrew 安装 brew install uv

# 或通过官方安装程序 curl -LsSf https://astral.sh/uv/install.sh | sh ```

安装方法

添加市场注册表并安装插件：

# 添加市场
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 操作的工作目录。

验证

安装后，验证插件是否已加载：

# 列出已安装的插件
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。

论文复现

> 从 "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/

快速假设检验

> 检验 2008 年金融危机后教育回报是否增加
> 使用大学入学作为处理组的双重差分法

Claude：
1. 生成 DiD 规范
2. 使用事件研究设计运行 stata_do
3. 呈现带经济学解释的结果

比较：插件 vs 手动配置

手动配置

使用命令的传统方法：

claude mcp add stata-mcp -- uvx stata-mcp

或需要手动编辑 .mcp.json：

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

基于插件的配置

使用插件：

# 单命令安装
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"

诊断：

# 独立测试 MCP 服务器
uvx stata-mcp --usable

# 检查 Stata 是否可访问
stata-se --version

# 验证 uvx 安装
uvx --version

解决方案： 1. 安装缺失的依赖： bash pip install stata-mcp

验证 Stata 安装路径
检查环境变量是否正确设置

LSP 不工作

症状： .do 文件中没有语法高亮或补全