@miguelarios/cal-mcp 0.19.0 → 0.20.0
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/CHANGELOG.md +7 -0
- package/README.md +20 -3
- package/dist/main.d.ts +7 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +15 -14
- package/dist/main.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.20.0 (2026-10-07)
|
|
4
|
+
|
|
5
|
+
- Runs over Streamable HTTP as well as stdio: set `PIM_MCP_TRANSPORT=http` (see the README's "Over Streamable HTTP"). stdio stays the default and is unchanged on the wire.
|
|
6
|
+
- The CalDAV service is created once at startup and shared by every server instance, since over HTTP an instance is built per request or per session. A configuration error now stops the process at startup instead of surfacing on the first connection.
|
|
7
|
+
- Bumped `@miguelarios/pim-core` dependency to `^0.15.0` for `serve`.
|
|
8
|
+
- Documentation: a Docker guide (`docs/docker.md`), including why a container needs `PIM_TIMEZONE`; this README gains an "Over HTTP and in Docker" section and `CAL_MCP_DEBUG`; `docs/tools/cal-mcp.md` was re-checked against the tool definitions (`import_ics` partial failures, alarm `trigger_human`, the `delete_calendar` confirmation).
|
|
9
|
+
|
|
3
10
|
## 0.19.0 (2026-09-14)
|
|
4
11
|
|
|
5
12
|
- `list_calendars` reports `description`, `timezone` (the calendar's default IANA zone, from RFC 7809 `calendar-timezone-id` when the server sends it, else the `TZID` inside RFC 4791 `calendar-timezone`) and `order` (Apple `calendar-order`), each `null` where the provider does not say (#46). `read_only` was already there.
|
package/README.md
CHANGED
|
@@ -4,10 +4,10 @@ MCP server for calendars via CalDAV — query, create, and manage events across
|
|
|
4
4
|
|
|
5
5
|
## Protocol support
|
|
6
6
|
|
|
7
|
-
Speaks MCP revision **2026-07-28** over stdio, and still serves 2025-era clients from the same tool definitions.
|
|
7
|
+
Speaks MCP revision **2026-07-28** over stdio or Streamable HTTP, and still serves 2025-era clients from the same tool definitions.
|
|
8
8
|
Every tool declares a `title`, all four behaviour annotations, and an `outputSchema`, and returns validated `structuredContent`.
|
|
9
9
|
|
|
10
|
-
`delete_event` asks the user to confirm whenever it removes the calendar object — `span: "all"`, and `span: "this"` on a non-recurring event. Excluding one occurrence of a recurring event is recoverable and is not gated. Set `PIM_MCP_CONFIRM=off` to skip confirmation in headless use.
|
|
10
|
+
`delete_event` asks the user to confirm whenever it removes the calendar object — `span: "all"`, and `span: "this"` on a non-recurring event. Excluding one occurrence of a recurring event is recoverable and is not gated. `delete_calendar` always asks, and so does an `update_event` with `span: "future"` that would drop per-occurrence changes. Set `PIM_MCP_CONFIRM=off` to skip confirmation in headless use.
|
|
11
11
|
|
|
12
12
|
## Usage
|
|
13
13
|
|
|
@@ -37,7 +37,24 @@ Add the server to your MCP client config (Claude Desktop, Claude Code, etc.). Cr
|
|
|
37
37
|
|
|
38
38
|
Add multiple providers by using different IDs: `CALDAV_NEXTCLOUD_URL`, `CALDAV_NEXTCLOUD_USER`, `CALDAV_NEXTCLOUD_PASS`, etc.
|
|
39
39
|
|
|
40
|
-
Optional env vars:
|
|
40
|
+
Optional env vars:
|
|
41
|
+
|
|
42
|
+
- `PIM_TIMEZONE` — IANA timezone used for "today", free-slot searches and local times. Defaults to the host timezone, which in a container is usually UTC.
|
|
43
|
+
- `CAL_MCP_DEBUG` — set to `1` to attach per-step CalDAV timings to tool results under `_meta`.
|
|
44
|
+
|
|
45
|
+
## Over HTTP and in Docker
|
|
46
|
+
|
|
47
|
+
Set `PIM_MCP_TRANSPORT=http` to serve Streamable HTTP at `/mcp` instead of stdio — for a client that connects by URL, or a server in a container. `PIM_MCP_HTTP_HOST` (default `127.0.0.1`) and `PIM_MCP_HTTP_PORT` (default `3000`) set where it listens, and `GET /healthz` answers `ok` for health checks. **The HTTP server does no authentication**: keep it on loopback or a private network, and put an OAuth proxy in front before exposing it further.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
docker run -d --name cal-mcp --restart unless-stopped --user node \
|
|
51
|
+
--env-file cal.env \
|
|
52
|
+
-e PIM_MCP_TRANSPORT=http -e PIM_MCP_HTTP_HOST=0.0.0.0 \
|
|
53
|
+
-p 127.0.0.1:3002:3000 -v cal-mcp-home:/home/node \
|
|
54
|
+
node:22-alpine npx -y @miguelarios/cal-mcp@0.20.0
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
See the [Docker guide](https://github.com/miguelarios/pim-agents/blob/main/docs/docker.md) for the env file, stdio use from a desktop client, Docker Compose, and exposing a server safely, and the [README](https://github.com/miguelarios/pim-agents/blob/main/README.md#over-streamable-http) for every HTTP setting.
|
|
41
58
|
|
|
42
59
|
## Tools (16)
|
|
43
60
|
|
package/dist/main.d.ts
CHANGED
|
@@ -1,4 +1,10 @@
|
|
|
1
1
|
import { McpServer } from "@modelcontextprotocol/server";
|
|
2
|
-
|
|
2
|
+
import { CalDavService } from "./services/CalDavService.js";
|
|
3
|
+
/**
|
|
4
|
+
* Builds one server instance around a shared service. Called per connection on
|
|
5
|
+
* stdio and per request over HTTP, so it must not open connections or install
|
|
6
|
+
* process handlers of its own.
|
|
7
|
+
*/
|
|
8
|
+
export declare function createServer(service: CalDavService): McpServer;
|
|
3
9
|
export declare function startServer(): Promise<void>;
|
|
4
10
|
//# sourceMappingURL=main.d.ts.map
|
package/dist/main.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;
|
|
1
|
+
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAO5D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAc9D;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAajD"}
|
package/dist/main.js
CHANGED
|
@@ -1,35 +1,36 @@
|
|
|
1
1
|
import { createRequire } from "node:module";
|
|
2
2
|
import { loadCalDavConfig } from "@miguelarios/pim-core";
|
|
3
|
-
import { TOOL_LIST_CACHE_HINT, registerTools } from "@miguelarios/pim-core/mcp";
|
|
3
|
+
import { TOOL_LIST_CACHE_HINT, registerTools, serve } from "@miguelarios/pim-core/mcp";
|
|
4
4
|
import { McpServer } from "@modelcontextprotocol/server";
|
|
5
|
-
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
6
5
|
import { CalDavService } from "./services/CalDavService.js";
|
|
7
6
|
import { CALENDAR_MANAGEMENT_TOOLS } from "./tools/calendarManagementTools.js";
|
|
8
7
|
import { CALENDAR_TOOLS } from "./tools/calendarTools.js";
|
|
9
8
|
const require = createRequire(import.meta.url);
|
|
10
9
|
const { version } = require("../package.json");
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
10
|
+
/**
|
|
11
|
+
* Builds one server instance around a shared service. Called per connection on
|
|
12
|
+
* stdio and per request over HTTP, so it must not open connections or install
|
|
13
|
+
* process handlers of its own.
|
|
14
|
+
*/
|
|
15
|
+
export function createServer(service) {
|
|
14
16
|
const server = new McpServer({ name: "@miguelarios/cal-mcp", title: "CalDAV Calendars", version }, {
|
|
15
17
|
capabilities: { tools: { listChanged: false } },
|
|
16
18
|
instructions: "Read and manage CalDAV calendars across every configured provider. Calendar IDs are provider-prefixed (e.g. mailbox/Work) — call list_calendars first. delete_event asks the user to confirm whenever it removes the calendar object; excluding one occurrence of a recurring event does not. delete_calendar asks the user to confirm too, since it removes every event in the calendar. Renaming a calendar with update_calendar changes its ID.",
|
|
17
19
|
cacheHints: { "tools/list": TOOL_LIST_CACHE_HINT },
|
|
18
20
|
});
|
|
19
21
|
registerTools(server, [...CALENDAR_TOOLS, ...CALENDAR_MANAGEMENT_TOOLS], service);
|
|
22
|
+
return server;
|
|
23
|
+
}
|
|
24
|
+
export async function startServer() {
|
|
25
|
+
const service = new CalDavService(loadCalDavConfig());
|
|
26
|
+
// PIM_MCP_TRANSPORT picks stdio or Streamable HTTP; either way the entry
|
|
27
|
+
// serves 2026-07-28 and 2025-era clients from the same factory.
|
|
28
|
+
const handle = await serve(() => createServer(service), { name: "cal-mcp" });
|
|
20
29
|
const handleShutdown = async () => {
|
|
30
|
+
await handle.close();
|
|
21
31
|
process.exit(0);
|
|
22
32
|
};
|
|
23
33
|
process.on("SIGINT", handleShutdown);
|
|
24
34
|
process.on("SIGTERM", handleShutdown);
|
|
25
|
-
return server;
|
|
26
|
-
}
|
|
27
|
-
export async function startServer() {
|
|
28
|
-
// `serveStdio` owns the era decision: a 2026-07-28 client gets the new
|
|
29
|
-
// protocol, and a 2025-era client is still served from the same factory.
|
|
30
|
-
serveStdio(() => createServer(), {
|
|
31
|
-
onerror: (error) => console.error("[cal-mcp] Server error:", error.message),
|
|
32
|
-
});
|
|
33
|
-
console.error("[cal-mcp] Server started on stdio");
|
|
34
35
|
}
|
|
35
36
|
//# sourceMappingURL=main.js.map
|
package/dist/main.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,EACpE;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE;QAC/C,YAAY,EACV,obAAob;QACtb,UAAU,EAAE,EAAE,YAAY,EAAE,oBAAoB,EAAE;KACnD,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,CAAC,GAAG,cAAc,EAAE,GAAG,yBAAyB,CAAC,EAAE,OAAO,CAAC,CAAC;IAElF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAEtD,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAE7E,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE;QAChC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACxC,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miguelarios/cal-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "MCP server for calendars via CalDAV — CRUD events, free/busy, multi-provider",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"start": "node dist/bin/cli.js"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
|
-
"@miguelarios/pim-core": "^0.
|
|
32
|
+
"@miguelarios/pim-core": "^0.15.0",
|
|
33
33
|
"@modelcontextprotocol/server": "^2.0.0",
|
|
34
34
|
"tsdav": "^2.1.0"
|
|
35
35
|
},
|