Ethora MCP CLI:连接AI与Web3应用平台的自动化桥梁
1. 项目概述:Ethora MCP CLI,一个连接AI与Web3应用平台的桥梁
如果你正在用Cursor、Claude Desktop或者VS Code的MCP插件,并且你的项目里涉及到聊天机器人、AI客服或者Web3钱包功能,那你可能已经感受到了一个痛点:如何在AI助手的对话环境中,直接操作你的应用后端?比如,让AI帮你创建一个新的聊天应用、上传知识库文档、或者给用户批量发送消息?过去,这通常意味着你要在IDE和浏览器之间来回切换,手动复制粘贴API密钥,写一堆临时的curl命令或者脚本。现在,dappros/ethora-mcp-cli这个项目就是为了解决这个问题而生的。
简单来说,Ethora MCP CLI是一个遵循Model Context Protocol (MCP)标准的命令行工具/服务器。它就像一个“翻译官”,运行在你的本地开发机上,通过标准输入输出(stdio)与你的AI客户端(如Cursor、Claude Desktop)通信。它的核心功能是,将你对Ethora平台的各种操作(管理应用、配置AI机器人、处理文件、操作钱包等)封装成一个个标准的“工具”(Tools),然后暴露给你的AI助手。这样,你就能直接用自然语言指挥AI去完成这些任务,比如“帮我在Ethora上创建一个名为‘客服助手’的应用,并启用AI机器人”。
我花了些时间深入测试了这个工具,发现它特别适合两类场景:一是个人开发者或小团队快速原型验证,你可以让AI帮你完成从应用创建、知识库构建到机器人上线的全流程;二是企业级的自动化工作流,比如定期从某个网站抓取内容更新知识库,或者批量创建测试用户。它把复杂的API调用和认证流程都封装好了,你只需要关注业务逻辑。接下来,我会拆解它的两种核心使用模式、详细的操作步骤,并分享一些从实际配置和调试中总结出来的经验,帮你避开我踩过的那些坑。
2. 核心架构与两种认证模式解析
要玩转这个工具,首先必须理解它的两种核心认证模式:用户认证模式和B2B模式。这不仅仅是登录方式的不同,更决定了你能操作的API路径、拥有的权限以及适合的自动化场景。选错了模式,你可能会发现很多工具调用不了,或者无法实现你想要的自动化效果。
2.1 用户认证模式:手动操作与探索的起点
用户认证模式模拟的是一个真实用户通过前端界面进行操作的过程。你需要一个ETHORA_APP_JWT。这个JWT通常从Ethora平台的前端应用配置中获取,它标识了你的应用,但初始状态下并没有绑定任何具体的用户身份。
这个模式下的典型流程是:
- 配置引导令牌:通过环境变量或
ethora-configure工具,设置ETHORA_APP_JWT和API地址。 - 切换认证模式:调用
ethora-auth-use-user,告诉服务器后续操作将使用用户会话。 - 用户登录:调用
ethora-user-login,提供邮箱和密码,在服务器端建立一个用户会话。这一步是关键,它利用APP_JWT完成了应用级别的认证,并创建了用户级别的会话。 - 执行用户操作:之后,你就可以调用诸如
ethora-files-upload-v2(上传文件)、ethora-wallet-get-balance(查询钱包余额)等需要用户身份的工具。
注意:
ETHORA_APP_JWT在这里仅仅是一个“敲门砖”,用于引导登录流程。真正的权限来自于登录后的用户会话。这意味着,如果你在多个地方使用同一个APP_JWT,但登录了不同的用户,那么各自的操作权限和数据访问范围将由对应的用户身份决定。
适用场景:
- 初次体验和功能探索:当你刚接触Ethora,想快速看看后台有哪些功能,上传些测试文件,或者测试钱包转账时。
- 租户管理员手动管理:作为某个应用的所有者,你需要临时处理一些用户文件、查看聊天记录等。
- 需要操作“用户维度”资源时:所有
/v1接口的遗留功能,以及那些明确需要用户上下文(如“我的文件”)的操作。
2.2 B2B模式:自动化与集成的核心
B2B模式是为服务器到服务器(Server-to-Server)的集成而设计的,它不需要前端用户登录。其核心凭证是一个ETHORA_B2B_TOKEN。这个令牌通常由Ethora平台的管理员在后台生成,类型为server,它直接代表一个“租户执行者”(tenant actor),拥有较高的权限。
这个模式下的权限和流程特点:
- 直接的高权限操作:配置好
ETHORA_B2B_TOKEN后,调用ethora-auth-use-b2b,即可直接使用所有以ethora-b2b-为前缀的工具,以及那些需要显式传递appId参数的/v2接口工具(如ethora-chats-broadcast-v2)。 - 应用令牌管理:B2B模式的一个核心能力是管理应用令牌(App Tokens)。你可以通过
ethora-app-tokens-create-v2为一个特定的应用生成一个appToken。这个appToken是应用级别的长期凭证,一旦生成,就可以在ethora-auth-use-app模式下使用,用于该应用范围内的所有自动化操作(如发送消息、管理知识源)。 - 完整的应用生命周期管理:从
ethora-b2b-app-create创建应用,到ethora-b2b-app-provision一站式配置应用(创建令牌、预设聊天室、配置机器人),都可以在B2B模式下完成。
适用场景:
- 后端服务集成:你的后台系统需要定期向Ethora应用中的用户发送通知或广播消息。
- 合作伙伴入驻自动化:为每个新合作伙伴自动创建独立的应用空间并完成基础配置。
- 无人值守的AI智能体:一个自主运行的AI Agent需要根据某些事件(如订单创建)在Ethora中执行操作,而无需人工干预登录。
- CI/CD流水线:在部署流程中自动为测试环境创建或更新应用配置。
2.3 模式选择与切换的心得
在实际使用中,我总结出一个简单的经验法则:
- “从用户开始,向B2B演进”:如果你是第一次在本地尝试,或者进行一些临时性的手动操作,从用户认证模式开始是最直观的。
- “为自动化而生”:任何计划投入生产环境、需要重复执行或由程序触发的任务,都应该基于B2B模式来设计。你可以先用B2B模式创建应用和
appToken,然后让自动化脚本使用appToken进行应用级别的精细操作。
一个常见的混合工作流是:
- 使用B2B令牌创建应用和
appToken。 - 切换到
appToken认证模式 (ethora-auth-use-app)。 - 在该模式下,执行针对这个应用的所有日常自动化任务,如更新知识源、查询机器人状态等。这样既安全(权限限定在单个应用),又方便。
重要安全提示:
ETHORA_B2B_TOKEN权限极高,务必像保护根密码一样保护它。永远不要将其提交到代码仓库。应该通过环境变量、安全的密钥管理服务(如AWS Secrets Manager, HashiCorp Vault)或MCP客户端自带的秘密存储功能来传递。对于appToken,也应遵循同样的原则,并且定期轮换。
3. 从零开始:环境配置与工具连接实战
理解了模式,我们开始动手。这部分我会带你完成从安装到第一个成功调用的全过程,并穿插一些配置上的细节和常见问题。
3.1 基础环境准备与安装
首先,确保你的开发环境符合要求:
- Node.js: 版本需要18.x或更高。你可以通过
node --version命令检查。我推荐使用nvm(Node Version Manager)来管理多个Node版本,这样可以轻松切换。 - 包管理器:
npm或yarn均可,工具通过npx调用,无需全局安装。
安装极其简单,因为MCP客户端会在需要时动态调用。但为了测试,你可以先在终端里运行一下,确保它能正常启动:
npx -y @ethora/mcp-server如果看到一些启动日志(可能提示缺少配置),没有报错退出,就说明基础包没问题。
3.2 配置管理:环境变量与运行时配置
工具支持两种配置方式,我建议结合使用。
方式一:环境变量(推荐用于固定值)在你的Shell配置文件(如.bashrc,.zshrc)或项目.env文件中设置:
# 设置API地址(如果你使用官方云服务) export ETHORA_API_URL=https://api.chat.ethora.com/v1 # 或者使用基础URL,工具会自动补上/v1 # export ETHORA_BASE_URL=https://api.chat.ethora.com # 设置你的B2B令牌(用于自动化) export ETHORA_B2B_TOKEN=your_super_secret_b2b_token_here # 设置你的App JWT(用于手动登录探索) export ETHORA_APP_JWT=JWT your_app_jwt_here踩坑记录:
ETHORA_APP_JWT的值有时是从Ethora管理界面复制出来的,可能已经包含了JWT前缀。在设置环境变量时,确保整个字符串都被正确引用,避免空格或换行符被截断。最稳妥的方式是把它放在单引号里:export ETHORA_APP_JWT='JWT eyJ...'。
方式二:运行时配置(ethora-configure工具)对于临时测试,或者你的MCP客户端环境不方便设置复杂环境变量时,可以使用这个工具。在AI客户端(如Cursor)中直接告诉AI:“调用ethora-configure工具,设置apiUrl为https://api.chat.ethora.com/v1,设置b2bToken为xxx。” 这种方式配置的凭证仅存在于当前MCP服务器进程的内存中,进程重启后就失效了,适合快速测试。
3.3 连接主流MCP客户端
这里以Cursor和Claude Desktop为例,展示具体的配置步骤。VS Code和Windsurf的配置逻辑类似。
在Cursor中配置:
- 打开Cursor,进入
Settings(或Cmd + ,)。 - 在侧边栏找到
MCP选项。 - 点击
Add new global MCP server。 - 在弹出的表单中,按以下格式填写:
- Name: 可以自定义,比如
ethora。 - Command: 填写
npx。 - Args: 填写
-y,@ethora/mcp-server(分两行或空格分隔,取决于UI)。
- Name: 可以自定义,比如
- 保存后,如果配置正确且网络通畅,你会看到服务器状态显示为绿色的“Active”。
在Claude Desktop中配置:
- 打开Claude Desktop应用。
- 点击左上角
Claude菜单,选择Settings->Developer。 - 点击
Edit Config,这会打开一个JSON配置文件(通常在~/Library/Application Support/Claude/claude_desktop_config.json)。 - 在JSON中,添加或修改
mcpServers部分:{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } } - 保存配置文件并完全重启Claude Desktop。重启后,你可以在与Claude的对话中尝试让它列出可用工具来验证。
连接验证技巧: 连接成功后,你可以在客户端里让AI助手执行“列出所有可用的工具”或类似指令。在Cursor中,你可以直接输入/list_tools(如果支持)。如果看到一系列以ethora-开头的工具名,恭喜你,连接成功了!如果没看到,首先检查MCP服务器的配置是否已保存并启用,然后查看客户端的错误日志。一个常见的初期错误是Node版本过低。
4. 核心工具链详解与自动化工作流构建
工具连接成功后,面对几十个工具,从哪里开始?我将其分为几个核心功能组,并构建了两个最常用的自动化工作流。
4.1 应用与机器人生命周期管理
这是B2B模式的核心价值所在。假设我们要为一个新客户“Acme Corp”自动化搭建一个支持AI的客服应用。
工作流一:一键式应用创建与AI机器人引导目标是执行一个命令,完成:创建应用 -> 配置知识源 -> 启用AI机器人。 这可以通过ethora-b2b-app-bootstrap-ai工具一站式完成。
操作步骤与参数详解:
- 确保处于B2B模式:先调用
ethora-auth-use-b2b。 - 调用引导工具:关键是如何构建输入参数。以下是一个功能丰富的示例:
{ "displayName": "Acme Corp - 智能客服", "savedAgentId": "可选,如果已有保存的智能体配置ID", "crawlUrl": "https://support.acmecorp.com/faq", "followLink": true, "docs": [ { "name": "产品手册.pdf", "mimeType": "application/pdf", "base64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nF2T3Y6bMBCF7/k..." } ], "enableBot": true, "botTrigger": "/ask", "botPrompt": "你是Acme Corp的官方客服助手,专业、友好且乐于助人。请根据提供的知识库回答用户关于产品、服务和政策的问题。如果问题超出知识范围,请礼貌地引导用户联系人工客服。", "llmProvider": "openai", "llmModel": "gpt-4o-mini" }displayName: 应用名称,必填。crawlUrl和docs: 可以二选一或同时提供,用于构建初始知识库。followLink: true会让爬虫抓取该页面链接的内容,适合构建网站知识库。enableBot: 设为true以立即启用机器人。botPrompt: 这是机器人的系统指令,至关重要。它定义了机器人的角色和行为边界。写一个好的prompt是机器人表现好坏的关键。llmProvider和llmModel: 指定底层大模型。这里有个大坑:你填写的provider和model必须在你的Ethora后端环境和AI服务中已被启用和配置。如果配置错误,机器人可能无法响应或使用默认模型。如果不确定,可以先不填,使用后端默认配置。
工作流二:精细化的应用配置与编排如果bootstrap-ai工具的功能不满足你,或者你想分步控制,可以使用更底层的工具组合:
ethora-b2b-app-create: 创建应用,获取appId。ethora-app-select: 选择刚创建的应用,并可选地为其创建appToken。ethora-auth-use-app: 切换到应用令牌模式,进行后续操作。ethora-sources-site-crawl-v2: 爬取网站知识。ethora-sources-docs-upload-v2: 上传文档知识。ethora-bot-update-v2: 配置机器人提示词、触发词等。ethora-bot-enable-v2: 启用机器人。
这种方式步骤多,但灵活性极高,适合集成到现有的复杂运维脚本中。
4.2 消息广播与用户批量操作
对于运营和测试场景,批量操作工具非常有用。
消息广播 (ethora-chats-broadcast-v2): 用于向应用内的所有用户或特定用户群发送一条消息。这在发布公告、活动通知时非常有用。
{ "appId": "你的应用ID", "message": "亲爱的用户,系统将于今晚24点至明早6点进行升级维护,期间服务可能短暂中断,敬请谅解。", "roomType": "group", // 或 "private" "targetUserIds": ["可选,指定用户ID数组"], // 如果为空,则发给所有用户 "senderName": "系统通知" }调用后会返回一个jobId,你可以用ethora-chats-broadcast-job-v2查询状态,或用ethora-wait-broadcast-job-v2阻塞等待完成。
用户批量创建 (ethora-users-batch-create-v2): 在B2B模式下,可以异步批量创建用户。这对于初始化测试数据或导入用户列表至关重要。 你需要准备一个CSV格式的字符串或用户对象数组。工具会创建一个后台任务,返回jobId供查询。
4.3 知识源管理与RAG增强
AI机器人的回答质量很大程度上依赖于知识源。MCP CLI提供了完备的知识源管理工具。
核心操作:
- 列表查询:
ethora-sources-site-list-v2和ethora-sources-docs-list-v2可以列出所有已爬取或上传的知识源,查看其ID、状态和现有标签。 - 标签管理:这是优化检索效果的关键。你可以使用
ethora-sources-site-tags-update-v2和ethora-sources-docs-tags-update-v2为知识源打上标签。
在机器人检索时,可以结合用户问题上下文和标签进行更精准的匹配。合理的标签体系能极大提升回答的准确率。{ "sourceId": "爬取任务的ID", "tags": ["产品介绍", "v2.0", "常见问题"] } - 重新索引:如果源网站内容更新了,可以调用
ethora-sources-site-reindex-v2对指定的URL进行重新抓取和索引。 - 删除操作:谨慎使用
ethora-sources-site-delete-url-v2-batch等删除工具。建议先列表确认,再操作。
实操心得:知识源的质量控制
- 从小范围开始:不要一开始就爬取整个大型网站。先选择最重要的几个页面(如首页、FAQ、核心产品页)进行爬取测试,查看索引效果和机器人回答质量。
- 利用标签进行分类:按照主题、部门、产品线、文档类型等维度设计标签体系。例如,
["技术文档”, “API”, “v1.2”],["人力资源”, “请假政策”, “2024”]。 - 监控索引状态:上传或爬取后,通过列表工具检查状态是否为
indexed。如果状态长时间处于processing或failed,需要检查源内容是否可访问、格式是否支持。
4.4 钱包与ERC-20代币操作
这是一个体现Ethora Web3特性的功能组。请注意,涉及资产转移的工具默认是禁用的,需要在环境变量中设置ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true才会暴露。
典型操作流程:
- 查询余额(
ethora-wallet-get-balance):在用户认证模式下,登录后可以查询当前用户钱包中各种ERC-20代币的余额。 - 转账(
ethora-wallet-erc20-transfer):危险操作!需要提供代币合约地址、接收方地址和金额。务必在测试网或确保金额极小的情况下操作,并仔细核对地址。{ "contractAddress": "0x... (代币合约地址)", "to": "0x... (接收地址)", "amount": "0.5" // 金额,注意单位通常是代币的最小单位,需根据代币的decimals调整 }
重要警告:钱包操作,特别是转账,涉及真实的链上资产。务必确保:
- 你完全理解所操作代币的合约和精度(decimals)。
- 接收地址绝对正确,区块链交易不可逆。
- 仅在绝对必要时启用危险工具,并在操作完成后考虑禁用。
5. 故障排查与最佳实践指南
即使按照指南操作,也难免会遇到问题。下面是我在实战中总结的常见问题及其解决方法。
5.1 连接与认证类问题
问题1:MCP客户端显示服务器未连接或工具列表为空。
- 检查Node版本:运行
node --version,确保是18.x或以上。 - 检查命令路径:确认在MCP配置中,
npx命令在系统PATH中可用。可以尝试在终端直接运行npx -y @ethora/mcp-server看是否有报错。 - 查看客户端日志:Cursor、Claude Desktop等客户端通常有输出日志的地方(如Cursor的MCP设置面板、Claude Desktop的开发者控制台),查看是否有连接错误信息。
- 网络问题:如果
ETHORA_API_URL设置的是远程地址,确保你的网络可以访问该地址。尝试用curl命令测试连通性。
问题2:调用工具时出现“Auth required”或“Invalid token”错误。
- 确认当前认证模式:先调用
ethora-status工具,查看activeAuthMode。你想调用的工具可能需要特定的模式(User, B2B, App)。 - 检查令牌有效性:
- 对于
ETHORA_APP_JWT,确保它没有过期,并且是从正确的应用配置中获取的。 - 对于
ETHORA_B2B_TOKEN,确保它有足够的权限执行当前操作(例如,创建应用需要租户级别的权限)。
- 对于
- 令牌格式:确保令牌字符串完整,没有意外的换行或空格。特别是从网页复制JWT时,注意是否包含了多余字符。
问题3:调用B2B工具时提示“appId not found”或权限错误。
- 显式传递appId:许多
/v2工具在B2B模式下需要你在参数中显式提供appId。即使你之前用ethora-app-select选过,在B2B模式下也可能不生效。仔细查看工具的文档说明。 - 切换模式:如果你要操作某个特定应用下的资源(如管理该应用的机器人),更简单的方法是先用B2B模式创建
appToken,然后切换到ethora-auth-use-app模式。在这个模式下,appId和appToken是绑定的,无需再显式传递。
5.2 工具执行与业务逻辑类问题
问题4:ethora-b2b-app-bootstrap-ai执行成功,但机器人无法回答或知识源未生效。
- 检查机器人状态:调用
ethora-bot-get-v2,确认enabled是否为true,以及llmProvider和llmModel是否已正确设置且被后端支持。 - 检查知识源状态:调用
ethora-sources-site-list-v2和ethora-sources-docs-list-v2,查看爬取或上传的任务状态是否为indexed。如果是failed或processing,需要根据错误信息排查(如URL无法访问、文档格式解析失败)。 - 验证AI服务配置:这个问题通常不在MCP客户端层面。需要联系Ethora后端管理员,确认AI服务(如OpenAI API)的配置、额度以及模型可用性。
问题5:广播消息或批量创建用户任务长时间处于“pending”状态。
- 使用等待工具:对于广播和批量用户创建这类异步任务,不要只调用一次创建工具就完了。应该使用对应的
ethora-wait-*-job-v2工具(如ethora-wait-broadcast-job-v2),它会轮询直到任务完成或失败,并返回最终结果。 - 检查任务规模:如果批量操作的数量非常大(例如上万用户),处理时间会相应变长。这是正常现象。
- 查看错误详情:如果任务失败,
wait工具或查询任务状态的工具会返回详细的错误信息,根据信息排查(如数据格式错误、权限不足等)。
5.3 安全与运维最佳实践
凭证管理是第一要务:
- 永远不要将
ETHORA_B2B_TOKEN、ETHORA_APP_JWT或任何appToken硬编码在代码中或提交到版本控制系统(如Git)。 - 使用秘密管理:在本地开发时,使用
.env文件(并确保.env在.gitignore中)。在服务器或CI/CD环境中,使用平台提供的秘密管理服务(如GitHub Secrets, GitLab CI Variables, AWS Secrets Manager)。 - 最小权限原则:为不同的自动化场景创建不同的
appToken,并仅授予必要的权限。避免所有场景都使用高权限的B2B令牌。
- 永远不要将
利用“医生”工具进行诊断: 在遇到任何疑难杂症时,首先调用
ethora-doctor工具。它会检查配置的完整性、网络连通性(对API的ping测试)以及基础认证是否通过,并给出清晰的提示,是快速定位配置问题的利器。设计健壮的自动化脚本:
- 错误处理:MCP工具返回的响应信封(
{ok, data, error})是统一的。在你的自动化逻辑中,一定要检查ok字段是否为true,并处理error情况。 - 异步任务轮询:对于广播、批量用户创建等异步操作,务必实现轮询逻辑(或直接使用
wait工具),直到任务完成,而不是假设它会立即成功。 - 日志与监控:记录关键操作的工具调用和结果,便于事后审计和问题排查。
- 错误处理:MCP工具返回的响应信封(
版本与兼容性: 关注Ethora MCP CLI的版本更新。不同版本的工具集可能有细微差别。在升级版本后,如果原有脚本出现问题,首先查阅对应版本的README或更新日志,检查是否有破坏性变更。
通过这套MCP工具链,你将能以一种前所未有的、高度集成的方式与Ethora平台交互。它不仅仅是API的包装,更是将平台能力无缝嵌入到你的AI辅助开发工作流中的关键组件。从快速原型设计到生产级自动化,熟练掌握它,能显著提升你在构建AI和Web3融合应用时的效率。
