spreadsheet-mcp 0.10.1

Stateful MCP server for spreadsheet analysis and editing — token-efficient tools for LLM agents to read, profile, edit, and recalculate .xlsx workbooks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

use crate::core::write::{normalize_object_edit, normalize_shorthand_edit};
use crate::errors::InvalidParamsError;
use crate::model::Warning;
use crate::tools::fork::{CellEdit, EditBatchParams};
use anyhow::Result;
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Clone, Deserialize, JsonSchema)]
pub struct EditBatchParamsInput {
    pub fork_id: String,
    pub sheet_name: String,
    pub edits: Vec<CellEditInput>,
}

#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum CellEditInput {
    Shorthand(String),
    Object(CellEditV2),
}

#[derive(Debug, Clone, Deserialize, JsonSchema)]
pub struct CellEditV2 {
    pub address: String,
    #[serde(default)]
    pub value: Option<String>,
    #[serde(default)]
    pub formula: Option<String>,
    #[serde(default)]
    pub is_formula: Option<bool>,
}

pub fn normalize_edit_batch(
    params: EditBatchParamsInput,
) -> Result<(EditBatchParams, Vec<Warning>)> {
    let mut warnings = Vec::new();
    let mut edits = Vec::with_capacity(params.edits.len());

    for (idx, edit) in params.edits.into_iter().enumerate() {
        match edit {
            CellEditInput::Shorthand(entry) => {
                let (normalized, core_warnings) =
                    normalize_shorthand_edit(&entry).map_err(|err| {
                        InvalidParamsError::new("edit_batch", err.to_string())
                            .with_path(format!("edits[{idx}]"))
                    })?;
                edits.push(CellEdit {
                    address: normalized.address,
                    value: normalized.value,
                    is_formula: normalized.is_formula,
                });
                warnings.extend(core_warnings.into_iter().map(|warning| Warning {
                    code: warning.code,
                    message: warning.message,
                }));
            }
            CellEditInput::Object(obj) => {
                let normalized =
                    normalize_object_edit(&obj.address, obj.value, obj.formula, obj.is_formula)
                        .map_err(|err| {
                            let path = if err.to_string().contains("address") {
                                format!("edits[{idx}].address")
                            } else {
                                format!("edits[{idx}]")
                            };
                            InvalidParamsError::new("edit_batch", err.to_string()).with_path(path)
                        })?;

                edits.push(CellEdit {
                    address: normalized.0.address,
                    value: normalized.0.value,
                    is_formula: normalized.0.is_formula,
                });
                warnings.extend(normalized.1.into_iter().map(|warning| Warning {
                    code: warning.code,
                    message: warning.message,
                }));
            }
        }
    }

    Ok((
        EditBatchParams {
            fork_id: params.fork_id,
            sheet_name: params.sheet_name,
            edits,
        },
        warnings,
    ))
}