excel_mcp_server/types/
responses.rs

1use serde::{Deserialize, Serialize};
2
3/// Status indicator for all tool responses.
4#[derive(Debug, Serialize)]
5#[serde(rename_all = "snake_case")]
6pub enum Status {
7    Success,
8    Error,
9}
10
11/// Structured response wrapper returned by every tool.
12#[derive(Debug, Serialize)]
13pub struct ToolResponse<T: Serialize> {
14    pub status: Status,
15    pub message: String,
16    #[serde(skip_serializing_if = "Option::is_none")]
17    pub data: Option<T>,
18}
19
20/// Error payload included in error responses.
21#[derive(Debug, Serialize)]
22pub struct ErrorData {
23    pub category: ErrorCategory,
24    pub description: String,
25    pub suggestion: String,
26}
27
28/// Categorises the kind of error that occurred.
29#[derive(Debug, Serialize)]
30#[serde(rename_all = "snake_case")]
31pub enum ErrorCategory {
32    NotFound,
33    InvalidInput,
34    EngineUnsupported,
35    CapacityExceeded,
36    IoError,
37    ParseError,
38    Evicted,
39}
40
41/// Build a success response with data, serialised to JSON.
42pub fn success<T: Serialize>(message: &str, data: T) -> String {
43    serde_json::to_string(&ToolResponse {
44        status: Status::Success,
45        message: message.to_string(),
46        data: Some(data),
47    })
48    .expect("serialization of ToolResponse should never fail")
49}
50
51/// Build a success response without data, serialised to JSON.
52pub fn success_no_data(message: &str) -> String {
53    serde_json::to_string(&ToolResponse::<()> {
54        status: Status::Success,
55        message: message.to_string(),
56        data: None,
57    })
58    .expect("serialization of ToolResponse should never fail")
59}
60
61/// Build an error response, serialised to JSON.
62pub fn error(category: ErrorCategory, description: &str, suggestion: &str) -> String {
63    serde_json::to_string(&ToolResponse {
64        status: Status::Error,
65        message: description.to_string(),
66        data: Some(ErrorData {
67            category,
68            description: description.to_string(),
69            suggestion: suggestion.to_string(),
70        }),
71    })
72    .expect("serialization of ToolResponse should never fail")
73}
74
75/// Data returned when a workbook is created or opened.
76#[derive(Debug, Serialize)]
77pub struct WorkbookInfo {
78    pub workbook_id: String,
79    pub engine: String,
80    pub sheets: Vec<SheetSummary>,
81}
82
83/// Summary of a single sheet within a workbook.
84#[derive(Debug, Serialize)]
85pub struct SheetSummary {
86    pub name: String,
87    pub dimensions: Option<String>,
88    pub row_count: Option<u32>,
89    pub col_count: Option<u16>,
90}
91
92/// Paginated read result for sheet data.
93#[derive(Debug, Serialize)]
94pub struct ReadSheetData {
95    pub rows: Vec<Vec<serde_json::Value>>,
96    pub total_rows: u32,
97    pub page_rows: u32,
98    pub continuation_token: Option<String>,
99}
100
101/// Single cell read result.
102#[derive(Debug, Serialize)]
103pub struct CellData {
104    pub cell: String,
105    pub value: serde_json::Value,
106    pub value_type: String,
107    pub formula: Option<String>,
108}
109
110/// Write confirmation returned after cell writes.
111#[derive(Debug, Serialize)]
112pub struct WriteResult {
113    pub cells_written: usize,
114    pub range_covered: String,
115}
116
117/// Search result containing matching cells.
118#[derive(Debug, Serialize)]
119pub struct SearchResult {
120    pub matches: Vec<SearchMatch>,
121    pub total_matches: usize,
122    pub truncated: bool,
123}
124
125/// A single cell match from a search operation.
126#[derive(Debug, Serialize)]
127pub struct SearchMatch {
128    pub sheet: String,
129    pub cell: String,
130    pub value: serde_json::Value,
131}
132
133/// Full workbook description with sample data per sheet.
134#[derive(Debug, Serialize)]
135pub struct WorkbookDescription {
136    pub workbook_id: String,
137    pub engine: String,
138    pub sheets: Vec<SheetDescription>,
139}
140
141/// Sheet description including dimensions and sample rows.
142#[derive(Debug, Serialize)]
143pub struct SheetDescription {
144    pub name: String,
145    pub dimensions: Option<String>,
146    pub row_count: Option<u32>,
147    pub col_count: Option<u16>,
148    pub sample_rows: Vec<Vec<serde_json::Value>>,
149}
150
151/// CSV export result.
152#[derive(Debug, Serialize)]
153pub struct CsvExportData {
154    pub csv: String,
155    pub total_rows: u32,
156    pub truncated: bool,
157}
158
159/// Continuation token for paginated read_sheet responses.
160#[derive(Debug, Serialize, Deserialize)]
161pub struct ContinuationToken {
162    pub sheet: String,
163    pub offset: u32,
164    pub range: Option<String>,
165}
excel_mcp_server/types/responses.rs

excel_mcp_server/types/
responses.rs
