synology-office-mcp 0.4.6
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/.env.example +139 -0
- package/CHANGELOG.md +257 -0
- package/LICENSE +21 -0
- package/README.md +382 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +3969 -0
- package/dist/index.js.map +1 -0
- package/package.json +79 -0
package/.env.example
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# ============================================================
|
|
2
|
+
# REQUIRED — Synology NAS Connection
|
|
3
|
+
# ============================================================
|
|
4
|
+
|
|
5
|
+
# NAS hostname or IP address
|
|
6
|
+
SYNO_HOST=192.168.1.100
|
|
7
|
+
|
|
8
|
+
# NAS port (5000 = HTTP, 5001 = HTTPS)
|
|
9
|
+
SYNO_PORT=5001
|
|
10
|
+
|
|
11
|
+
# Use HTTPS (true/false)
|
|
12
|
+
SYNO_HTTPS=true
|
|
13
|
+
|
|
14
|
+
# Accept self-signed TLS certificate (default: false — secure-by-default).
|
|
15
|
+
# Set true ONLY for home NAS setups with self-signed certs you trust.
|
|
16
|
+
# WARNING: true disables MITM protection on the NAS connection.
|
|
17
|
+
SYNO_IGNORE_CERT=false
|
|
18
|
+
|
|
19
|
+
# DSM credentials
|
|
20
|
+
SYNO_USERNAME=your_nas_user
|
|
21
|
+
SYNO_PASSWORD=your_nas_password
|
|
22
|
+
|
|
23
|
+
# 2FA OTP code (leave empty if not using 2FA).
|
|
24
|
+
# NOTE: DSM does NOT have "Application Passwords" (that is a Google/Microsoft
|
|
25
|
+
# concept, not a Synology one). For 2-step-verification accounts, the only
|
|
26
|
+
# fully supported path for unattended automation — including the Spreadsheet
|
|
27
|
+
# container, whose /authorize endpoint does NOT accept OTP — is to create a
|
|
28
|
+
# dedicated DSM service account WITHOUT 2FA enabled.
|
|
29
|
+
SYNO_OTP_CODE=
|
|
30
|
+
|
|
31
|
+
# ============================================================
|
|
32
|
+
# OPTIONAL — Feature Flags
|
|
33
|
+
# ============================================================
|
|
34
|
+
|
|
35
|
+
SYNO_ENABLE_DRIVE=true
|
|
36
|
+
SYNO_ENABLE_SPREADSHEET=true
|
|
37
|
+
SYNO_ENABLE_MAILPLUS=true
|
|
38
|
+
SYNO_ENABLE_CALENDAR=true
|
|
39
|
+
|
|
40
|
+
# ============================================================
|
|
41
|
+
# OPTIONAL — MCP Server Transport
|
|
42
|
+
# ============================================================
|
|
43
|
+
|
|
44
|
+
# Transport mode: "stdio" or "sse"
|
|
45
|
+
MCP_TRANSPORT=stdio
|
|
46
|
+
|
|
47
|
+
# SSE port (only used when MCP_TRANSPORT=sse)
|
|
48
|
+
MCP_SSE_PORT=3100
|
|
49
|
+
|
|
50
|
+
# SSE host binding (use 127.0.0.1 for local-only)
|
|
51
|
+
MCP_SSE_HOST=127.0.0.1
|
|
52
|
+
|
|
53
|
+
# ============================================================
|
|
54
|
+
# OPTIONAL — Security
|
|
55
|
+
# ============================================================
|
|
56
|
+
|
|
57
|
+
# Shared secret for SSE mode.
|
|
58
|
+
# REQUIRED when MCP_SSE_HOST is not a loopback address (127.0.0.1 / ::1 / localhost).
|
|
59
|
+
# Server will refuse to start if SSE is bound to LAN/public host without a token.
|
|
60
|
+
MCP_AUTH_TOKEN=
|
|
61
|
+
|
|
62
|
+
# ============================================================
|
|
63
|
+
# OPTIONAL — Logging
|
|
64
|
+
# ============================================================
|
|
65
|
+
|
|
66
|
+
# Log level: "debug" | "info" | "warn" | "error"
|
|
67
|
+
LOG_LEVEL=info
|
|
68
|
+
|
|
69
|
+
# Log file path (leave empty to log to stderr only)
|
|
70
|
+
LOG_FILE=
|
|
71
|
+
|
|
72
|
+
# ============================================================
|
|
73
|
+
# OPTIONAL — Performance
|
|
74
|
+
# ============================================================
|
|
75
|
+
|
|
76
|
+
# Session token TTL in milliseconds (default: 23 hours)
|
|
77
|
+
SYNO_TOKEN_TTL_MS=82800000
|
|
78
|
+
|
|
79
|
+
# HTTP request timeout in milliseconds
|
|
80
|
+
SYNO_REQUEST_TIMEOUT_MS=30000
|
|
81
|
+
|
|
82
|
+
# ============================================================
|
|
83
|
+
# OPTIONAL — Spreadsheet REST API (Synology Office >= 3.6.0)
|
|
84
|
+
# ============================================================
|
|
85
|
+
# Used by the Spreadsheet client and scripts/smoke-spreadsheet.mjs.
|
|
86
|
+
# Defaults to SYNO_HOST when SYNO_SS_HOST is unset.
|
|
87
|
+
|
|
88
|
+
# Hostname of the synology/spreadsheet-api endpoint
|
|
89
|
+
SYNO_SS_HOST=
|
|
90
|
+
|
|
91
|
+
# Port of the spreadsheet-api endpoint (container default: 3000)
|
|
92
|
+
SYNO_SS_PORT=3000
|
|
93
|
+
|
|
94
|
+
# Use HTTPS for the spreadsheet-api endpoint (true/false)
|
|
95
|
+
SYNO_SS_HTTPS=false
|
|
96
|
+
|
|
97
|
+
# ------------------------------------------------------------
|
|
98
|
+
# Spreadsheet container's DSM back-channel (advanced, optional)
|
|
99
|
+
# ------------------------------------------------------------
|
|
100
|
+
# When you call /spreadsheets/authorize, the container makes its OWN back-call
|
|
101
|
+
# to DSM to validate credentials. Three knobs below control THAT back-call,
|
|
102
|
+
# independent of the MCP→DSM connection (SYNO_HOST/PORT/HTTPS).
|
|
103
|
+
#
|
|
104
|
+
# Why these exist: the synology/spreadsheet-api Docker image ships without
|
|
105
|
+
# DSM's self-signed CA, so HTTPS back-calls to a homelab DSM fail TLS verify
|
|
106
|
+
# and return 401 — even when credentials are correct. Pointing the back-call
|
|
107
|
+
# at DSM's HTTP port works around this without weakening MCP→DSM TLS.
|
|
108
|
+
#
|
|
109
|
+
# All three default to the matching SYNO_* value. Leave blank if DSM uses a
|
|
110
|
+
# trusted cert (or the container has the CA installed).
|
|
111
|
+
#
|
|
112
|
+
# DSM host the container should back-call (defaults to SYNO_HOST)
|
|
113
|
+
SYNO_SS_DSM_HOST=
|
|
114
|
+
#
|
|
115
|
+
# DSM port for the container's back-call (defaults to SYNO_PORT).
|
|
116
|
+
# Common: 5000 (HTTP) or your custom DSM HTTP port.
|
|
117
|
+
SYNO_SS_DSM_PORT=
|
|
118
|
+
#
|
|
119
|
+
# Use HTTPS for the container's back-call (defaults to SYNO_HTTPS).
|
|
120
|
+
# Set false when the container rejects DSM's self-signed cert.
|
|
121
|
+
SYNO_SS_DSM_HTTPS=
|
|
122
|
+
|
|
123
|
+
# ------------------------------------------------------------
|
|
124
|
+
# Notes on 401 from /spreadsheets/authorize
|
|
125
|
+
# ------------------------------------------------------------
|
|
126
|
+
# The endpoint validates DSM credentials via the container's own back-call.
|
|
127
|
+
# Common causes (most frequent first):
|
|
128
|
+
# 1. Container rejects DSM's self-signed TLS cert — set SYNO_SS_DSM_HTTPS=false
|
|
129
|
+
# and SYNO_SS_DSM_PORT to DSM's HTTP port (default 5000) to bypass.
|
|
130
|
+
# 2. Container cannot reach DSM at the back-call URL (Docker bridge, firewall,
|
|
131
|
+
# wrong host). Test from inside the container:
|
|
132
|
+
# docker exec <ss-container> curl -kv https://DSM_HOST:DSM_PORT/webapi/...
|
|
133
|
+
# 3. DSM auto-block triggered against the container's source IP. Unblock and
|
|
134
|
+
# whitelist the Docker subnet (Control Panel → Security → Account).
|
|
135
|
+
# 4. User lacks Synology Office privilege (Control Panel → Application
|
|
136
|
+
# Privileges → Synology Office).
|
|
137
|
+
# 5. Wrong DSM credentials. The endpoint does NOT accept OTP — for 2FA
|
|
138
|
+
# accounts, use a dedicated service account without 2FA enabled.
|
|
139
|
+
# DSM has NO "Application Password" feature despite what some docs claim.
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to **synology-office-mcp** are documented in this file.
|
|
4
|
+
|
|
5
|
+
The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
> Pre-1.0 status: minor versions (`0.x.0`) deliver shipping milestones from the [implementation plan](./plans/260426-1222-synology-office-mcp/plan.md). The public surface (CLI, env vars, MCP tools) may still change between minor versions until `1.0.0`.
|
|
8
|
+
|
|
9
|
+
## [Unreleased]
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## [0.4.6] - 2026-05-03
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- Landing page link at the top of `README.md` (https://synology-mcp-server.smb-base.com/).
|
|
17
|
+
- Quick Start now walks through deploying the official `synology/spreadsheet-api` Docker container, the DSM access/whitelist steps, and the homelab self-signed-cert workaround (`SYNO_SS_DSM_HTTPS=false` + `SYNO_SS_DSM_PORT=5000`).
|
|
18
|
+
- Quick Start env block expanded to cover `SYNO_SS_*` variables (host, port, https) and back-call overrides (`SYNO_SS_DSM_*`).
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
- Quick Start restructured into three numbered steps: container deploy → env vars → run server.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## [0.4.5] - 2026-05-01
|
|
26
|
+
|
|
27
|
+
### Added — Documentation refresh
|
|
28
|
+
- New `usage-guide.md` at repo root: sample natural-language prompts for every one of the 37 MCP tools, plus composite-workflow examples and tips (absolute paths, ISO 8601, register-by-name, confirm-pattern).
|
|
29
|
+
- `integration-guide.md`: added a **Remove MCP** subsection to every client section (Claude Desktop, Cursor, Continue.dev, Windsurf/Codeium, OpenAI Codex CLI, Google Antigravity, ChatGPT, BabyAGI/AutoGPT, LangChain, LlamaIndex, Generic SDK) so operators have a paired install/uninstall path.
|
|
30
|
+
|
|
31
|
+
### Changed
|
|
32
|
+
- Tool count corrected to **37** across `README.md` (Features matrix, Quick summary, Documentation table) and `tool-reference.md` (header + Spreadsheet section). Spreadsheet module grew from 8 → 13 tools.
|
|
33
|
+
- Spreadsheet section in `tool-reference.md` now documents the five tools added during 0.4.x: `spreadsheet_register`, `spreadsheet_get_styles`, `spreadsheet_batch_update`, `spreadsheet_rename_sheet`, `spreadsheet_delete_sheet`.
|
|
34
|
+
|
|
35
|
+
### Why
|
|
36
|
+
Docs had drifted behind the 0.4.x spreadsheet expansion. New users following `README.md` saw a stale tool count and missed the register-by-name flow that several spreadsheet tools rely on.
|
|
37
|
+
|
|
38
|
+
### Verified
|
|
39
|
+
- Security scan across `src/`, `tests/`, and all root `*.md` documents: zero hard-coded credentials, private keys, or real tokens. Only placeholders (`your_password`, `192.168.1.100`) and intentional test fixtures (with redaction tests in `tests/utils/logger.test.ts`).
|
|
40
|
+
- `git ls-files` confirms only `.env.example` is tracked; `.env*` remains gitignored.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## [0.4.4] - 2026-04-30
|
|
45
|
+
|
|
46
|
+
### Added — Independent DSM back-channel for the Spreadsheet container
|
|
47
|
+
- New env vars `SYNO_SS_DSM_HOST` / `SYNO_SS_DSM_PORT` / `SYNO_SS_DSM_HTTPS` control the URL the Spreadsheet container uses to back-call DSM (the `host` / `protocol` fields in `/spreadsheets/authorize`). Each falls back to the matching `SYNO_*` value when unset, so existing setups keep working.
|
|
48
|
+
- New `SynologyConfig` fields: `spreadsheetDsmHost`, `spreadsheetDsmPort`, `spreadsheetDsmHttps`.
|
|
49
|
+
|
|
50
|
+
### Why
|
|
51
|
+
The `synology/spreadsheet-api` Docker image ships without DSM's self-signed CA, so HTTPS back-calls to a homelab DSM fail TLS verification and the container returns `401 Unauthorized` even when credentials are correct. Previously the back-call URL was hard-wired to `SYNO_HOST/PORT/HTTPS`, forcing operators to choose between (a) downgrading the entire MCP→DSM connection to HTTP or (b) installing a CA inside the container. With this change, only the container's back-call is downgraded to HTTP — MCP→DSM stays on HTTPS as configured.
|
|
52
|
+
|
|
53
|
+
### Fixed — Auth-failure error hint
|
|
54
|
+
- Reordered 401 root-cause hint by observed frequency (TLS verify first, not 2FA).
|
|
55
|
+
- Removed incorrect references to "DSM Application Password" — DSM has no such feature; the previous hint sent operators chasing a menu that does not exist.
|
|
56
|
+
- Hint now points operators at the new `SYNO_SS_DSM_*` knobs as the primary fix.
|
|
57
|
+
|
|
58
|
+
### Documentation
|
|
59
|
+
- `.env.example`: documented all three `SYNO_SS_DSM_*` vars and rewrote the 401 troubleshooting section.
|
|
60
|
+
- `troubleshooting.md`: new "Spreadsheet `/spreadsheets/authorize` Returns 401" section with diagnose/fix recipe; corrected 2FA guidance (no Application Password feature in DSM).
|
|
61
|
+
- `docs/project/synology-office-mcp-spec.md`: added `SYNO_SS_*` block to env-var reference and updated `SynologyConfig` schema.
|
|
62
|
+
|
|
63
|
+
### Migration
|
|
64
|
+
- No breaking changes. Setups that worked previously continue to work — the new vars default to the matching `SYNO_*` values. If you were hitting `401` on `/spreadsheets/authorize` with HTTPS DSM, set `SYNO_SS_DSM_HTTPS=false` and `SYNO_SS_DSM_PORT=<DSM HTTP port>`.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## [0.4.3] - 2026-04-29
|
|
69
|
+
|
|
70
|
+
### Fixed — Spreadsheet auth diagnostics & env-var consistency
|
|
71
|
+
- Spreadsheet API endpoint now configurable via `SYNO_SS_HOST` (defaults to `SYNO_HOST`); previously the host was hardcoded to `SYNO_HOST` with no override
|
|
72
|
+
- Renamed env vars to a single canonical naming: `SYNO_SS_HOST` / `SYNO_SS_PORT` / `SYNO_SS_HTTPS` (matches `scripts/smoke-spreadsheet.mjs`)
|
|
73
|
+
- Removed undocumented `SYNO_SPREADSHEET_PORT` / `SYNO_SPREADSHEET_HTTPS` — these were silently ignored by `claude mcp add` setups using `SYNO_SS_*`
|
|
74
|
+
- Auth-failure error message now lists the four common 401 causes (wrong creds, 2FA without app password, container cannot reach DSM, DSM auto-block) and prints the DSM URL the Spreadsheet container is reaching
|
|
75
|
+
- Added 2FA app-password caveat to `.env.example` (the `/spreadsheets/authorize` endpoint does not accept OTP)
|
|
76
|
+
|
|
77
|
+
### Migration
|
|
78
|
+
- If you previously set `SYNO_SPREADSHEET_PORT` / `SYNO_SPREADSHEET_HTTPS`, rename them to `SYNO_SS_PORT` / `SYNO_SS_HTTPS`. Defaults (`3000` / `false`) are unchanged.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## [0.3.3] - 2026-04-27
|
|
83
|
+
|
|
84
|
+
### Changed — Documentation restructure
|
|
85
|
+
- Removed `AGENTS.md` (OpenCode no longer used) and `files/dockers/README.md` (duplicated `deployment-guide.md`)
|
|
86
|
+
- Moved `files/docs/{security,troubleshooting,tool-reference,integration-guide}.md` to repo root
|
|
87
|
+
- Removed `files/docs/deployment.md` (subset of `deployment-guide.md`)
|
|
88
|
+
- Split `SECURITY.md` (disclosure-only) from new `security-model.md` (threat model, transport security, redaction)
|
|
89
|
+
- Updated all cross-links and bumped stale version refs (`0.2.0`/`0.7.0`) across docs
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## [0.3.2] - 2026-04-27
|
|
94
|
+
|
|
95
|
+
Move doc files.
|
|
96
|
+
|
|
97
|
+
## [0.3.1] - 2026-04-27
|
|
98
|
+
|
|
99
|
+
### Fixed — DSM 7.3.2 namespace and shape alignment
|
|
100
|
+
|
|
101
|
+
DSM 7.3.2 returned error 102 ("API does not exist") for legacy namespaces. Renamed all client API references to the namespaces actually exposed by DSM 7.3.2 and adapted Drive request params + response shape accordingly.
|
|
102
|
+
|
|
103
|
+
#### Namespace renames
|
|
104
|
+
- Drive: `SYNO.Drive.Files` → `SYNO.SynologyDrive.Files`
|
|
105
|
+
- Drive sharing: `SYNO.Drive.Sharing` → `SYNO.SynologyDrive.Sharing`
|
|
106
|
+
- MailPlus: `SYNO.MailPlus.{Folder,Message,Compose,Attachment}` → `SYNO.MailClient.{Mailbox,Message,Draft,Attachment}`
|
|
107
|
+
- Spreadsheet: `SYNO.Office.Spreadsheet` → `SYNO.Office.Sheet.Snapshot` (operations) + `SYNO.Office.Export` (export)
|
|
108
|
+
- Calendar: `SYNO.Cal.*` (already correct, no change)
|
|
109
|
+
|
|
110
|
+
#### Drive shape adaptation (DSM 7.3.2)
|
|
111
|
+
- `list` / `search` use `path` parameter (not legacy `folder_path`); `search` uses `keyword` (not `query`)
|
|
112
|
+
- Response wrapper: `{ total, items }` (not `{ total, offset, files }`)
|
|
113
|
+
- Item fields: `file_id`, `display_path`, `modified_time`, `created_time`, `owner.name`, `capabilities` map → `perm.acl`
|
|
114
|
+
- `get` drops obsolete `additional` JSON param — DSM 7.3.2 returns full metadata by default
|
|
115
|
+
|
|
116
|
+
#### Verified
|
|
117
|
+
- 311/311 unit tests passing
|
|
118
|
+
- Live NAS smoke test on DSM `7.3.2-86009 update 3`: 6/6 read-only tools pass; `drive_list_files` returns real metadata end-to-end
|
|
119
|
+
|
|
120
|
+
### Notes
|
|
121
|
+
- Drive write operations (upload/move/delete/create_folder/sharing) have correct namespace but params/response shape not yet validated against live NAS — recommend smoke testing before relying on writes.
|
|
122
|
+
- MailPlus and Office tools verified namespace-only on live NAS (test user lacked mail/Office package permissions for full payload validation).
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## [0.3.0] - 2026-04-26
|
|
127
|
+
|
|
128
|
+
### Added — All modules milestone (Phases 02–08)
|
|
129
|
+
|
|
130
|
+
#### Drive module (Phase 02)
|
|
131
|
+
- `DriveClient` wrapping `SYNO.Drive.Files` and `SYNO.Drive.Labels` APIs
|
|
132
|
+
- 11 MCP tools: `drive_list_files`, `drive_search_files`, `drive_get_file_info`, `drive_download_file`, `drive_upload_file`, `drive_create_folder`, `drive_move_file`, `drive_delete_file`, `drive_get_sharing_link`, `drive_list_labels`, `drive_add_label`
|
|
133
|
+
- Confirm-required guard on `drive_delete_file` and `drive_move_file`
|
|
134
|
+
- MSW-mocked unit tests + smoke tests gated by `SMOKE_TEST=1`
|
|
135
|
+
|
|
136
|
+
#### Spreadsheet module (Phase 03)
|
|
137
|
+
- `SpreadsheetClient` wrapping `SYNO.Office.Spreadsheet` APIs
|
|
138
|
+
- 8 MCP tools: `spreadsheet_list`, `spreadsheet_get_info`, `spreadsheet_read_sheet`, `spreadsheet_write_cells`, `spreadsheet_append_rows`, `spreadsheet_add_sheet`, `spreadsheet_create`, `spreadsheet_export`
|
|
139
|
+
- Confirm-required guard on `spreadsheet_write_cells` and `spreadsheet_append_rows`
|
|
140
|
+
|
|
141
|
+
#### MailPlus module (Phase 04)
|
|
142
|
+
- `MailPlusClient` wrapping `SYNO.MailPlus` APIs
|
|
143
|
+
- 6 MCP tools: `mailplus_list_folders`, `mailplus_list_messages`, `mailplus_get_message`, `mailplus_send_message`, `mailplus_move_messages`, `mailplus_mark_messages`
|
|
144
|
+
- Confirm-required guard on `mailplus_send_message` and `mailplus_move_messages`
|
|
145
|
+
|
|
146
|
+
#### Calendar module (Phase 05)
|
|
147
|
+
- `CalendarClient` wrapping `SYNO.Cal` APIs
|
|
148
|
+
- 7 MCP tools: `calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`, `calendar_create_calendar`, `calendar_create_event`, `calendar_update_event`, `calendar_delete_event`
|
|
149
|
+
- Confirm-required guard on `calendar_create_event`, `calendar_update_event`, and `calendar_delete_event`
|
|
150
|
+
|
|
151
|
+
#### MCP integration (Phase 06)
|
|
152
|
+
- Full MCP server bootstrap with stdio and SSE transports
|
|
153
|
+
- Tool registry wiring all 32 tools
|
|
154
|
+
- Resources: Drive file tree (`drive://files`), MailPlus folder list (`mailplus://folders`), calendar list (`calendar://calendars`)
|
|
155
|
+
- Prompts: `summarize_drive_folder`, `draft_email`, `weekly_agenda`
|
|
156
|
+
- SSE: origin guard, bearer-auth middleware, loopback-enforcement at startup
|
|
157
|
+
|
|
158
|
+
#### Hardening (Phase 07)
|
|
159
|
+
- Retry with exponential backoff (max 3 attempts) on transient network errors and Synology codes 108/119
|
|
160
|
+
- Structured JSON logging via `LOG_LEVEL` env var
|
|
161
|
+
- Graceful shutdown: SIGINT/SIGTERM triggers best-effort Synology logout + SSE client drain
|
|
162
|
+
- Request timeout enforcement via `AbortSignal.timeout()` and `SYNO_REQUEST_TIMEOUT_MS`
|
|
163
|
+
|
|
164
|
+
#### Docs & release prep (Phase 08)
|
|
165
|
+
- `docs/tool-reference.md` — full 32-tool reference table
|
|
166
|
+
- `docs/deployment.md` — Docker, systemd, Synology scheduled task
|
|
167
|
+
- `docs/troubleshooting.md` — Synology error codes + fixes
|
|
168
|
+
- `docs/security.md` — detailed threat model
|
|
169
|
+
- `examples/` — Claude Desktop config, Claude Code add script, GoClaw config, smoke-test script
|
|
170
|
+
- `.github/workflows/release.yml` — tag-triggered npm publish with provenance
|
|
171
|
+
|
|
172
|
+
### Changed
|
|
173
|
+
- `src/index.ts` promoted from Phase 01 stub to full MCP server entry point
|
|
174
|
+
- `package.json` version bumped to `0.3.0`; added `exports` field
|
|
175
|
+
- README updated to reflect v0.3.0 milestone with all modules shipped
|
|
176
|
+
|
|
177
|
+
### Notes
|
|
178
|
+
- 311 unit tests passing; smoke tests against real DSM 7.2.2 pending before v1.0.0
|
|
179
|
+
- v1.0.0 target: real-NAS smoke test validation, changelog-driven release cut
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## [0.2.0] — 2026-04-26
|
|
184
|
+
|
|
185
|
+
### Added — Foundation milestone (Phase 01)
|
|
186
|
+
|
|
187
|
+
#### Project hygiene
|
|
188
|
+
- MIT-licensed open-source repository scaffold (`LICENSE`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`)
|
|
189
|
+
- GitHub issue templates (bug report, feature request) under `.github/ISSUE_TEMPLATE/`
|
|
190
|
+
- GitHub Actions CI workflow (`typecheck`, `lint`, `test`, `build` on Node 22)
|
|
191
|
+
- pnpm workspace with strict `engines` requirement (Node `>=22.0.0`, pnpm `>=9.0.0`)
|
|
192
|
+
- `tsup` build pipeline emitting ESM-only `dist/`
|
|
193
|
+
- Husky + lint-staged pre-commit hooks (typecheck, ESLint, Prettier on staged files)
|
|
194
|
+
- Prettier + ESLint flat config + `typescript-eslint` strict ruleset
|
|
195
|
+
|
|
196
|
+
#### Configuration
|
|
197
|
+
- `loadConfig()` with Zod schema validation (`src/config.ts`)
|
|
198
|
+
- Coercion helpers for boolean / int env vars with defaults
|
|
199
|
+
- SSE auth-required guard: rejects startup when `MCP_TRANSPORT=sse` is bound to a non-loopback host without `MCP_AUTH_TOKEN`
|
|
200
|
+
- Fully documented `.env.example` covering NAS connection, feature flags, transport, security, logging, and performance
|
|
201
|
+
|
|
202
|
+
#### Authentication & HTTP
|
|
203
|
+
- `AuthManager` (`src/auth/auth-manager.ts`)
|
|
204
|
+
- Login via `SYNO.API.Auth` v6 with `format=sid`
|
|
205
|
+
- Credentials sent via `POST` form body — never in URL
|
|
206
|
+
- `undici.Agent` opt-in for self-signed cert bypass (`SYNO_IGNORE_CERT=true`)
|
|
207
|
+
- Best-effort `logout()` on shutdown
|
|
208
|
+
- `TokenCache` (`src/auth/token-cache.ts`) — in-memory TTL cache with explicit invalidation
|
|
209
|
+
- `BaseClient` (`src/clients/base-client.ts`) — abstract HTTP base
|
|
210
|
+
- `_sid` forwarded via `Cookie: id=<sid>` header (kept out of URL/access logs)
|
|
211
|
+
- Single retry on Synology codes `108` / `119` (session expired) and HTTP 401
|
|
212
|
+
- `AbortSignal.timeout()` enforcement using `SYNO_REQUEST_TIMEOUT_MS`
|
|
213
|
+
- Response envelope unwrapping with typed errors
|
|
214
|
+
|
|
215
|
+
#### Error model
|
|
216
|
+
- `SynologyMcpError` base class with `code`, `synoCode`, and `retryable`
|
|
217
|
+
- Specialised: `AuthError`, `NotFoundError`, `PermissionError`, `ValidationError`, `NetworkError`
|
|
218
|
+
- `mapSynologyError()` translates Synology numeric codes to typed exceptions
|
|
219
|
+
|
|
220
|
+
#### Security utilities
|
|
221
|
+
- `redactSensitive()` — strips `passwd`, `_sid`, `otp_code`, bearer tokens from log payloads
|
|
222
|
+
- `pathGuard()` — blocks path traversal (`..`, absolute escapes) at tool boundary
|
|
223
|
+
- `originGuard()` — Origin / Host validation for SSE transport
|
|
224
|
+
- `bearerAuth()` — constant-time bearer-token comparison for SSE
|
|
225
|
+
|
|
226
|
+
#### Types
|
|
227
|
+
- `AppConfig`, `SynologyConfig`, `McpConfig` interfaces
|
|
228
|
+
- `SynologyResponse<T>` envelope with discriminated `success` flag
|
|
229
|
+
- MCP tool / resource / prompt type stubs ready for Phase 06
|
|
230
|
+
|
|
231
|
+
#### Tests
|
|
232
|
+
- Vitest configuration with v8 coverage reporter
|
|
233
|
+
- MSW-based HTTP mocking helpers in `tests/setup.ts`
|
|
234
|
+
- Unit suites: `config`, `token-cache`, `bearer-auth`, `origin-guard`, `path-guard`, `redact`
|
|
235
|
+
|
|
236
|
+
### Notes
|
|
237
|
+
- `src/index.ts` is intentionally a Phase 01 stub — full MCP server bootstrap (stdio + SSE transports, tool registry) ships in `0.7.0` per the [phased plan](./plans/260426-1222-synology-office-mcp/plan.md).
|
|
238
|
+
- No module clients (`Drive`, `Spreadsheet`, `MailPlus`, `Calendar`) are wired yet — see Roadmap in [README](./README.md#roadmap).
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## [0.1.0] — 2026-04-25
|
|
243
|
+
|
|
244
|
+
### Added
|
|
245
|
+
- Initial repository scaffold and project specification
|
|
246
|
+
- `docs/project/synology-office-mcp-spec.md` — full implementation specification (2 281 lines covering architecture, tools, resources, prompts, security, deployment)
|
|
247
|
+
- Phase-based implementation plan under `plans/260426-1222-synology-office-mcp/` (8 phases)
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
[Unreleased]: https://github.com/vocweb/synology-mcp-server/compare/v0.3.3...HEAD
|
|
252
|
+
[0.3.3]: https://github.com/vocweb/synology-mcp-server/compare/v0.3.2...v0.3.3
|
|
253
|
+
[0.3.2]: https://github.com/vocweb/synology-mcp-server/compare/v0.3.1...v0.3.2
|
|
254
|
+
[0.3.1]: https://github.com/vocweb/synology-mcp-server/compare/v0.3.0...v0.3.1
|
|
255
|
+
[0.3.0]: https://github.com/vocweb/synology-mcp-server/compare/v0.2.0...v0.3.0
|
|
256
|
+
[0.2.0]: https://github.com/vocweb/synology-mcp-server/compare/v0.1.0...v0.2.0
|
|
257
|
+
[0.1.0]: https://github.com/vocweb/synology-mcp-server/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tien Chu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|