Initial VBA tool

Author: PSU3D0

Cargo.lock

@@ -22,6 +22,7 @@ lru = "0.12"
 ahash = "0.8"
 smallvec = "1.13"
 umya-spreadsheet = "2.3.3"
+ovba = "0.7.1"
 formualizer-parse = { version = "0.1.0" }
 walkdir = "2.5"
 globset = "0.4"
@@ -43,14 +44,14 @@ base64 = { version = "0.22", optional = true }
 
 async-trait = { version = "0.1", optional = true }
 uuid = { version = "1.10", features = ["v4"], optional = true }
-zip = { version = "0.6", optional = true }
+zip = "0.6"
 quick-xml = { version = "0.31", optional = true }
 xxhash-rust = { version = "0.8", features = ["xxh64"], optional = true }
 tempfile = "3.10"
 
 [features]
 default = []
-recalc = ["async-trait", "uuid", "zip", "quick-xml", "xxhash-rust", "image", "base64"]
+recalc = ["async-trait", "uuid", "quick-xml", "xxhash-rust", "image", "base64"]
 docker-tests = []
 
 [dev-dependencies]

Cargo.toml

@@ -12,7 +12,8 @@ MCP server for spreadsheet analysis and editing. Slim, token-efficient tool surf
 
 Dumping a 50,000-row spreadsheet into an LLM context is expensive and usually unnecessary. Most spreadsheet tasks need surgical access: find a region, profile its structure, read a filtered slice. This server exposes tools that let agents **discover → profile → extract** without burning tokens on cells they don't need.
 
-- **Full support:** `.xlsx` (via `umya-spreadsheet`)
+- **Full support:** `.xlsx`, `.xlsm` (via `umya-spreadsheet`)
+- **VBA source inspection (optional):** `.xlsm` via `SPREADSHEET_MCP_VBA_ENABLED=true` / `--vba-enabled` (parses embedded `xl/vbaProject.bin` via `ovba`)
 - **Discovery only:** `.xls`, `.xlsb` (enumerated, not parsed)
 
 ## Architecture
@@ -36,9 +37,26 @@ Dumping a 50,000-row spreadsheet into an LLM context is expensive and usually un
 | `sheet_formula_map`, `formula_trace`, `scan_volatiles` | Formula analysis and tracing |
 | `sheet_styles`, `workbook_style_summary` | Style inspection (sheet-scoped + workbook-wide) |
 | `named_ranges` | List defined names + tables |
+| `vba_project_summary`, `vba_module_source` | Read VBA project metadata + module source (disabled by default; `.xlsm`) |
 | `get_manifest_stub` | Generate manifest scaffold |
 | `close_workbook` | Evict workbook from cache |
 
+## VBA Support (Read-Only)
+
+VBA tools are **disabled by default**. When enabled, the server can extract and parse the embedded VBA project from `.xlsm` files and return module source code.
+
+Enable via:
+- CLI: `--vba-enabled`
+- Env: `SPREADSHEET_MCP_VBA_ENABLED=true`
+
+Tools:
+- `vba_project_summary`: Lists modules + basic project metadata
+- `vba_module_source`: Returns paged source for a single module
+
+Notes:
+- This does **not** execute macros; it only reads and returns text.
+- Responses are size-limited; page through module source.
+
 ## Write & Recalc Support
 
 Write tools allow "what-if" analysis: fork a workbook, edit cells, recalculate formulas via LibreOffice, and diff the results. For safety, you can create checkpoints for high‑fidelity rollback and apply previewed (staged) changes explicitly.
@@ -201,6 +219,9 @@ Two image variants are published:
 # Read-only (slim image)
 docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:latest
 
+# Read-only + VBA tools enabled
+docker run -v /path/to/workbooks:/data -p 8079:8079 -e SPREADSHEET_MCP_VBA_ENABLED=true ghcr.io/psu3d0/spreadsheet-mcp:latest
+
 # With write/recalc support (full image)
 docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:full
 ```
@@ -211,6 +232,9 @@ docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-m
 # Read-only
 cargo install spreadsheet-mcp
 spreadsheet-mcp --workspace-root /path/to/workbooks
+
+# Enable VBA tools
+SPREADSHEET_MCP_VBA_ENABLED=true spreadsheet-mcp --workspace-root /path/to/workbooks
 ```
 
 **Note:** For write/recalc features, use the `:full` Docker image instead of cargo install. The Docker image includes LibreOffice with required macro configuration.
@@ -243,13 +267,25 @@ Add to `~/.claude.json` or project `.mcp.json`:
 }
 ```
 
+**Read-only + VBA tools enabled:**
+```json
+{
+  "mcpServers": {
+    "spreadsheet": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio", "--vba-enabled"]
+    }
+  }
+}
+```
+
 **With write/recalc (full image):**
 ```json
 {
   "mcpServers": {
     "spreadsheet": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "-i", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
+      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
     }
   }
 }
@@ -275,7 +311,7 @@ Add to `~/.claude.json` or project `.mcp.json`:
   "mcp.servers": {
     "spreadsheet": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "-i",  "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio"]
+      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio"]
     }
   }
 }
@@ -287,7 +323,7 @@ Add to `~/.claude.json` or project `.mcp.json`:
   "mcp.servers": {
     "spreadsheet": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "-i", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
+      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
     }
   }
 }

README.md

@@ -8,7 +8,7 @@ use std::path::{Path, PathBuf};
 
 const DEFAULT_CACHE_CAPACITY: usize = 5;
 const DEFAULT_MAX_RECALCS: usize = 2;
-const DEFAULT_EXTENSIONS: &[&str] = &["xlsx", "xls", "xlsb"];
+const DEFAULT_EXTENSIONS: &[&str] = &["xlsx", "xlsm", "xls", "xlsb"];
 const DEFAULT_HTTP_BIND: &str = "127.0.0.1:8079";
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Serialize, Deserialize)]
@@ -39,6 +39,7 @@ pub struct ServerConfig {
     pub transport: TransportKind,
     pub http_bind_address: SocketAddr,
     pub recalc_enabled: bool,
+    pub vba_enabled: bool,
     pub max_concurrent_recalcs: usize,
     pub allow_overwrite: bool,
 }
@@ -55,6 +56,7 @@ impl ServerConfig {
             transport: cli_transport,
             http_bind: cli_http_bind,
             recalc_enabled: cli_recalc_enabled,
+            vba_enabled: cli_vba_enabled,
             max_concurrent_recalcs: cli_max_concurrent_recalcs,
             allow_overwrite: cli_allow_overwrite,
         } = args;
@@ -74,6 +76,7 @@ impl ServerConfig {
             transport: file_transport,
             http_bind: file_http_bind,
             recalc_enabled: file_recalc_enabled,
+            vba_enabled: file_vba_enabled,
             max_concurrent_recalcs: file_max_concurrent_recalcs,
             allow_overwrite: file_allow_overwrite,
         } = file_config;
@@ -174,6 +177,7 @@ impl ServerConfig {
         });
 
         let recalc_enabled = cli_recalc_enabled || file_recalc_enabled.unwrap_or(false);
+        let vba_enabled = cli_vba_enabled || file_vba_enabled.unwrap_or(false);
 
         let max_concurrent_recalcs = cli_max_concurrent_recalcs
             .or(file_max_concurrent_recalcs)
@@ -191,6 +195,7 @@ impl ServerConfig {
             transport,
             http_bind_address,
             recalc_enabled,
+            vba_enabled,
             max_concurrent_recalcs,
             allow_overwrite,
         })
@@ -321,6 +326,13 @@ pub struct CliArgs {
     )]
     pub recalc_enabled: bool,
 
+    #[arg(
+        long,
+        env = "SPREADSHEET_MCP_VBA_ENABLED",
+        help = "Enable VBA introspection tools (read-only)"
+    )]
+    pub vba_enabled: bool,
+
     #[arg(
         long,
         env = "SPREADSHEET_MCP_MAX_CONCURRENT_RECALCS",
@@ -346,6 +358,7 @@ struct PartialConfig {
     transport: Option<TransportKind>,
     http_bind: Option<SocketAddr>,
     recalc_enabled: Option<bool>,
+    vba_enabled: Option<bool>,
     max_concurrent_recalcs: Option<usize>,
     allow_overwrite: Option<bool>,
 }

src/config.rs

@@ -814,3 +814,47 @@ pub struct CloseWorkbookResponse {
     pub workbook_id: WorkbookId,
     pub message: String,
 }
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct VbaProjectSummaryResponse {
+    pub workbook_id: WorkbookId,
+    pub workbook_short_id: String,
+    pub has_vba: bool,
+    pub code_page: Option<u16>,
+    pub sys_kind: Option<String>,
+    pub modules: Vec<VbaModuleDescriptor>,
+    pub modules_truncated: bool,
+    pub references: Vec<VbaReferenceDescriptor>,
+    pub references_truncated: bool,
+    pub notes: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct VbaModuleDescriptor {
+    pub name: String,
+    pub stream_name: String,
+    pub doc_string: String,
+    pub text_offset: u64,
+    pub help_context: u32,
+    pub module_type: String,
+    pub read_only: bool,
+    pub private: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct VbaReferenceDescriptor {
+    pub kind: String,
+    pub debug: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct VbaModuleSourceResponse {
+    pub workbook_id: WorkbookId,
+    pub workbook_short_id: String,
+    pub module_name: String,
+    pub offset_lines: u32,
+    pub limit_lines: u32,
+    pub total_lines: u32,
+    pub truncated: bool,
+    pub source: String,
+}