使用说明

vba-lint mcp

提供VBA代码检查、linting和解析树分析的MCP服务器——从Rubberduck VBA移植的65个检查。

概述

vba-lint-mcp 通过以下方式公开VBA静态分析功能模型上下文协议，使AI助手（Claude Code等）和MCP兼容工具能够对VBA源文件执行代码质量检查。

检查逻辑源自橡胶鸭VBA 项目——一个开源的VBIDE插件，为VBA开发人员提供代码检查、重构、导航和单元测试。该项目将Rubberduck经过验证的C#检查模式转换为TypeScript，并通过MCP访问它们。

这是给谁的？

VBA开发人员使用Claude Code或其他MCP客户端提供代码帮助
需要自动代码质量检查的维护Excel/Access VBA项目的团队
任何构建包含VBA支持的基于MCP的开发工具链的人

快速开始

安装

git clone git@github.com:devinmlowe/vba-lint-mcp.git
cd vba-lint-mcp
npm install
npm run generate-parser   # Requires Java 17+ (JRE)
npm run build

在Claude代码中配置

添加到MCP设置(.claude/settings.json 或项目设置）：

{
  "mcpServers": {
    "vba-lint": {
      "command": "node",
      "args": ["/path/to/vba-lint-mcp/dist/server.js"],
      "env": {
        "VBA_LINT_LOG_LEVEL": "warn"
      }
    }
  }
}

第一次检查

配置后，Claude Code可以直接检查VBA代码：

> Inspect this VBA code for issues:
>
> Sub Example()
>     Dim x
>     Let y = 10
>     If True Then
>     End If
> End Sub

服务器将返回缺失的诊断信息 Option Explicit，隐式变量类型，已过时 Let 关键字和空 If 块。

工具

`vba/inspect`

对VBA代码字符串运行检查。

参数	类型	默认值	说明
`code`	string	（必需）	要检查的VBA源代码
`hostLibraries`	string[]	`["excel"]`	可用的主机库（例如。， `["excel", "access"]`)
`severity`	string	（all）	最小严重性： `"error"`, `"warning"`, `"suggestion"`, `"hint"`
`categories`	string[]	（all）	按类别筛选（例如。， `["CodeQuality", "Excel"]`)

输出示例：

{
  "results": [
    {
      "inspection": "EmptyIfBlock",
      "description": "If block is empty and should either contain code or be removed.",
      "severity": "warning",
      "category": "CodeQuality",
      "tier": "A",
      "location": { "startLine": 3, "startColumn": 4, "endLine": 4, "endColumn": 10 },
      "quickFix": { "description": "Remove the empty If block" },
      "suppressed": false
    }
  ],
  "errors": [],
  "skippedInspections": [],
  "parseErrors": [],
  "engineVersion": "0.1.0"
}

`vba/inspect-workspace`

扫描VBA文件（.bas、.cls、.frm）的目录树，并返回聚合结果。

参数	类型	默认值	说明
`path`	string	（必填）	要扫描的目录路径
`hostLibraries`	string[]	`["excel"]`	主机库可用
`severity`	string	（all）	最小严重性筛选器
`categories`	string[]	（all）	类别筛选器
`limit`	number	100	返回的最大结果数
`detailed`	boolean	false	返回完整结果而不是摘要

在摘要模式（默认）下，按文件和检查返回计数。在详细模式下，为每个发现返回完整的结果对象。

`vba/list-inspections`

列出所有可用的检查及其元数据。

参数	类型	默认值	说明
`hostLibraries`	string[]	（all）	按主机库筛选
`category`	string	（all）	按类别筛选
`tier`	string	（all）	按层筛选： `"A"` 或 `"B"`

`vba/parse`

解析VBA源代码并返回AST。

参数	类型	默认值	说明
`code`	string	（必需）	要解析的VBA源代码
`depth`	number	3	要返回的最大AST深度（1-10）

有助于理解代码结构。这 depth 参数限制了大型模块的序列化大小。

检验目录

在2个级别和8个类别中进行了65次检查。

A级：解析树检查（43）

这些检查直接分析ANTLR4解析树，不需要符号解析。它们在两个内联代码上运行(vba/inspect)以及工作空间扫描。

ID	类别	严重性	描述
`EmptyIfBlock`	CodeQuality	警告	如果块为空，应包含代码或被删除。
`EmptyElseBlock`	CodeQuality	警告	否则块为空，应包含代码或被删除。
`EmptyCaseBlock`	CodeQuality	警告	大小写块为空，应包含代码或删除。
`EmptyForLoopBlock`	CodeQuality	警告	适用。..下一个循环是空的，应该包含代码或被删除。
`EmptyForEachBlock`	CodeQuality	警告	每个。..下一个循环是空的，应该包含代码或被删除。
`EmptyWhileWendBlock`	代码质量	警告	同时。..Wend循环为空，应包含代码或删除。
`EmptyDoWhileBlock`	CodeQuality	warning	Do…循环块为空，应包含代码或被删除。
`EmptyMethod`	CodeQuality	建议	方法体为空，应包含代码或删除。
`EmptyModule`	CodeQuality	提示	模块不包含任何声明或过程，可能是不必要的。
`ObsoleteLetStatement`	ObsoleteSyntax	建议	Let关键字已过时，应从值赋值中删除。
`ObsoleteCallStatement`	过时语法	建议	Call关键字已过时。不使用它直接调用程序
`ObsoleteGlobal`	过时语法	建议	Global关键字已过时。改用Public。
`ObsoleteWhileWendStatement`	过时的语法	建议	虽然。Wend已经过时了。使用Do While。..改为循环，以获得更好的控制流。
`ObsoleteCommentSyntax`	过时语法	建议	注释的Rem关键字已过时。请改用单引号（'）语法。
`ObsoleteTypeHint`	过时语法	建议	类型提示字符已过时。请改用显式的As Type声明。
`StopKeyword`	CodeQuality	warning	Stop语句像断点一样停止执行，应将其从生产代码中删除。
`EndKeyword`	CodeQuality	warning	Standalone End语句突然终止程序而不进行清理。
`DefTypeStatement`	过时语法	建议	DefType语句（DefBool、DefInt等）隐式类型变量，应替换为显式声明。
`OptionExplicit`	CodeQuality	警告	模块缺少Option Explicit。变量应该显式声明。
`OptionBaseZeroOrOne`	CodeQuality	提示	选项库更改了默认数组下限，可能会造成混淆。
`MultipleDeclarations`	CodeQuality	建议	在一行中声明多个变量。按自己的行声明。
`ImplicitByRefModifier`	CodeQuality	建议	参数由ByRef隐式传递。明确指定ByRef或ByVal。
`ImplicitPublicMember`	CodeQuality	建议	成员隐式为公共。明确指定公共或私有。
`ImplicitVariantReturnType`	CodeQuality	建议	函数/属性Get隐式返回变量。指定显式返回类型。
`RedundantByRefModifier`	CodeQuality	hint	ByRef是默认的参数传递机制，指定时是冗余的。
`BooleanAssignedInIfElse`	CodeQuality	建议	If/Else块将True/False分配给同一变量。简化为直接分配。
`SelfAssignedDeclaration`	CodeQuality	建议	变量使用As New，它可以自动实例化并屏蔽Nothing检查。
`UnreachableCode`	CodeQuality	警告	退出子功能、结束或转到后的代码无法访问。
`LineContinuationBetweenKeywords`	CodeQuality	警告	行连续字符拆分复合关键字，降低可读性。
`OnLocalError`	CodeQuality	建议	本地错误在功能上与错误相同。Local关键字是多余的。
`StepNotSpecified`	CodeQuality	hint	For循环未指定步骤。考虑添加一个显式的Step子句。
`StepOneIsRedundant`	CodeQuality	提示	步骤1是for循环的默认值，并且是冗余的。
`UnhandledOnErrorResumeNext`	ErrorHandling	warning	On Error Resume Next在没有相应的On Error GoTo 0的情况下用于重置错误处理。
`OnErrorGoToMinusOne`	ErrorHandling	warning	On Error GoTo-1清除当前错误对象。确保这是故意的。
`EmptyStringLiteral`	性能	提示	使用vbNullString而不是“”以获得更好的性能。
`IsMissingOnInappropriateArgument`	CodeQuality	hint	IsMissing仅适用于Optional Variant参数。验证参数类型。
`IsMissingWithNonArgumentParameter`	使用非参数参数调用CodeQuality	warning	IsMissing。IsMissing仅适用于程序参数。
`ImplicitActiveSheetReference`	Excel	建议	未限定的区域/单元格/行/列隐式引用了ActiveSheet。
`ImplicitActiveWorkbookReference`	Excel	建议	不合格的工作表/工作表/名称隐式引用ActiveWorkbook。
`SheetAccessedUsingString`	Excel	建议	按字符串名称访问工作表很脆弱。请改用工作表代号属性。
`ApplicationWorksheetFunction`	Excel	提示	应用程序。工作表功能冗余。直接使用工作表功能。
`ExcelMemberMayReturnNothing`	Excel	警告	查找/FindNext/FindPrevious可能会返回“无”。使用前检查结果
`ExcelUdfNameIsValidCellReference`	Excel	警告	函数名看起来像单元格引用（例如A1、B2），不能用作Excel公式中的UDF。

B级：符号感知检查（22）

这些检查需要符号解析（声明收集+参考解析）。它们在内联代码和工作区扫描上运行，工作区扫描提供跨模块解析。

ID	类别	严重性	描述
`VariableNotUsed`	CodeQuality	警告	变量已声明但从未被引用。
`ParameterNotUsed`	CodeQuality	建议	参数已声明，但从未在过程体中引用。
`NonReturningFunction`	CodeQuality	警告	函数或属性Get从不分配返回值。
`ConstantNotUsed`	CodeQuality	警告	常量已声明但从未被引用。
`ProcedureNotUsed`	CodeQuality	建议	从不调用私有过程。
`LineLabelNotUsed`	CodeQuality	建议	行标签已声明，但从未被GoTo或GoSub引用。
`VariableNotAssigned`	CodeQuality	警告	变量被引用，但从未被赋值。
`HungarianNotation`	命名	建议	变量名称使用匈牙利符号前缀。
`UseMeaningfulName`	命名	建议	变量名太短，没有意义。
`UnderscoreInPublicClassModuleMember`	命名	警告	公共成员名称包含下划线，这可能与VBA接口分派冲突。
`ObjectVariableNotSet`	CodeQuality	错误	分配给不带Set关键字的对象变量。
`IntegerDataType`	LanguageOpportunities	建议	使用整数类型——现代VBA中首选Long。
`VariableTypeNotDeclared`	LanguageOpportunities	建议	变量声明时没有显式类型（隐式变量）。
`ModuleScopeDimKeyword`	CodeQuality	建议	模块级变量使用Dim而不是Private。
`EncapsulatePublicField`	CodeQuality	建议	类模块中的公共变量应使用Property过程。
`MoveFieldCloserToUsage`	CodeQuality	建议	模块级变量仅在一个过程中使用--可以是本地变量。
`FunctionReturnValueNotUsed`	CodeQuality	建议	函数返回值总是被调用者丢弃。
`FunctionReturnValueAlwaysDiscarded`	CodeQuality	建议	函数返回值从不在任何调用站点使用——考虑转换为Sub
`ProcedureCanBeWrittenAsFunction`	LanguageOpportunities	建议	将子赋值给ByRef参数--可以改为Function。
`ExcessiveParameters`	CodeQuality	建议	过程参数太多。
`ParameterCanBeByVal`	CodeQuality	建议	ByRef参数从未分配给--可能是ByVal。
`UnassignedVariableUsage`	CodeQuality	警告	变量在赋值之前已被使用。

配置

主机库

这 hostLibraries 参数控制运行哪些特定于主机的检查。默认值为 ["excel"].Excel特定检查（ImplicitActiveSheetReference等）仅在以下情况下运行 "excel" 包括在内。

`.vbalintignore`

对于工作区扫描，创建 .vbalintignore 使用glob模式排除文件的文件：

# Ignore generated code
generated/**
*.generated.bas

# Ignore test fixtures
test/**

计划功能

设计了以下功能，但 尚未实现:

`.vbalintrc.json` （计划中）

用于自定义严重性覆盖和默认主机库的项目级配置文件：

{
  "hostLibraries": ["excel"],
  "severity": {
    "EmptyIfBlock": "error",
    "StepNotSpecified": "off"
  }
}

`@Ignore` 注释抑制（计划中）

使用VBA注释注释内联抑制特定检查：

'@Ignore EmptyIfBlock
If condition Then
End If

'@Ignore EmptyIfBlock, ObsoleteLetStatement

码头工人

构建

docker build -t vba-lint-mcp .

使用Docker Compose运行

docker compose build
docker compose run --rm vba-lint

MCP服务器使用stdio传输（stdin/stdout JSON-RPC），因此必须以交互方式运行(docker compose run)，未分离(docker compose up).

装载VBA文件以进行工作区扫描

编辑 docker-compose.yml 要装载VBA项目目录，请执行以下操作：

services:
  vba-lint:
    build: .
    stdin_open: true
    volumes:
      - ./my-vba-project:/data:ro

然后使用 vba/inspect-workspace 工具与 path: "/data".

图像大小

运行时映像使用 node:22-alpine 非root用户。包含源文件以符合GPL-3.0标准。

发展

设置

npm install
npm run generate-parser   # Requires Java 17+
npm run build

测试

npm test                  # All tests
npm run test:watch        # Watch mode
npx vitest run <path>     # Specific test

添加检查

看贡献.md 获取添加新检查的分步指南。

项目结构

src/
  server.ts              # MCP server entry point
  inspections/
    base.ts              # Inspection contracts
    registry.ts          # Master registration
    runner.ts            # Tiered execution engine
    parse-tree/          # Tier A inspections (by category)
    declaration/         # Tier B inspections
  parser/                # ANTLR4 parser facade
  symbols/               # Symbol resolution (Tier B)
  annotations/           # @Ignore annotation parsing
grammar/
  VBALexer.g4            # ANTLR4 lexer grammar (from Rubberduck)
  VBAParser.g4           # ANTLR4 parser grammar (from Rubberduck)

已知限制

条件编译 (#If, #Const, #Else)未进行预处理。所有分支都被解析为活动代码，这可能会在使用条件编译的模块中产生误报。
C级检查 （COM类型库依赖、Rubberduck注释系统、VBE运行时）超出范围。看计划.md 查看完整列表。

归因

这个项目是橡胶鸭VBAVBA语法和检查逻辑是从Rubberduck的C#代码库翻译而来的。

看属性.md 完整的归因、衍生作品表和贡献者确认。

许可证

该项目根据 GNU通用公共许可证v3.0。参见许可证全文。

根据GPL-3.0：

所有派生检查逻辑都保留了Rubberduck VBA的属性
每个派生文件都包含一个每个文件的版权标头
Docker镜像包含完整的源代码（GPL-3.0第6节）
本项目的消费者必须遵守GPL-3.0条款

使用说明

vba-lint mcp

概述

快速开始

安装

在Claude代码中配置

第一次检查

工具

vba/inspect

vba/inspect-workspace

vba/list-inspections

vba/parse

检验目录

A级：解析树检查（43）

B级：符号感知检查（22）

配置

主机库

.vbalintignore

计划功能

.vbalintrc.json （计划中）

@Ignore 注释抑制（计划中）

码头工人

构建

使用Docker Compose运行

装载VBA文件以进行工作区扫描

图像大小

发展

设置

测试

添加检查

项目结构

已知限制

归因

许可证

相关 MCP

代码安全扫描工具

JADX APK逆向分析MCP插件

Ghidra逆向工程MCP服务器

MCP安全扫描工具

静态代码分析服务

APK逆向分析MCP服务器