1. 项目概述为AI智能体构建一个受控的通讯录如果你正在使用Claude Desktop、Cursor或者任何支持Model Context ProtocolMCP的AI智能体并且希望它们能帮你管理联系人比如记住客户的邮箱、电话和公司信息那么你很可能需要一个持久化、可查询的存储方案。直接让AI在对话里记住这些信息既不靠谱也不安全更无法在下次对话时复用。veyra-contacts这个MCP工具就是为了解决这个问题而生的。简单来说它是一个专门给AI智能体用的通讯录管理器。AI可以通过它来创建、读取、更新和删除联系人信息所有数据都安全地存储在你本地的SQLite数据库里。但它的设计哲学非常有意思读操作完全免费而所有写操作增、删、改都被标记为“Class B”需要经过一个叫做Veyra的“提交模式”授权才能执行。这背后的逻辑是联系人数据通常涉及商业机密或个人隐私属于业务关键信息必须防止AI智能体在未经明确授权的情况下进行意外修改或删除。这种“读写分离”的权限模型正是Veyra生态系统的核心理念——为AI的生产力操作加上一道安全阀。2. 核心设计思路为什么需要“提交模式”在深入配置和使用之前我们有必要先理解veyra-contacts乃至整个Veyra工具家族的设计初衷。这能帮你更好地判断它是否适合你的场景。2.1 传统AI工具交互的痛点在没有类似工具时我们与AI协作管理数据通常有两种方式纯对话记忆告诉AI“记住Alice的邮箱是aliceexample.com”。这种方式极不可靠对话上下文窗口有限一旦切换话题或开始新对话信息就丢失了。手动桥接自己操作一个数据库或表格当AI需要联系人信息时你手动查询并粘贴给它。这打断了工作流效率低下。MCP协议的出现就是为了让AI智能体能直接、安全地调用外部工具和服务打破信息孤岛。veyra-contacts就是一个标准的MCP服务器它让AI拥有了一个结构化的、持久的联系人数据库。2.2 “业务关键数据”与“信任边界”问题然而赋予AI写入权限带来了新的风险。想象一下你让AI“更新一下Alice的信息”它可能因为理解偏差误删了Alice的联系人或者把她的邮箱错误地覆盖成别人的。对于非关键数据比如一个临时的待办事项这种错误或许可以容忍。但对于客户联系方式、合同关键人这类业务关键数据一次意外的写入操作可能导致严重的后果。因此veyra-contacts引入了一个明确的“信任边界”读取是低风险的因此免费且无需额外授权写入是高风险的因此需要显式的、额外的授权。这个授权机制就是Veyra的“提交模式”。2.3 Veyra提交模式的工作原理你可以把Veyra理解为一个针对AI操作的“二次确认”系统。其工作流程如下尝试写入AI智能体如Claude试图调用create_contact工具但最初不会附带授权令牌veyra_token。拦截与提示veyra-contacts服务器检测到这是一个Class B写入操作且缺少令牌它会立即中止执行并返回一个结构化的错误响应。这个响应不仅告诉AI“操作被拒绝”更重要的是它提供了一个标准的authorize_endpoint授权端点URL。获取授权AI智能体或集成了该AI的应用将这个授权端点信息呈现给用户。用户需要访问这个端点通常是一个简单的网页确认此次操作。确认后Veyra服务会生成一个短期有效的veyra_token。重试与执行AI智能体获得令牌后使用相同的参数但加上veyra_token重新调用写入工具。这次veyra-contacts会通过Veyra的Node.js SDK验证令牌的有效性。验证通过后操作才被真正执行。这个过程确保了每一次对关键数据的修改都经过了人类用户的“点头”确认。它不是在阻碍自动化而是在关键的决策点上引入了必要的人工监督从而建立起对AI操作的信任。注意这种模式特别适合“助理型”AI工作流。AI可以自由地查询、筛选联系人读帮我们快速找到信息。但当它要修改数据时会主动停下来向我们“请示”我们批准后它才继续。这完美平衡了效率与安全。3. 环境准备与安装部署了解了原理我们开始动手部署。veyra-contacts是一个Node.js项目部署过程相对简单。3.1 前置条件检查首先确保你的开发环境已经就绪Node.js需要版本16或更高。你可以在终端运行node --version来检查。npm通常随Node.js一起安装运行npm --version确认。Git用于克隆项目仓库运行git --version确认。如果你的系统没有安装Node.js建议通过 Node.js官网 下载LTS长期支持版本进行安装这是最稳妥的方式。3.2 获取项目源码打开终端选择一个你喜欢的目录克隆veyra-contacts的仓库git clone https://github.com/Aquariosan/veyra-contacts.git cd veyra-contacts这个命令会将项目代码下载到当前目录下的veyra-contacts文件夹中并自动进入该文件夹。3.3 安装依赖与构建项目根目录下应该已经存在package.json文件。我们使用npm来安装所有必要的依赖包。npm installnpm install命令会读取package.json中的dependencies和devDependencies下载所有需要的库比如veyrahq/sdk-node用于Veyra令牌验证、sqlite3数据库驱动以及TypeScript编译器等。安装完成后我们需要将TypeScript源代码编译成JavaScript因为MCP服务器最终运行的是编译后的JS文件。npm run build这个命令通常会执行tscTypeScript编译器将src目录下的.ts文件编译到dist目录通常是dist/index.js。你可以查看package.json中scripts部分下的build命令来确认具体的构建指令。3.4 数据存储位置首次成功运行veyra-contacts服务器后它会在你的用户主目录~下创建一个名为.veyra-contacts的隐藏文件夹并在其中生成一个data.db的SQLite数据库文件。路径示例Mac/Linux/Users/你的用户名/.veyra-contacts/data.db路径示例WindowsC:\Users\你的用户名\.veyra-contacts\data.dbSQLite是一个轻量级的单文件数据库无需安装额外的数据库服务非常方便。这个文件包含了所有的联系人表和数据。你可以使用任何SQLite浏览器如DB Browser for SQLite直接打开这个文件进行查看或手动维护但这通常不是必须的。实操心得在团队共享环境中如果你希望将数据库文件放在其他位置比如一个共享网络驱动器你需要修改项目的源代码调整数据库文件的初始化路径。这涉及到修改src/index.ts中创建数据库连接的部分。对于绝大多数个人用户使用默认路径即可。4. 配置MCP客户端以Claude Desktop为例MCP工具需要被“注册”到AI客户端中才能被调用。这里以最流行的Claude Desktop为例展示配置过程。其他支持MCP的客户端如Cursor配置逻辑类似具体请参考其官方文档。4.1 定位Claude Desktop的配置目录Claude Desktop的MCP服务器配置存储在一个JSON文件中。macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果该文件或目录不存在你可以手动创建它。4.2 编辑配置文件使用你喜欢的文本编辑器如VS Code、记事本等打开或创建上述配置文件。你需要添加一个mcpServers字段来配置veyra-contacts。关键的一步是获取veyra-contacts编译后的入口文件index.js的绝对路径。如何获取绝对路径在终端中进入你之前克隆的veyra-contacts目录然后使用pwdMac/Linux或cdWindows命令结合路径拼接来获取。Mac/Linux:cd /path/to/veyra-contacts pwd假设输出是/Users/yourname/projects/veyra-contacts那么绝对路径就是/Users/yourname/projects/veyra-contacts/dist/index.js。Windows (PowerShell):cd C:\path\to\veyra-contacts $pwd (Get-Item -Path .\).FullName Join-Path $pwd dist\index.js4.3 编写配置内容将以下配置模板填入claude_desktop_config.json。请务必将/absolute/path/to/veyra-contacts/dist/index.js替换为你上一步得到的真实绝对路径。{ mcpServers: { veyra-contacts: { command: node, args: [/absolute/path/to/veyra-contacts/dist/index.js] } } }例如在Mac上的完整配置可能看起来像这样{ mcpServers: { veyra-contacts: { command: node, args: [/Users/alice/projects/veyra-contacts/dist/index.js] } } }4.4 重启与验证保存配置文件后完全关闭并重新启动Claude Desktop应用程序。这是必须的因为Claude只在启动时读取配置。重启后你可以通过以下方式验证配置是否成功新建一个对话。在输入框里尝试让Claude使用联系人工具。例如你可以输入“请列出我通讯录里所有的联系人。”如果配置正确Claude会识别到可用的list_contacts工具并调用它。由于此时数据库是空的它可能会返回一个空列表[]或者告诉你没有联系人。这本身就是成功的标志——说明工具已被加载并能正常响应。注意事项如果Claude没有反应或报错请依次检查1) 配置文件路径和格式是否正确JSON格式严格不能有尾随逗号2)index.js的绝对路径是否正确无误3) 是否已经成功执行了npm run build4) 终端中直接运行node /your/path/dist/index.js看是否有错误输出。常见的错误是Node.js模块路径问题确保在项目根目录下运行过npm install。5. 工具详解与实战调用veyra-contacts提供了六种核心工具分为免费的读取类和需要授权的写入类。理解每个工具的输入输出是高效使用它的关键。5.1 读取类工具免费这些工具用于查询和检索信息AI可以自由调用。1.list_contacts- 列出联系人功能获取联系人列表支持简单的过滤。输入参数tag(可选): 按标签过滤例如customer。company(可选): 按公司过滤例如Acme Corp。使用场景“给我看看所有客户标签的联系人”或“列出Acme公司的所有人”。2.search_contacts- 搜索联系人功能在全字段姓名、邮箱、公司、标签进行关键词模糊搜索。这是最常用的查找工具。输入参数query(必需): 搜索关键词例如alice或gmail。使用场景“帮我找一下名字里带‘张’的人”或“搜索所有使用Gmail邮箱的联系人”。3.get_contact- 获取单个联系人详情功能通过唯一ID获取某个联系人的完整详细信息。输入参数id(必需): 联系人的唯一标识符。这个ID在创建联系人时由系统自动生成通常在list_contacts的结果中可以找到。使用场景在获得一个联系人列表后需要查看其中某一个人的全部信息时使用。5.2 写入类工具Class B需Veyra令牌这些工具会修改数据每次调用成本为€0.02且必须提供有效的veyra_token。4.create_contact- 创建联系人输入参数name(必需): 联系人姓名。email(可选): 电子邮箱。phone(可选): 电话号码。company(可选): 公司名称。tags(可选): 标签多个标签可以用英文逗号分隔例如customer,vip,urgent。veyra_token(可选但对写入操作实际为必需): Veyra授权令牌。关键细节tags字段虽然以字符串形式传入但工具内部会处理为便于搜索的格式。合理使用标签如按项目、按关系、按优先级分类能极大提升后续检索效率。5.update_contact- 更新联系人输入参数id(必需): 要更新的联系人的ID。name(可选): 新的姓名。email(可选): 新的邮箱。phone(可选): 新的电话。company(可选): 新的公司。tags(可选): 新的标签注意这会覆盖原有标签而非追加。veyra_token(可选但对写入操作实际为必需): Veyra授权令牌。注意事项这是一个“部分更新”操作。你只需要传入需要修改的字段。例如只更新邮箱则只需提供id,email和veyra_token。6.delete_contact- 删除联系人输入参数id(必需): 要删除的联系人的ID。veyra_token(可选但对写入操作实际为必需): Veyra授权令牌。警告删除操作是不可逆的。一旦执行该联系人的所有数据将从本地数据库中永久移除。这也是为什么它被归类为Class B操作。5.3 实战对话示例让我们模拟一个完整的AI对话场景看看这些工具如何串联工作。用户“我刚刚和Acme公司的Bob谈过他换了新邮箱是bob.newacme.com记得把他标记为‘关键客户’。”AI (Claude) 的思考与操作流程搜索现有记录AI首先会尝试调用search_contacts查询query为 “Bob Acme”以确认Bob是否已存在。判断操作类型情况A找到了Bob的记录。AI会看到返回的记录中包含Bob的ID例如id: 1712345678-xyz987。这时AI需要执行更新操作。情况B没有找到Bob的记录。AI则需要执行创建操作。执行写入操作以情况A更新为例AI会构造一个update_contact调用参数为{ id: 1712345678-xyz987, email: bob.newacme.com, tags: 关键客户 }由于这是Class B操作AI第一次调用时不会包含veyra_token。触发Veyra授权veyra-contacts返回VeyraCommitRequired错误并附带authorize_endpoint。Claude Desktop的UI可能会将这个信息以可点击链接或提示框的形式展示给用户。用户授权用户点击链接在Veyra的授权页面上确认此次“更新Bob的联系方式”操作。确认后页面会生成一个veyra_token通常是一串加密字符。完成操作用户将令牌提供给AI可能是通过粘贴AI用相同的参数但加上veyra_token重新调用update_contact。这次调用成功数据库被更新。结果反馈AI向用户确认“已成功将Bob的邮箱更新为bob.newacme.com并添加了‘关键客户’标签。”这个流程虽然比直接写入多了一步授权但确保了每一次数据变更都在用户的知情和控制下进行避免了AI因误解指令而“擅作主张”。6. 深入Veyra授权流程与令牌管理Veyra的“提交模式”是veyra-contacts安全性的基石。让我们更技术化地剖析这个流程并讨论令牌管理的实践。6.1 授权流程的详细拆解当AI发起一个写入请求以create_contact为例且未附带令牌时veyra-contacts内部的处理逻辑如下请求接收与分类服务器收到请求解析工具名称为create_contact查表知其属于Class B。令牌检查检查请求的arguments中是否存在veyra_token字段。如果不存在立即进入错误处理流程。构造错误响应服务器不会执行任何数据库操作而是返回一个预定义的、符合MCP错误格式的响应。这个响应非常关键它不仅是错误信息更是下一步操作的指引。{ error: VeyraCommitRequired, message: Write operations require Veyra commit mode., currentMode: open, requiredMode: commit, authorize_endpoint: https://api.veyra.to/v1/authorize-action, docs_url: https://veyra.to }authorize_endpoint: 这是用户或AI客户端需要去获取令牌的统一地址。currentModerequiredMode: 清晰地说明了当前状态开放模式和所需状态提交模式。客户端处理一个设计良好的MCP客户端如Claude Desktop应该能识别这种标准错误并优雅地将其呈现给用户例如显示一个按钮“授权此操作”点击后打开授权端点页面。令牌验证当请求附带令牌重试时veyra-contacts会调用veyrahq/sdk-node中的验证函数将令牌发送到Veyra的服务端进行校验。校验内容包括令牌是否有效、是否过期、是否针对此次操作类型如create_contact签发等。只有全部通过写入操作才会继续。6.2 关于Veyra令牌的实践要点令牌的有效期Veyra令牌通常是短期有效的例如几分钟并且是单次使用或针对单次操作签发的。这意味着你不能将一个令牌存储起来反复使用。每次需要授权时都需要走一遍授权流程获取新令牌。成本与计费每次成功的Class B操作即验证令牌成功后执行的操作会产生€0.02的费用。这个费用是支付给Veyra服务用于维持其授权和审计基础设施。读取操作Class A完全免费。你需要一个Veyra账户并为其充值才能进行写入操作。开发与测试在开发阶段频繁的授权可能会影响效率。Veyra可能提供沙箱环境或测试令牌具体需要查阅其官方文档。对于本地开发和测试另一种思路是临时修改veyra-contacts的源代码绕过令牌验证仅限测试环境但这需要你有一定的Node.js开发能力并且要清楚知道这样做的安全风险。实操心得在实际使用中尤其是与Claude配合时你会发现这个授权流程被集成得很顺畅。Claude会直接在你对话界面里提示你需要授权并提供一个按钮。点击后系统默认浏览器会打开Veyra的授权页面你确认后令牌会自动传回给Claude整个过程几乎是无感的。这种用户体验设计得非常好既保证了安全又没有过多打断工作流。7. 高级主题使用Veyra托管服务包对于大多数用户尤其是希望快速集成多个Veyra工具的用户官方强烈推荐使用Veyra Hosted Pack托管服务包而非单独部署veyra-contacts。7.1 托管包 vs 独立包如何选择特性独立包 (veyra-contacts)托管服务包 (mcp.veyra.to)部署复杂度中。需本地安装Node.js、克隆项目、构建、配置路径。极低。只需在MCP配置中添加一个URL。维护成本高。需手动更新代码、处理依赖冲突、确保服务常驻。零。由Veyra团队维护、更新和保障可用性。功能范围单一。仅联系人管理工具。全面。一个URL集成48个工具包括联系人、笔记、任务、代码片段等所有Veyra工具。扩展性灵活。可自行修改源码定制功能。固定。使用官方提供的标准化工具集。适用场景深度定制开发、学习MCP服务器原理、仅需联系人单一功能。追求开箱即用、快速获得完整AI工具链、无运维负担的绝大多数用户。7.2 配置托管服务包配置托管包简单到令人发指。只需在Claude Desktop的配置文件 (claude_desktop_config.json) 中将之前的独立服务器配置替换为以下内容{ mcpServers: { veyra: { url: https://mcp.veyra.to/sse } } }保存并重启Claude Desktop。重启后Claude将拥有来自Veyra托管包的数十个工具其中自然包含了联系人管理相关的所有功能list_contacts,create_contact等。你可以通过询问Claude“你现在有哪些可用的工具”来验证。7.3 托管包的优势解读一键集成无需关心服务器运行、进程管理。SSEServer-Sent Events连接由客户端维护你只需要一个有效的URL。工具生态除了contacts你立即获得了memory键值存储、notes笔记、tasks任务、snippets代码片段、bookmarks书签等一系列工具极大地扩展了AI的能力边界。持续更新Veyra团队会在后端更新工具、修复漏洞、提升性能所有用户自动受益无需手动升级。统一授权所有工具的授权流程一致使用同一个Veyra账户管理。访问托管包的清单你甚至可以直接在浏览器中打开https://mcp.veyra.to/.well-known/veyra-pack.json查看这个服务包提供的所有工具及其详细描述这相当于一份完整的工具说明书。8. 故障排除与常见问题在实际部署和使用过程中你可能会遇到一些问题。这里汇总了一些常见情况及其解决方法。8.1 配置与启动问题问题1Claude Desktop重启后提示找不到MCP服务器或连接失败。可能原因ANode.js路径或项目路径错误。这是最常见的问题。仔细检查claude_desktop_config.json中args数组里的路径。确保路径指向的是编译后的dist/index.js文件并且该文件确实存在。在终端中使用ls -la /your/path/dist/index.jsMac/Linux或dir C:\your\path\dist\index.jsWindows来确认。可能原因BNode.js环境问题。尝试在终端中直接运行该JS文件node /your/path/dist/index.js。如果报错如缺少模块说明项目依赖可能未正确安装。回到项目目录删除node_modules文件夹和package-lock.json文件重新运行npm install和npm run build。可能原因C端口冲突。虽然MCP服务器通常使用stdio通信但某些实现可能涉及网络端口。确保没有其他程序占用相关端口。问题2AI无法识别工具或者说“没有可用的工具”。检查确认Claude Desktop已完全重启。检查配置文件语法确保JSON格式正确可以使用在线JSON校验器。如果使用托管包确认URL拼写无误。8.2 运行时与操作问题问题3执行写入操作时AI没有弹出授权提示而是直接报错。原因这取决于MCP客户端如Claude Desktop的实现。理想的客户端应该能解析VeyraCommitRequired错误并引导用户授权。如果客户端只是简单地将错误信息显示出来你需要手动处理。查看错误信息中的authorize_endpoint链接手动在浏览器中打开并完成授权然后将获得的veyra_token复制给AI让它重试。进阶可以关注Claude Desktop的更新日志其对MCP错误处理的体验正在不断优化。问题4授权成功后操作仍然失败提示令牌无效或过期。原因Veyra令牌有效期很短。可能你在获取令牌后过了几分钟才让AI重试此时令牌已失效。需要重新发起一次授权流程获取新的令牌。检查确保AI在重试请求中正确地将令牌放在了arguments对象的veyra_token字段里。问题5搜索或列表操作返回的结果不符合预期。排查确认数据存在使用list_contacts不带参数查看所有数据确认你要找的联系人是否已创建。理解搜索逻辑search_contacts是跨字段的模糊匹配。搜索“gmail”会匹配邮箱中包含“gmail”的所有联系人。而list_contacts的company和tag参数是精确匹配。检查标签格式创建或更新时tags字段是用英文逗号分隔的字符串如work,friend。搜索时list_contacts的tag参数需要精确匹配其中一个标签例如tag: work。8.3 数据备份与迁移本地数据库备份你的所有数据都在~/.veyra-contacts/data.db这个SQLite文件里。定期备份这个文件即可。你可以直接复制它或者使用sqlite3命令行工具进行备份sqlite3 ~/.veyra-contacts/data.db .backup backup.db。迁移到新机器在新机器上部署好veyra-contacts并成功运行一次生成空数据库文件后停止服务用备份的data.db文件覆盖新生成的空文件再启动服务数据就迁移完成了。使用Veyra托管包则完全无需担心数据备份问题数据的安全与持久化由Veyra服务负责。从独立部署的折腾到托管服务包的一行配置veyra-contacts提供了两种截然不同的体验路径但都指向同一个目标让AI智能体安全、可靠地管理你的核心联系人数据。Class B写入的设计初看似乎增加了步骤但在实际与Claude等AI的协作中你会发现这种“请求-授权”的交互模式非常自然它巧妙地将人的判断力嵌入到自动化流程中防止了“自动化失控”。对于个人或小团队来说托管包无疑是性价比最高的选择几乎零运维成本就能获得一整套生产级的AI工具链。而独立部署则更像是一个给开发者的乐高积木你可以深入其中理解MCP服务器的每一行代码甚至基于它定制属于自己的AI数据工具。无论选择哪条路你都在实践一个未来人机协作的重要范式AI负责执行和检索人类负责决策和授权。