Mcp Nextcloud Calendar

日程 TypeScript

🚀 MCP Nextcloud Calendar

MCP Nextcloud Calendar 是一个用于集成 Nextcloud 日历的模型上下文协议（MCP）服务器，它能从 Nextcloud 中获取日历信息，并提供对 ADHD 友好的组织功能，同时支持 MCP 协议。

🚀 快速开始

你可以使用 npx 快速使用该包：

npx mcp-nextcloud-calendar

✨ 主要特性

从 Nextcloud 获取日历信息。
具备对 ADHD 友好的组织功能。
支持 MCP 协议（可流式传输的 HTTP 和传统的 HTTP+SSE）。

📦 安装指南

全局安装

npm install -g mcp-nextcloud-calendar

本地安装

npm install mcp-nextcloud-calendar

💻 使用示例

MCP 客户端配置

若要与 MCP 客户端（如 Claude）配合使用，请将以下配置添加到你的 MCP 客户端设置中：

{
"mcpServers": {
"nextcloud-calendar": {
"command": "npx",
"args": ["-y", "mcp-nextcloud-calendar"],
"env": {
"NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
"NEXTCLOUD_USERNAME": "your-username",
"NEXTCLOUD_APP_TOKEN": "your-app-token"
}
}
}
}

指定版本

你可以固定使用该包的特定版本：

{
"mcpServers": {
"nextcloud-calendar": {
"command": "npx",
"args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
"env": {
"NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
"NEXTCLOUD_USERNAME": "your-username",
"NEXTCLOUD_APP_TOKEN": "your-app-token"
}
}
}
}

📚 详细文档

环境变量

服务器使用以下环境变量，并在可能的情况下提供默认值：

属性	详情
PORT	服务器端口，默认值为 3001，非必需
SERVER_NAME	MCP 服务器标识符，默认值为 nextcloud-calendar-server，非必需
NODE_ENV	环境（开发/生产），默认值为 development，非必需
NEXTCLOUD_BASE_URL	你的 Nextcloud 服务器 URL，必需
NEXTCLOUD_USERNAME	你的 Nextcloud 用户名，必需
NEXTCLOUD_APP_TOKEN	你的 Nextcloud 应用令牌，必需
KEEP_ALIVE_INTERVAL	保持活动间隔（毫秒），默认值为 30000，非必需

开发设置

本地开发步骤

克隆仓库。
安装依赖：

npm install

cp .env.example .env

使用你的 Nextcloud 凭证编辑 .env 文件。

获取 Nextcloud 应用令牌

登录你的 Nextcloud 实例。
转到设置 → 安全 → 应用密码。
创建一个名为“MCP Calendar”的新应用密码。
将生成的令牌复制到你的 .env 文件中。

开发命令

# 构建项目
npm run build

# 以开发模式运行
npm run dev

# 运行测试
npm run test

# 运行代码检查
npm run lint

# 格式化代码
npm run format

🔧 技术细节

API 端点

/mcp - 主要的 MCP 端点（可流式传输的 HTTP 传输）。
/sse 和 /messages - 传统的 MCP 端点（HTTP+SSE 传输）。
GET /health - 健康检查端点。
GET /api/calendars - 列出所有日历。

MCP 工具

日历管理

工具	描述	参数
`listCalendars`	检索所有可访问的日历	无
`createCalendar`	创建一个新日历	`displayName`（必需），`color`（可选），`category`（可选），`focusPriority`（可选）
`updateCalendar`	更新现有日历	`id`（必需），`displayName`（可选），`color`（可选），`category`（可选），`focusPriority`（可选）
`deleteCalendar`	删除一个日历	`id`（必需）

⚠️ 重要提示

updateCalendar 和 deleteCalendar 工具可能需要你的 Nextcloud 实例中的特殊权限。日历操作受 Nextcloud 的权限系统约束。

事件管理

工具	描述	参数
`listEvents`	检索日历的事件	`calendarId`（必需），`start`（可选），`end`（可选）
`getEvent`	获取特定事件	`calendarId`（必需），`eventId`（必需）
`createEvent`	创建一个新事件	`calendarId`（必需），`summary`（必需），`start`（必需），`end`（必需），`description`（可选），`location`（可选）
`updateEvent`	更新现有事件	`calendarId`（必需），`eventId`（必需），[以及任何要更新的事件属性]
`deleteEvent`	删除一个事件	`calendarId`（必需），`eventId`（必需）

📄 许可证

本项目采用 ISC 许可证。

⚠️ 重要提示

此包目前处于早期开发阶段（0.1.x）。API 和工具可能会在未来版本中无通知更改。

💡 使用建议

更新和删除日历操作可能需要你的 Nextcloud 实例中的特定权限。

针对特定 Nextcloud 错误代码的错误处理仍在改进中。

包含大量事件的大型日历可能会出现性能问题。

如果你遇到任何问题，请在 GitHub 仓库中报告。

0 条评论
分类：日程