Zelinqa MCP

安装 · 示例 · 工具 · 配置 · 运维 · Français

对话由你的助手处理，接下来该问什么由 Zelinqa 决定。 在 Zelinqa Studio 中一次性描述对话需要了解什么。此服务为任何 MCP 主机提供运行该对话所需的工具：启动对话、传递每条回复、获取下一个问题、记录结果。模型只会看到问题文本、选项标签和对话名称。会话、决策和状态标识符都保留在服务内部。

更少的令牌、确定性、可解释性

引擎负责选择问题，因此模型不再生成问题，也不再重复提问：同样的对话所需令牌更少。选择本身是从你发布的领域中选取，而非生成：相同状态始终会产生相同问题，每项决策都包含该问题收集的信息、每个维度的进度以及明确的停止原因，因此对话事后可以审计。令牌数据：内部测试平台，2026 年 9 月：使用同一助手重放 700 多场对话两次，一次独立运行，一次由 Zelinqa 引擎引导；两种情况下均以相同方式重放模拟受访者。测试方法、数据和局限：阅读测试平台报告。计划于 2026 年底前发布一项包含共享数据和代码的科学基准测试。

为什么

任何需要先提问再做决定的助手，无论用于面试、资格审核、指导、分诊还是推荐，都会即兴编写问题，并在信息不完整的情况下做出决定。使用此服务后，引擎会根据你已发布的领域运行提问阶段，模型只需在完整、类型化的状态下做出一次决定。

安装

你需要安装 Python 3.11+ 和 uv，并准备一个在 Zelinqa Studio 中为已发布领域创建的运行时 API 密钥。免费 Developer 版本账户即可满足需求。

也可以手动将服务添加到你的宿主端。所有环境使用相同的命令：uvx zelinqa-mcp，并将密钥放在宿主端的机密环境变量中。

claude mcp add zelinqa \
  -e ZELINQA_API_KEY=YOUR_RUNTIME_API_KEY \
  -- uvx zelinqa-mcp

{
  "mcpServers": {
    "zelinqa": {
      "command": "uvx",
      "args": ["zelinqa-mcp"],
      "env": {
        "ZELINQA_API_KEY": "YOUR_RUNTIME_API_KEY"
      }
    }
  }
}

[mcp_servers.zelinqa]
command = "uvx"
args = ["zelinqa-mcp"]
env = { ZELINQA_API_KEY = "YOUR_RUNTIME_API_KEY" }

git clone https://github.com/Zelinqa/zelinqa-mcp.git
cd zelinqa-mcp
uv sync --group dev --locked
uv run zelinqa-mcp --version

examples/ 中提供了适用于各宿主端、可直接复制的文件。请遵循宿主端的工具审批策略：某些调用会创建会话并提交反馈。

四次工具调用完成一次对话

模型调用 zelinqa_start，用自己的话询问返回的问题，将对方的回复传给 zelinqa_next_question，并重复此过程，直到引擎停止。最后，模型会记录实际发生的情况。

▶ zelinqa_start           {"conversation": "lead-42"}
◀ ask  ·  "Which budget range are you considering this year?"
          choices: Under €10k · €10k to €50k · Over €50k

▶ zelinqa_next_question   {"conversation": "lead-42", "choice_labels": ["€10k to €50k"]}
◀ ask  ·  "When would you like to start?"
          progress: budget covered · timeline not started

▶ zelinqa_next_question   {"conversation": "lead-42", "user_text": "Next quarter, after the sales kickoff."}
◀ stop ·  objective achieved

▶ zelinqa_feedback        {"conversation": "lead-42", "result": "success"}

如果调用 zelinqa_next_question 时没有提供回复，它只会重新显示待回答的问题。如果 CRM 已经知道某个答案，zelinqa_adjust 可以直接记录，无需提问。zelinqa_adjust 和 zelinqa_add_context 可以替换待回答的问题，例如，当它询问的信息现在已知时：务必询问它们返回的问题。完整的回答规则请参阅 docs/operations.md。

工具

结果包含问题文本、排名、选项标签、目标进度和计数器；下一步决策结果还会添加警告、停止原因和降级模式原因。达到 max_turns 时，结果会包含 action: "stop" 和 stop_reason: "max_turns_reached"，之后的调用会返回相同的停止结果。达到轮数上限并不能证明已实现目标。

zelinqa-mcp --advanced 会将业务工具替换为六个可显示 API 标识符和完整状态的低级工具。请参阅 docs/operations.md。

配置

安全与状态

• 传输方式为 stdio，每个受信任的宿主和用户对应一个隔离进程。在实现身份验证和会话隔离之前，HTTP 托管功能处于禁用状态。日志写入 stderr；stdout 专用于 MCP。
• 服务器最多在内存中保存 128 个具名对话，且不会静默逐出对话。名称仅在进程内有效：若要在重启后继续使用，宿主需保留 API 会话 ID，并在模型之外注入上述恢复变量。
• 修改同一对话的调用必须顺序执行；同时调用时会被拒绝，而不会基于过期状态作答。发生冲突后，请调用 zelinqa_status 并协调状态，然后再作答。

详细信息、重试语义和测试套件： docs/operations.md。漏洞报告：SECURITY.md。

相关链接

• zelinqa-sdk：此服务器基于该 Python 和 TypeScript 客户端构建，适用于直接调用 API 的应用。
• docs.zelinqa.ai：概念介绍、Studio 指南和 API 参考。

许可证

Apache-2.0。发布步骤见 RELEASING.md。