Dex MCP Server

Dex MCP 服务

v1.0.0 现已发布！

• 请查看 RELEASE-NOTES.md 和 GitHub Releases，了解主要更新和升级信息。
• 升级方法：
  1. 拉取最新代码：git pull --rebase origin main
  2. 确保 .env 文件存在且包含有效的 DEX_API_KEY。
  3. 如有需要，请在 Agent 启动前使用 kill-dex-mcp-server.sh 脚本。
  4. 请参阅 copilot-instructions.md，了解 Agent/CLI 用法和最佳实践。

一个模型上下文协议（MCP）服务，通过 Dex API 为 AI Agent 提供全面的联系人关系管理功能。

功能

🚀 联系人管理

• 创建、读取、更新和删除联系人及其完整信息
• 按姓名、电子邮件或公司搜索联系人
• 全面的联系人字段：姓名、公司、职位、描述、电子邮件、电话号码

📝 笔记管理

• 与联系人关联的笔记以时间线条目的形式存储
• 为任何联系人创建、更新和删除笔记
• 跨所有联系人按内容搜索笔记
• 支持大型笔记集合的分页

⏰ 提醒管理

• 设置与特定联系人关联的提醒
• 根据需要完成、更新和删除提醒
• 按文本内容搜索提醒
• 支持重复提醒
• 跟踪到期日期并正确格式化日期

安装

前提条件

• Node.js 18 或更高版本
• Dex API 账户和 API 密钥

设置

1. 克隆此仓库：

git clone https://github.com/alpabon73/dex-mcp-server.git
cd dex-mcp-server

2. 安装依赖项：

npm install

3. 在 src/index.ts 中配置 Dex API 密钥：

const API_KEY = 'your-dex-api-key-here';

4. 构建服务：

npm run build

环境变量

此项目需要 Dex API 密钥。切勿将真实 API 密钥提交到公共仓库。

1. 将 .env.example 复制为 .env：

   cp .env.example .env
   

2. 编辑 .env 并设置真实的 Dex API 密钥：

   DEX_API_KEY=your-dex-api-key-here
   

3. 除非在环境或 .env 文件中设置了 DEX_API_KEY，否则服务不会启动。

.env 已列入 .gitignore，绝不会被提交。

用法

独立使用

npm start

与 AnythingLLM 搭配使用

将其添加到 MCP 服务配置中：

{
  "servers": {
    "dex-mcp": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/dex-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

可用工具

联系人工具（6）

• get_contacts - 分页获取联系人
• get_contact_by_id - 获取指定联系人的详细信息
• search_contacts - 按姓名/公司/电子邮件搜索
• create_contact - 添加联系人
• update_contact - 修改现有联系人
• delete_contact - 删除联系人

笔记工具（6）

• get_notes_by_contact - 获取某位联系人的所有笔记
• get_all_notes - 分页获取所有笔记
• search_notes - 按内容搜索笔记
• create_note - 为联系人添加笔记
• update_note - 修改现有笔记
• delete_note - 删除笔记

提醒工具（6）

• get_reminders_by_contact - 获取联系人的提醒
• get_all_reminders - 分页获取所有提醒
• search_reminders - 按文本搜索提醒
• create_reminder - 设置新提醒
• update_reminder - 修改现有提醒
• complete_reminder - 将提醒标记为已完成
• delete_reminder - 删除提醒

笔记允许的会议类型

创建笔记时，可以使用显示名称或 Dex API 枚举值指定会议类型。下表列出了可接受的值：

显示名称	Dex API 枚举值
笔记	note
电话	call
电子邮件	email
短信/消息	text_messaging
Linkedin	linkedin
Skype/Teams	skype_teams
Slack	slack
咖啡	coffee
社交联络	networking
派对/社交	party_social
其他	other
餐食	meal
会议	meeting
自定义	custom

你可以使用上述任意显示名称（不区分大小写，允许空格和斜杠），也可以使用准确的枚举值。系统会自动将你的输入映射到正确的 Dex API 值。

示例用例

• “将 TechCorp 的 John Smith 添加为新联系人”
• “设置提醒，下周跟进 Sarah”
• “搜索所有关于 ABC 项目的笔记”
• “将 Mike 的职位更新为高级工程师”
• “显示本月所有待处理的提醒”
• “创建一条关于今天与客户会议的笔记”

开发

脚本

• npm run build - 编译 TypeScript
• npm run dev - 使用 ts-node 运行以进行开发
• npm run watch - 监视模式编译
• npm start - 运行编译后的服务

架构

• 使用 TypeScript 确保类型安全
• 使用 Zod 进行架构验证
• 使用 Axios 向 Dex API 发送 HTTP 请求
• 使用 MCP SDK 实现协议

API 集成

此服务通过以下方式与 Dex API 集成：

• GraphQL 端点：https://api.getdex.com/v1/graphql
• 使用 Timeline items 存储笔记
• 使用 Reminders 表，并通过联系人关联
• 支持完善的分页和搜索功能

代码质量与 CI

本项目使用 TypeScript 确保类型安全，并使用 ESLint 检查代码。CI 会自动检查所有代码中的类型错误和 lint 问题（参见 .github/workflows/ci.yml）。

• 在本地运行类型检查：

  npm run build # or npx tsc --noEmit
  

• 在本地运行 linter：

  npm run lint
  

所有拉取请求都必须通过 CI 检查才能合并。

Issue 和 PR 模板

• 错误报告和功能请求使用 GitHub issue 模板，以保持一致。
• 所有拉取请求都使用 PR 模板，以确保质量和文档完善。

安全与密钥

• 切勿提交密钥或 API 密钥。 .env 已加入 gitignore，密钥通过环境变量加载。
• 如果密钥曾被提交，请遵循仓库的历史清理流程（参见 scrub-git-history.sh）。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行修改
4. 如适用，添加测试
5. 运行 npm run lint 和 npm run build 检查代码质量
6. 提交拉取请求

许可证

MIT License - 详情请参见 LICENSE 文件

支持

关于以下方面的问题：

• Dex API：查看 Dex 文档
• MCP 协议：参见 MCP 规范
• 此服务：在此仓库中提交 issue

---

如何报告问题或参与贡献

• 发现错误或有功能请求？提交 issue
• 想要贡献？请参阅 CONTRIBUTING.md 了解指南。
• 有安全方面的疑虑？请参阅 SECURITY.md 了解负责任的披露方式。
• 有关发行说明和升级信息，请参阅 RELEASE-NOTES.md 和 CHANGELOG.md。