内容
# carddav-mcp
<div align="center">
📇 一个 CardDAV 模型上下文协议（MCP）服务器，用于将联系人和通讯录暴露为 AI 助手工具。
[](https://github.com/dominik1001/carddav-mcp/actions/workflows/release.yml)
[](https://www.npmjs.com/package/carddav-mcp)
[](https://choosealicense.com/licenses/mit/)
[](https://modelcontextprotocol.io)
[](https://github.com/semantic-release/semantic-release)
</div>
## ✨ 功能特点
- 连接到 CardDAV 服务器
- 列出通讯录
- 列出通讯录中的联系人
- 获取单个联系人的完整详细信息
- 创建联系人（vCard）
- 更新联系人 — 部分更新保留其他客户端写入的 vCard 属性
- 按 UID 删除联系人
## 设置
```
{
"mcpServers": {
...,
"contacts": {
"command": "npx",
"args": [
"carddav-mcp"
],
"env": {
"CARDDAV_BASE_URL": "<CardDAV 服务器 URL>",
"CARDDAV_USERNAME": "<CardDAV 用户名>",
"CARDDAV_PASSWORD": "<CardDAV 密码>"
}
}
}
}
```
## 开发
### 快速开始
在开发模式下运行 MCP 服务器，并启用自动重新加载：
```bash
npm run dev
```
这将直接运行 TypeScript 代码，并启用监视模式，同时自动从 `.env` 加载环境变量。
### 手动构建
或者，您可以编译 TypeScript 为 JavaScript 并运行：
1. 编译：
```bash
npx tsc
```
2. 运行：
```bash
node dist/index.js
```
## 可用工具
<!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->
### 列出通讯录
列出所有通讯录，返回名称和 URL
参数：无
返回：
- 所有可用通讯录的列表
### 列出联系人
列出指定 URL 的通讯录中的所有联系人。返回每个联系人的摘要；使用 get-contact 获取完整详细信息。
参数：
- `addressBookUrl`: 字符串
返回：
- 联系人列表，每个联系人包含 `uid`、`fn`（格式化名称）、`emails` 和 `phones`
### 获取联系人
获取指定 URL 的通讯录中单个联系人的完整详细信息
参数：
- `uid`: 字符串 — 要获取的联系人的唯一标识符（从 list-contacts 获取）
- `addressBookUrl`: 字符串
返回：
- 联系人的解析字段（`uid`、`fn`、`name`、`emails`、`phones`，以及可选的 `org`、`title`、`note`）以及 `vcard` 中的原始 vCard
### 创建联系人
在指定 URL 的通讯录中创建联系人（vCard）。如果省略 `name`，则从 `fn` 派生结构化名称部分。
参数：
- `addressBookUrl`: 字符串
- `fn`: 字符串 — 联系人的格式化显示名称
- `name`: 对象（可选）— 结构化名称部分（姓氏、名、中间名等）
- `family`: 字符串（可选）
- `given`: 字符串（可选）
- `middle`: 字符串（可选）
- `prefix`: 字符串（可选）
- `suffix`: 字符串（可选）
- `emails`: 字符串数组（可选）
- `phones`: 字符串数组（可选）
- `org`: 字符串（可选）— 组织/公司
- `title`: 字符串（可选）— 职位或角色
- `note`: 字符串（可选）
返回：
- 创建的联系人的唯一 ID
### 更新联系人
更新指定 URL 的通讯录中现有的联系人。仅更改提供的字段；`emails` 和 `phones` 替换整个列表（传递空数组以清除它们，或传递空字符串以清除 `org`、`title` 或 `note`）。其他 vCard 属性得以保留。
参数：
- `uid`: 字符串 — 要更新的联系人的唯一标识符（从 list-contacts 获取）
- `addressBookUrl`: 字符串
- `fn`: 字符串（可选）
- `name`: 对象（可选）
- `family`: 字符串（可选）
- `given`: 字符串（可选）
- `middle`: 字符串（可选）
- `prefix`: 字符串（可选）
- `suffix`: 字符串（可选）
- `emails`: 字符串数组（可选）
- `phones`: 字符串数组（可选）
- `org`: 字符串（可选）
- `title`: 字符串（可选）
- `note`: 字符串（可选）
返回：
- 更新的联系人的唯一 ID
### 删除联系人
删除指定 URL 的通讯录中的联系人
参数：
- `uid`: 字符串 — 要删除的联系人的唯一标识符（从 list-contacts 获取）
- `addressBookUrl`: 字符串
返回：
- 联系人成功删除时的确认消息
<!-- TOOLS:END -->
## 烟雾测试
针对真正的 CardDAV 服务器（两者都从 `.env` 读取凭证）进行两项互补的端到端检查：
- `npm run smoke` — 确定性 SDK 套件（`scripts/smoke.ts`）。通过 MCP 客户端 SDK 在标准输入/输出上启动构建的服务器，并断言 create → list → get → update → delete 联系人往返。
- `npm run smoke:agent` — 代理舒适度套件（`scripts/smoke-agent.sh`）。通过 `claude -p` 驱动服务器，并使用 JSON 输出模式验证工具名称、描述、模式和错误消息是否可供 LLM 使用。
## 许可证
[MIT](https://choosealicense.com/licenses/mit/)
