Cv MCP Server

碳语音MCP服务器

用于集成的模型上下文协议（MCP）服务器实现 Carbon Voice的API，为人工智能助手提供语音消息、对话和工作空间管理的综合工具。

碳音: https://getcarbon.app

API: https://api.carbonvoice.app/docs

特性

• 消息管理：创建、列出和检索语音消息、对话消息和直接消息
• 用户操作：搜索和检索用户信息
• 会话管理：访问和管理对话及其参与者
• 文件夹操作：创建、组织、移动和管理文件夹及其内容
• 工作区管理：获取工作区信息
• AI行动：运行AI提示并检索AI生成的响应
• 附件支持：向邮件添加链接附件

安全与合规

此服务器完全符合 MCP安全最佳实践:

• OAuth 2.1身份验证：通过适当的令牌处理确保授权流的安全
• HTTPS强制：通过HTTPS服务的所有远程端点
• 会话安全：加密安全会话管理
• 输入验证：全面验证所有用户输入
• 速率限制：内置防滥用保护

出于安全考虑，请联系：devsupport@phononx.com

先决条件

用于标准运输（本地安装）

必修的：

1. Carbon Voice API密钥 -联系Carbon Voice开发团队，索取您的API密钥：

- 📧 联系: devsupport@phononx.com - 📧 主题：“请求MCP服务器的API密钥”

1. npx安装 -你一定有 npx 安装在您的系统上。npx与Node.js（14.8.0或更高版本）捆绑在一起。如果你没有安装Node.js，你可以从以下网址下载 .

要验证您的安装，请运行：

   npx --version

用于HTTP传输（远程）

必修的：

1. 没有什么 -不需要额外的先决条件。HTTP传输版本完全在云中运行，并使用OAuth2身份验证，因此不需要安装API密钥或npx。

配置

快速概览

_建议使用HTTP传输，以便于设置和增强安全性。_

对于光标

HTTP传输（远程）

1. 打开的游标
2. 首选 光标设置 > 特性 > 模型上下文协议
3. 添加新的MCP服务器配置：

{
  "mcpServers": {
    "Carbon Voice": {
      "url": "https://mcp.carbonvoice.app"
    }
  }
}

1. 保存并重新启动游标

第一次使用它时，Cursor将引导您完成OAuth2身份验证过程。

标准运输（本地安装）

如果您更喜欢使用API密钥验证在本地运行MCP服务器：

1. 打开的游标
2. 首选 光标设置 > 特性 > 模型上下文协议
3. 添加新的MCP服务器配置：

{
  "mcpServers": {
    "Carbon Voice": {
      "command": "npx",
      "env": {
        "CARBON_VOICE_API_KEY": "your_api_key_here"
      },
      "args": ["-y", "@carbonvoice/cv-mcp-server"]
    }
  }
}

1. 替换 "your_api_key_here" 使用您实际的Carbon Voice API密钥
2. 保存并重新启动游标

适用于克劳德桌面

HTTP传输（远程）

在Claude Desktop中设置Carbon Voice非常简单！操作方法如下：

1. 打开克劳德桌面 并导航到 搜索和工具

1. 转到管理连接器 然后单击 “添加自定义连接器”

1. 填写连接器详细信息:

- 名字：给它起一个友好的名字，比如“碳之声” - 远程MCP服务器URL：输入 https://mcp.carbonvoice.app

1. 保存连接器

1. 单击连接:

第一次使用它时，Claude将指导您完成OAuth2身份验证过程。您只需使用您的Carbon Voice帐户登录并授予权限。在那之后，你就准备好了！

标准运输（本地安装）

如果您更喜欢使用API密钥验证在本地运行MCP服务器：

1. 打开您的Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 添加Carbon Voice MCP服务器配置：

{
  "mcpServers": {
    "Carbon-Voice": {
      "command": "npx",
      "env": {
        "CARBON_VOICE_API_KEY": "your_api_key_here"
      },
      "args": ["-y", "@carbonvoice/cv-mcp-server"]
    }
  }
}

1. 替换 "your_api_key_here" 使用您实际的Carbon Voice API密钥
2. 保存文件并重新启动Claude Desktop

环境变量（仅适用于Stdio版本）

使用MCP服务器的stdio版本时，您可以配置其他环境变量：

LOG_LEVEL

控制日志输出的详细程度。可用选项：

• info （默认）-标准日志记录信息
• debug -最详细的日志记录，显示详细的请求/响应数据
• warn -只有警告和错误消息
• error -只有错误消息

例子：

{
  "mcpServers": {
    "Carbon-Voice": {
      "command": "npx",
      "env": {
        "CARBON_VOICE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "debug"
      },
      "args": ["-y", "@carbonvoice/cv-mcp-server"]
    }
  }
}

LOG_DIR

指定存储日志文件的目录。默认值为： /tmp/cv-mcp-server/logs

服务器将在此目录中创建两个日志文件：

• combined.log -包含所有日志消息
• error.log -仅包含错误消息

例子：

{
  "mcpServers": {
    "Carbon-Voice": {
      "command": "npx",
      "env": {
        "CARBON_VOICE_API_KEY": "your_api_key_here",
        "LOG_DIR": "/Users/USER_NAME/Documents/cv-mcp-server/logs"
      },
      "args": ["-y", "@carbonvoice/cv-mcp-server"]
    }
  }
}

包含两个变量的完整示例：

{
  "mcpServers": {
    "Carbon-Voice": {
      "command": "npx",
      "env": {
        "CARBON_VOICE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "debug",
        "LOG_DIR": "/Users/USER_NAME/Documents/cv-mcp-server/logs"
      },
      "args": ["-y", "@carbonvoice/cv-mcp-server"]
    }
  }
}

可用工具

消息

• list_messages -列出带有日期筛选的邮件（最大31天范围）
• get_message -按ID检索特定邮件
• get_recent_messages -获取10条最新消息的完整上下文
• create_conversation_message -向对话发送消息
• create_direct_message -向用户或组发送直接消息
• create_voicememo_message -创建语音备忘录消息
• add_attachments_to_message -向现有邮件添加链接附件

用户

• get_user -按ID检索用户信息
• search_user -通过电话号码或电子邮件查找用户
• search_users -通过各种标识符搜索多个用户

交谈

• list_conversations -获取过去6个月的所有对话
• get_conversation -按ID检索对话详细信息
• get_conversation_users -让所有用户参与对话

文件夹

• get_workspace_folders_and_message_counts -获取文件夹和邮件统计信息
• get_root_folders -列出工作区的根文件夹
• create_folder -创建新文件夹
• get_folder -检索文件夹信息
• get_folder_with_messages -获取包含邮件的文件夹
• update_folder_name -重命名文件夹
• delete_folder -删除文件夹(⚠️ 破坏性操作）
• move_folder -在不同位置之间移动文件夹
• move_message_to_folder -将邮件组织到文件夹中

工作区

• get_workspaces_basic_info -获取基本工作空间信息

AI行动

• list_ai_actions -列出可用的AI提示/操作
• run_ai_action -对消息执行AI操作
• run_ai_action_for_shared_link -在共享内容上运行AI操作
• get_ai_action_responses -检索AI生成的响应

使用示例

入门指南

配置后，您可以通过AI助手与Carbon Voice进行交互。以下是一些示例请求：

"Show me my recent messages"
"Create a voice memo about today's meeting"
"Search for user john@example.com"
"Show me my workspace information"
"List my conversations from this week"

使用文件夹

"Create a folder called 'Project Updates'"
"Move message ID 12345 to the Project Updates folder"
"Show me all messages in the Marketing folder"

AI行动

"Run a summary AI action on message ID 67890"
"List all available AI prompts"
"Get AI responses for conversation ID 123"

错误处理

服务器包括全面的错误处理和日志记录。错误以结构化格式返回，其中包括：

• 错误消息
• 状态代码
• 请求上下文
• 调试信息

发展

本节面向希望贡献、实现新功能或解决问题的开发人员。

开发命令

建设与发展

npm run build          # Build the project
npm run auto:build     # Watch mode with auto-rebuild (recommended for development)
npm run lint:fix       # Fix linting issues

API生成

npm run generate:api   # Generate TypeScript types from Carbon Voice API

运行服务器

npm run dev:http       # Start HTTP server in development mode with hot reload
npm run start:http     # Start HTTP server in production mode

MCP检验员测试

设置：复制 .env.sample 向 .env 并配置您的开发环境变量。

npm run mcp:inspector:stdio  # Test stdio transport with MCP Inspector
npm run mcp:inspector:http   # Test HTTP transport with MCP Inspector

对于stdio传输测试：

1. 使用令牌打开生成的URL（例如。， http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=46bfbd8938955be26da7f2089a8cccb7be57ed570e65d8d2d68e95561ed9b79e)
2. 集 传输类型: STDIO
3. 集 命令: node
4. 点击 连接
5. 应看到已连接信息。

对于HTTP传输测试：

1. 使用令牌打开生成的URL
2. 集 传输类型: Streamable HTTP
3. 集 统一资源定位符: http://localhost:3005
4. 单击Auth，然后单击Quick Oauth Flow。
5. 将被重定向到碳语音认证页面。登录后，承载令牌应自动添加到授权请求标头中。
6. 点击 连接
7. 应看到已连接信息。

版本管理

备注：只有合并到主分支的代码才具有 不同版本 从当前版本开始，将创建一个新的Git标签并触发新的npm包发布。CI/CD管道会自动检查中的版本 package.json 在部署和发布之前已更改。

版本命令

npm run version:patch  # Bump patch version (1.0.0 → 1.0.1)
npm run version:minor  # Bump minor version (1.0.0 → 1.1.0)
npm run version:major  # Bump major version (1.0.0 → 2.0.0)

释放命令

npm run release:patch  # Build, test, version patch, and merge to main
npm run release:minor  # Build, test, version minor, and merge to main
npm run release:major  # Build, test, version major, and merge to main
npm run deploy:release # Build, test, and merge to main (no version bump)

开发工作流程示例

致力于发展

# 1. Make your changes and test locally
npm run build
npm run lint:fix

# 2. Commit and push to develop
git add .
git commit -m "feat: add new message filtering feature"
git push origin develop

发布Bug修复

# 1. Test your changes
npm run build
npm run mcp:inspector:http

# 2. Release patch version
npm run release:patch

发布新功能

# 1. Test your changes
npm run build
npm run mcp:inspector:stdio
npm run mcp:inspector:http

# 2. Release minor version
npm run release:minor

开发技巧

• 使用 auto:build 在文件更改时自动重建的开发过程中
• 测试两种运输方式 发布前与MCP检查员进行沟通
• 跑 generate:api 当Carbon Voice API发生变化时
• 使用语义版本控制：补丁用于修复，次要用于功能，主要用于破坏性更改
• 始终进行测试 发布前同时使用stdio和HTTP传输

MCP合规性

此服务器完全符合 模型上下文协议规范 并遵循官方文件中概述的所有安全最佳实践。该实现支持MCP规范中定义的stdio和HTTP传输。

支持

• 问题:
• API密钥请求: devsupport@phononx.com
• 碳语音平台: https://getcarbon.app
• API文档: https://api.carbonvoice.app/docs

许可证

ISC许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

备注：此MCP服务器需要有效的Carbon Voice API密钥才能使用stdio传输。对于HTTP传输，OAuth2身份验证是通过web界面自动处理的。在尝试使用服务器之前，请确保您拥有适当的凭据。