xlsx-for-ai 2.26.0 → 2.26.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/annotations.js +122 -0
- package/package.json +6 -3
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* MCP tool annotations — canonical source.
|
|
5
|
+
*
|
|
6
|
+
* Per MCP spec (2025-06-18+) tool annotations describe runtime behavior:
|
|
7
|
+
* - title Human-readable tool name
|
|
8
|
+
* - readOnlyHint Tool does NOT modify its environment
|
|
9
|
+
* - destructiveHint Tool may perform irreversible side-effects
|
|
10
|
+
*
|
|
11
|
+
* The annotations live here rather than inline on each tool definition so:
|
|
12
|
+
* 1. They overlay onto tools regardless of source — static fallback,
|
|
13
|
+
* cached catalog, or freshly-fetched remote. The remote /api/v1/tools/list
|
|
14
|
+
* currently returns minimal entries; this overlay restores the
|
|
15
|
+
* annotations the wire format would otherwise drop.
|
|
16
|
+
* 2. They drive manifest generation downstream (MCPB, M365 declarative
|
|
17
|
+
* agent, future OpenAPI). One annotation change → all manifests
|
|
18
|
+
* regenerate consistently.
|
|
19
|
+
*
|
|
20
|
+
* Classification rules:
|
|
21
|
+
* - readOnlyHint: true → tool only reads; never writes a file or causes
|
|
22
|
+
* an externally observable side-effect.
|
|
23
|
+
* - destructiveHint: true → tool causes an irreversible external action
|
|
24
|
+
* (e.g., posts to a third-party system).
|
|
25
|
+
* Note: tools that write a NEW file (Save-As shape) are NOT destructive
|
|
26
|
+
* even though readOnlyHint is false — the source workbook is preserved.
|
|
27
|
+
* destructiveHint is reserved for actions that cannot be undone by
|
|
28
|
+
* deleting the output, which means external side-effects.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
const TOOL_ANNOTATIONS = Object.freeze({
|
|
32
|
+
// ---- Reading / inspection: 35 read-only tools -------------------------
|
|
33
|
+
xlsx_read: { title: 'Read Excel file', readOnlyHint: true, destructiveHint: false },
|
|
34
|
+
xlsx_list_sheets: { title: 'List Excel sheets', readOnlyHint: true, destructiveHint: false },
|
|
35
|
+
xlsx_schema: { title: 'Infer Excel column types', readOnlyHint: true, destructiveHint: false },
|
|
36
|
+
xlsx_diff: { title: 'Diff two Excel workbooks', readOnlyHint: true, destructiveHint: false },
|
|
37
|
+
xlsx_describe: { title: 'Summarize Excel columns', readOnlyHint: true, destructiveHint: false },
|
|
38
|
+
xlsx_filter: { title: 'Filter Excel rows', readOnlyHint: true, destructiveHint: false },
|
|
39
|
+
xlsx_aggregate: { title: 'Group-by aggregate Excel rows', readOnlyHint: true, destructiveHint: false },
|
|
40
|
+
xlsx_named_ranges: { title: 'List Excel named ranges', readOnlyHint: true, destructiveHint: false },
|
|
41
|
+
xlsx_sort: { title: 'Sort Excel rows', readOnlyHint: true, destructiveHint: false },
|
|
42
|
+
xlsx_value_counts: { title: 'Count Excel column values', readOnlyHint: true, destructiveHint: false },
|
|
43
|
+
xlsx_formulas: { title: 'Inspect Excel formulas', readOnlyHint: true, destructiveHint: false },
|
|
44
|
+
xlsx_tables: { title: 'List Excel tables', readOnlyHint: true, destructiveHint: false },
|
|
45
|
+
xlsx_pivot: { title: 'Pivot Excel data', readOnlyHint: true, destructiveHint: false },
|
|
46
|
+
xlsx_eval: { title: 'Evaluate Excel formula', readOnlyHint: true, destructiveHint: false },
|
|
47
|
+
xlsx_validate: { title: 'Cross-engine validate Excel', readOnlyHint: true, destructiveHint: false },
|
|
48
|
+
xlsx_data_validations: { title: 'List Excel data-validation rules', readOnlyHint: true, destructiveHint: false },
|
|
49
|
+
xlsx_hyperlinks: { title: 'List Excel hyperlinks', readOnlyHint: true, destructiveHint: false },
|
|
50
|
+
xlsx_topology: { title: 'Map Excel sheet topology', readOnlyHint: true, destructiveHint: false },
|
|
51
|
+
xlsx_conditional_formats: { title: 'List Excel conditional formats', readOnlyHint: true, destructiveHint: false },
|
|
52
|
+
xlsx_comments: { title: 'List Excel comments', readOnlyHint: true, destructiveHint: false },
|
|
53
|
+
xlsx_doctor: { title: 'Audit Excel workbook health', readOnlyHint: true, destructiveHint: false },
|
|
54
|
+
xlsx_form_controls: { title: 'List Excel form controls', readOnlyHint: true, destructiveHint: false },
|
|
55
|
+
xlsx_macros: { title: 'List Excel VBA macros', readOnlyHint: true, destructiveHint: false },
|
|
56
|
+
xlsx_merged_cells: { title: 'List Excel merged cells', readOnlyHint: true, destructiveHint: false },
|
|
57
|
+
xlsx_workbook_views: { title: 'List Excel workbook views', readOnlyHint: true, destructiveHint: false },
|
|
58
|
+
xlsx_print_settings: { title: 'List Excel print settings', readOnlyHint: true, destructiveHint: false },
|
|
59
|
+
xlsx_properties: { title: 'Read Excel document properties', readOnlyHint: true, destructiveHint: false },
|
|
60
|
+
xlsx_external_links: { title: 'List Excel external links', readOnlyHint: true, destructiveHint: false },
|
|
61
|
+
xlsx_slicers_timelines: { title: 'List Excel slicers and timelines', readOnlyHint: true, destructiveHint: false },
|
|
62
|
+
xlsx_pivot_tables: { title: 'List Excel pivot tables', readOnlyHint: true, destructiveHint: false },
|
|
63
|
+
xlsx_images: { title: 'List Excel embedded images', readOnlyHint: true, destructiveHint: false },
|
|
64
|
+
xlsx_charts: { title: 'List Excel charts', readOnlyHint: true, destructiveHint: false },
|
|
65
|
+
xlsx_protection: { title: 'List Excel protection settings', readOnlyHint: true, destructiveHint: false },
|
|
66
|
+
xlsx_styles: { title: 'List Excel cell styles', readOnlyHint: true, destructiveHint: false },
|
|
67
|
+
xlsx_verify_stamp: { title: 'Verify Excel integrity stamp', readOnlyHint: true, destructiveHint: false },
|
|
68
|
+
|
|
69
|
+
// ---- Writing — non-destructive: 5 Save-As-shape tools -----------------
|
|
70
|
+
// Source workbook is preserved; output goes to a new path or returned bytes.
|
|
71
|
+
xlsx_write: { title: 'Write Excel file', readOnlyHint: false, destructiveHint: false },
|
|
72
|
+
xlsx_redact: { title: 'Redact Excel file', readOnlyHint: false, destructiveHint: false },
|
|
73
|
+
xlsx_convert: { title: 'Convert Excel to other format', readOnlyHint: false, destructiveHint: false },
|
|
74
|
+
xlsx_data_clean: { title: 'Clean Excel data', readOnlyHint: false, destructiveHint: false },
|
|
75
|
+
xlsx_stamp: { title: 'Stamp Excel with integrity verification', readOnlyHint: false, destructiveHint: false },
|
|
76
|
+
|
|
77
|
+
// ---- External side-effects — destructive: 2 tools ---------------------
|
|
78
|
+
// A post can't be undone; the message lands in a third-party system.
|
|
79
|
+
xlsx_post_slack: { title: 'Post Excel summary to Slack', readOnlyHint: false, destructiveHint: true },
|
|
80
|
+
xlsx_post_teams: { title: 'Post Excel summary to Teams', readOnlyHint: false, destructiveHint: true },
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Overlay annotations onto an MCP-shaped tool array.
|
|
85
|
+
*
|
|
86
|
+
* Returns a new array with each tool extended with an `annotations` object
|
|
87
|
+
* pulled from TOOL_ANNOTATIONS by name. Tools without a known annotation
|
|
88
|
+
* pass through unchanged — this is intentional so that a dynamically-
|
|
89
|
+
* discovered tool the client doesn't recognize still appears, just without
|
|
90
|
+
* the annotation hints. The annotation map should be updated whenever
|
|
91
|
+
* a new tool is added to the server.
|
|
92
|
+
*/
|
|
93
|
+
// Keys we refuse to copy from upstream annotation objects — guards against
|
|
94
|
+
// prototype-pollution if a remote /api/v1/tools/list ever returns hostile
|
|
95
|
+
// data. Our overlay map is a frozen const so it's safe to spread directly;
|
|
96
|
+
// the danger is only the foreign `existing` object.
|
|
97
|
+
const POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
|
|
98
|
+
|
|
99
|
+
function applyAnnotations(tools) {
|
|
100
|
+
if (!Array.isArray(tools)) return tools;
|
|
101
|
+
return tools.map((t) => {
|
|
102
|
+
if (!t || typeof t.name !== 'string') return t;
|
|
103
|
+
const ann = TOOL_ANNOTATIONS[t.name];
|
|
104
|
+
if (!ann) return t;
|
|
105
|
+
// Preserve any annotations the upstream source already carries; ours fill
|
|
106
|
+
// in the gaps without clobbering richer remote data. Reject pollution
|
|
107
|
+
// keys and non-plain-object inputs.
|
|
108
|
+
const merged = { ...ann };
|
|
109
|
+
if (t.annotations && typeof t.annotations === 'object' && !Array.isArray(t.annotations)) {
|
|
110
|
+
for (const [k, v] of Object.entries(t.annotations)) {
|
|
111
|
+
if (POLLUTION_KEYS.has(k)) continue;
|
|
112
|
+
merged[k] = v;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
return { ...t, annotations: merged };
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
module.exports = {
|
|
120
|
+
TOOL_ANNOTATIONS,
|
|
121
|
+
applyAnnotations,
|
|
122
|
+
};
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xlsx-for-ai",
|
|
3
3
|
"mcpName": "io.github.senoff/xlsx-for-ai",
|
|
4
|
-
"version": "2.26.
|
|
4
|
+
"version": "2.26.1",
|
|
5
5
|
"description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"bin": {
|
|
@@ -12,11 +12,12 @@
|
|
|
12
12
|
"files": [
|
|
13
13
|
"index.js",
|
|
14
14
|
"mcp.js",
|
|
15
|
+
"lib/annotations.js",
|
|
15
16
|
"lib/client.js",
|
|
16
17
|
"lib/config.js",
|
|
17
|
-
"lib/register.js",
|
|
18
|
-
"lib/fallback-read.js",
|
|
19
18
|
"lib/discover.js",
|
|
19
|
+
"lib/fallback-read.js",
|
|
20
|
+
"lib/register.js",
|
|
20
21
|
"README.md",
|
|
21
22
|
"SECURITY.md",
|
|
22
23
|
"LICENSE"
|
|
@@ -25,6 +26,8 @@
|
|
|
25
26
|
"test": "node --test test/v2/*.test.js",
|
|
26
27
|
"build-manifests": "node scripts/build-manifests.js",
|
|
27
28
|
"check-manifests": "node scripts/build-manifests.js --check",
|
|
29
|
+
"check-publish-allowlist": "node scripts/check-publish-allowlist.js",
|
|
30
|
+
"prepublishOnly": "node scripts/check-publish-allowlist.js && node scripts/build-manifests.js --check",
|
|
28
31
|
"prepare": "husky"
|
|
29
32
|
},
|
|
30
33
|
"keywords": [
|