aethis-mcp

---

安装

规则编写功能处于私人测试阶段。 决策工具（aethis_decide、aethis_schema、aethis_explain、aethis_next_question）已公开提供，无需密钥。规则编写工具（规则生成、测试优化、发布）需要邀请。请前往 aethis.ai/developer-access 申请访问权限。

推荐方式——通过 aethis-cli 执行一条命令：

uv tool install aethis-cli
aethis mcp install --target all

将服务接入 claude-code、cursor、claude-desktop 或 windsurf。此操作具有幂等性。重启编辑器以应用更改。运行 aethis account generate 轮换密钥后，请重新运行。完整选项：aethis mcp install --help。

手动安装：

claude mcp add aethis -- npx -y aethis-mcp

Cursor / Claude Desktop / Windsurf 的手动配置请参阅设置。

要为 AI 编码 Agent 完成端到端接入？请参阅 docs.aethis.ai/agents/onboarding——在一个页面中了解安装、验证、身份验证和工作流模式。

---

技能

安装 MCP 服务后，可通过 aethis-skills 添加可重复使用的 Agent 工作流：

npx skills add Aethis-ai/aethis-skills

该技能包提供政策转规则集、测试/优化/发布循环、带追踪的决策以及回归比较等工作流。它会调用此软件包中的 MCP 工具，不会取代 MCP 服务。

---

快速开始

aethis_decide({
  ruleset_id: "aethis/spacecraft-crew-certification",
  field_values: { "space.crew.species": "Vogon" },
  include_trace: true
})

{
  "decision": "not_eligible",
  "fields_provided": 1,
  "fields_evaluated": 11,
  "trace": {
    "species_check": "FAIL — species is 'Vogon' (disqualifying, Section 3)"
  }
}

公开规则集无需密钥即可使用。浏览方式：aethis_discover_rulesets({}) 或访问 docs.aethis.ai。

引擎确定性与准确性基准测试：Aethis-ai/confidently-wrong-benchmark。

---

工具

6 个分组中共有 35 个工具。

分组	访问权限	工具
决策	公开	aethis_decide、aethis_schema、aethis_next_question、aethis_explain、aethis_explain_failure、aethis_graph
发现 — 公开目录	公开	aethis_discover_rulesets
发现 — 你的租户	私有测试版	aethis_list_projects、aethis_list_rulesets、aethis_list_rulebooks、aethis_rulebook_schema
创作 — 规则手册	私有测试版	aethis_create_rulebook、aethis_update_rulebook
创作 — 章节和字段	私有测试版	aethis_discover_sections、aethis_refine_sections、aethis_validate_sections、aethis_set_field_spec、aethis_discover_fields、aethis_refine_fields、aethis_validate_fields
创作 — 生成	私有测试版	aethis_create_ruleset、aethis_set_tests、aethis_add_guidance、aethis_list_guidance、aethis_generate_and_test、aethis_generation_status、aethis_cancel_generation、aethis_refine、aethis_publish、aethis_add_domain_guidance、aethis_list_domain_guidance
管理	私有测试版	aethis_archive_project、aethis_archive_ruleset

aethis_graph 可用于公开示例规则集（ruleset_id），也可在租户范围内用于规则手册（rulebook_id）——它会返回规则集地图图表（{nodes, edges, sections, stats}，每个节点包含 display.sentence/display.routes/display.expr），以及可直接渲染的 mermaid 图表字符串。将 include_graph_overlay: true 传给 aethis_decide，即可获取同一图表，并在其上标注特定决策的各项标准状态（satisfied/not_satisfied/pending）（响应中的 graph_overlay）——展示这些输入当前进展的“你在这里”地图。

aethis_create_rulebook / aethis_update_rulebook 用于管理规则手册的身份信息（名称/领域/slug/描述）和 robot_hints——按对话阶段键控、为对话 Agent 提供的自然语言指引。当前启用的阶段：general_context、preamble、session_start、postamble、session_end、stuck。预留阶段（已接受，尚未生效）：persona、conversational_style、section_transition。通过 outcome_logic 组合规则集是另一项规模更大的功能，目前尚不由这两个工具支持。

工作流

评估资格（2 次调用）：

aethis_schema(ruleset_id)          → fields needed
aethis_decide(ruleset_id, fields)  → eligible / not_eligible / undetermined

传入 include_trace: true 可获取逐项标准评估轨迹。传入 include_explanation: true 可获取易于理解的规则描述。

aethis_decide 接受 ruleset_id（单个规则集，可以是公开的）或 rulebook_id（组合式多规则集规则手册）——两者不能同时使用。规则手册决策始终需要 API 密钥（AETHIS_API_KEY）；匿名调用者会收到 HTTP 401。aethis_graph 对底层地图也采用相同的 ruleset_id/rulebook_id 区分方式。

对话式资格评估（下一问题路由）：

aethis_next_question(ruleset_id, field_values)

返回最有信息量的后续问题，以及剩余问题的 optimal_path。每次回答后再次调用；引擎会根据更新后的状态重新计算。达到可作出决策的条件后停止。

创作（私有测试版）：请参阅创作。

提示词

提示词	描述
aethis-author	逐步执行的 TDD 创作工作流
aethis-decide	决策工作流指南；接受可选的 ruleset_id

---

设置

决策工具无需密钥即可使用。如需受邀使用创作功能，请运行 aethis login，然后使用 aethis mcp install --target <client> 安装。安装程序会引用已保存的配置文件，因此主机配置中不会包含 API 密钥。

Claude Code

# Decision tools only
claude mcp add aethis -- npx -y aethis-mcp

# With authoring access
claude mcp add aethis -e AETHIS_PROFILE=default -e XDG_CONFIG_HOME=/absolute/path/to/config -- npx -y aethis-mcp

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "aethis": {
      "command": "npx",
      "args": ["-y", "aethis-mcp"]
    }
  }
}

用于创作时，添加 "env": { "AETHIS_PROFILE": "default", "XDG_CONFIG_HOME": "/absolute/path/to/config" }。请使用已保存的配置文件名称，以及包含 aethis/credentials 的绝对目录（通常是主目录下的 .config）。

Cursor / Windsurf

添加到 ~/.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json（JSON 结构相同）。

密钥

• AETHIS_PROFILE — 非机密的已保存配置文件名称。它会固定此注册使用的账户和端点，即使 CLI 的 active_profile 之后发生变化也不受影响。
• XDG_CONFIG_HOME — 包含 aethis/credentials 的绝对配置目录。不接受相对路径，也不接受指向主目录/配置目录之外的凭据符号链接；凭据文件不得设置组用户或其他用户的权限位（通常为 0600）。
• AETHIS_API_KEY — 可选的显式进程环境变量，用于覆盖平台密钥。安装时优先引用已保存的配置文件；避免将原始密钥写入主机配置或命令参数。主机必须安全地提供进程环境变量，且不一定会继承 shell 环境变量。
• AETHIS_ANTHROPIC_KEY_ENV — 保存 Anthropic 密钥的环境变量的名称，Aethis 创作工具可以使用该密钥（例如 AETHIS_ANTHROPIC_KEY）。除非设置此变量，否则服务绝不会从环境变量中读取提供方密钥。请参阅安全传递 Anthropic 密钥。
• 通过 aethis account generate + aethis account revoke <key_id> 轮换密钥。每台机器生成一个密钥，以便精准撤销。

凭据优先级和重启行为

MCP 会将 CLI 凭据文件解析为 YAML。AETHIS_PROFILE 用于选择指定名称的配置文件；否则会选择文件中的 active_profile（或 default）。配置文件会同时提供 API 密钥和 base_url；默认端点为 https://api.aethis.ai。显式设置 AETHIS_PROFILE 时，AETHIS_API_KEY 和 AETHIS_BASE_URL 会分别有意覆盖对应值。未显式选择配置文件时，AETHIS_API_KEY 会使用 AETHIS_BASE_URL 或默认端点，并忽略隐式激活的配置文件（包括隐式匿名配置）。显式选择的配置文件缺失或格式错误时，会明确报错，即使设置了环境变量覆盖项也是如此。显式设置 AETHIS_PROFILE=anonymous 始终不会进行身份验证。完成匿名设置后，运行 aethis login，然后重新安装以引用已保存的创作配置文件，再重启主机。

已保存的配置文件优先于旧版 macOS 钥匙串条目。如果未配置配置文件，也未显式选择名称，MCP 可以使用旧版默认钥匙串条目，然后使用更早的扁平 credentials.yaml 文件。aethis/credentials 中扁平格式的 api_key/base_url 文件仍受支持。等待登录的已配置配置文件会保持未认证状态，而不会借用其他已存储的密钥。

服务会在重启前始终使用配对的启动身份验证密钥和端点。如果启动时没有密钥，经过身份验证的工具可以获取之后针对同一端点完成的登录信息。端点发生变化时会明确拒绝操作：请重启 MCP 主机以加载新的配对信息。启动时的 stderr 只会报告凭据来源，绝不显示密钥值。

安全地提供 Anthropic 密钥

创作工具（aethis_generate_and_test、aethis_refine、aethis_discover_fields、aethis_refine_fields、aethis_discover_sections、aethis_refine_sections）每次调用都需要 Anthropic API 密钥。以下是三种受支持的形式，按优先顺序排列：

只有在你为 Aethis 配置了提供方密钥时，服务才会向 Aethis 发送该密钥。它不会自行从你的环境中读取 ANTHROPIC_API_KEY（或任何其他变量）；如果宿主模型在工具调用中提供的环境变量名称不是你配置的名称，也会被拒绝。只接受 Anthropic 密钥（sk-ant-…）；其他内容会在本地被拒绝，不会发送。

1. AETHIS_ANTHROPIC_KEY_ENV（推荐）。在 MCP 服务配置中，将密钥放入专用环境变量，并在 AETHIS_ANTHROPIC_KEY_ENV 中指定该变量名。工具随后会自动使用它。原始值不会出现在工具调用负载中，因此不会写入 MCP 宿主磁盘上的会话记录。

   // claude_desktop_config.json
   {
     "mcpServers": {
       "aethis": {
         "command": "npx",
         "args": ["aethis-mcp"],
         "env": {
           "AETHIS_PROFILE": "default",
           "XDG_CONFIG_HOME": "/absolute/path/to/config",
           "AETHIS_ANTHROPIC_KEY_ENV": "AETHIS_ANTHROPIC_KEY",
           "AETHIS_ANTHROPIC_KEY": "sk-ant-..."   // never echoed back to the LLM
         }
       }
     }
   }
   

   aethis_generate_and_test({ project_id })   // uses the configured key
   

2. anthropic_key_keychain（macOS）。钥匙串引用，可以是 "account"（服务默认值为 aethis-anthropic-key）或 "service:account"。使用 security add-generic-password -U -s aethis-anthropic-key -a my-anthropic -w 'sk-ant-...' 将密钥存储一次，然后调用：

   aethis_generate_and_test({ project_id, anthropic_key_keychain: "my-anthropic" })
   

3. anthropic_key（已弃用）。将原始密钥作为工具参数传入。为保持向后兼容而接受此形式，但原始值会逐字写入宿主磁盘上的会话记录 JSONL。如果曾以这种方式传入密钥，请先轮换密钥，再使用更安全的形式。

---

创作（私有测试版）

创作需要邀请。申请访问权限。决策工具（上文所述）为公开工具。

三阶段工作流。阶段 1–2 适用于多章节领域；对于单章节规则，请跳过这两个阶段，直接进入阶段 3。

阶段 1 — 章节发现

aethis_discover_sections({ domain, sources: [{ name, content }, ...] })
aethis_validate_sections({ domain, expected_sections, discovered_sections })
aethis_refine_sections({ domain, feedback, sources })

阶段 2 — 字段词汇

aethis_set_field_spec({
  project_id,
  expected_fields: [{ key, sort, enum_values?, notes?: [{ note_text, source?, metadata? }] }, ...]
})
aethis_discover_fields({ project_id })           // auto-validates against the spec if set
aethis_refine_fields({ project_id, feedback })
aethis_validate_fields({ project_id, expected_fields })

阶段 3 — 生成、测试并发布

aethis_create_ruleset({
  name, section_id, domain?, source_text,
  test_cases: [{ name, field_values, expected_outcome, expectations? }, ...],
  contract_version?: 1,
  expected_review_bindings?: { field_id: { token: true | false | null } }
})
aethis_generate_and_test({ project_id })
aethis_refine({ project_id, feedback })          // iterate until tests pass
aethis_publish({ project_id })                   // refuses if tests fail; returns ruleset_id on success

当测试包含 expectations 时，请设置 contract_version: 1。可选的绑定目录是通用创作元数据：如果不需要绑定断言，请省略；如果要断言不存在审核绑定，请传入 {}。服务器必须在开始生成前确认完整的已存储契约。aethis_create_ruleset 会创建项目；它不会向现有项目追加或替换测试。之后如需替换，请使用完整的版本 1 契约调用 aethis_set_tests，然后对同一项目进行生成或优化。旧版更新无法丢弃已存储的断言。字段值映射和绑定映射中名为 __proto__ 的对象键会被拒绝，而不是静默丢弃。

如果生成轮询超时，请先调用 aethis_generation_status({ project_id }) 再重试：使用其 telemetry_availability、以服务器为准的 worker_lifecycle 和 retry_readiness，并且仅在就绪状态为 ready 时重试。仅凭旧心跳无法证明工作进程已终止。只有在显示已观察到的 job_id 并收到明确的放弃该活动运行的确认后，才调用 aethis_cancel_generation({ project_id, job_id, confirm_job_id })。此操作会释放项目的作业所有权，但工作进程可能会以协作方式关闭，而非立即关闭；请检查返回的详情。这是会造成破坏且受 API 密钥保护的变更操作。响应会区分新发生的 cancelled 转换和幂等的 already_cancelled 结果。

指南

提供定向提示而不重新生成，并提供适用于某个领域的跨章节原则：

aethis_add_guidance({ project_id, guidance_text, process_type })
aethis_list_guidance({ project_id })

aethis_add_domain_guidance({ domain, guidance_text, process_type, notes? })
aethis_list_domain_guidance({ domain })

process_type 为 rule_generation（默认值）或 field_extraction。

诊断失败的测试

aethis_explain_failure({
  ruleset_id, field_values, expected_outcome, test_name
})
// Returns criterion statuses, the failing rule, and a targeted fix hint.

重要

测试是发布门槛。 aethis_publish 拒绝发布包含失败测试的规则集。SME 编写测试；LLM 根据源文本和指导生成规则；平台拒绝发布不满足测试要求的规则。测试越好，收敛越快。

重要

编写内容需要 Anthropic 密钥。请配置 AETHIS_ANTHROPIC_KEY_ENV，或使用 anthropic_key_keychain（macOS 钥匙串引用），而不要使用原始的 anthropic_key 参数——请参阅安全传递 Anthropic 密钥。密钥按请求使用，绝不会存储在服务端；不过，原始形式会写入 MCP 主机磁盘上的会话记录。

重要

DATE 字段使用整数序数（date.toordinal()），而非 ISO 字符串。2025-04-13 = 739354。快速转换：python3 -c "from datetime import date; print(date(2025,4,13).toordinal())。

---

DSL 功能

字段类型

类型	描述
Bool	真 / 假
Int	整数（计数、便士形式的金额、整数百分比）
Enum	命名值的封闭集合
Date	整数序数 — date.toordinal()
Duration	整数天数
String	自由文本 — 对于已知集合，优先使用 Enum

运算符

类别	运算符
逻辑	AND、OR、NOT、IMPLIES
比较	=、≠、<、≤、>、≥
成员关系	IN [v1, v2, ...]
算术	+、−，用于 Int/Date；* 用于 Int
聚合	min(...)、max(...)

辅助函数

• days_between(date_a, date_b) → Int
• years_between(date_a, date_b) → Int — 两个日期之间已完整经过的整年数（正确处理闰年）。请用它根据出生日期字段计算年龄；绝不要用 days_between(...) / 365 推算年龄。
• min(a, b, ...)、max(a, b, ...) → Int
• 常量算术会在编写时折叠（5 * 365 → 1825）

不支持

• 对运行时字段值进行除法
• 加权评分或概率结果
• 将列表用作字段值（请使用预先聚合的 Int / Bool）
• 超过 3 个结果等级（eligible / not_eligible / undetermined）

---

故障排除

错误	原因	解决方法
API key is required	未设置 AETHIS_API_KEY（编写内容时）	在 MCP 客户端设置中配置，而非 shell 配置文件
X-Anthropic-Key header is required	缺少 Anthropic 密钥	在 MCP 服务配置中设置 AETHIS_ANTHROPIC_KEY_ENV（推荐），或在工具调用时传入 anthropic_key_keychain / anthropic_key。请参阅安全传递 Anthropic 密钥。
Ruleset not found (404)	ID 错误或已归档	aethis_list_projects → aethis_list_rulesets
Rate limit exceeded (429)	每日限额	客户端会自动重试。如需更高级别，请联系 [email protected]
Cannot publish: tests failing	测试未通过	使用 aethis_refine 直到所有测试通过
生成超时 (504)	服务仍在生成（通常需要 5–15 分钟）	请等待，然后运行 aethis_list_rulesets({ project_id }) 检查。不要重新触发
Expected an integer for <field>, got str	DATE 字段以 ISO 字符串形式传入	使用 date.toordinal() 整数

---

相关内容

• aethis-cli — Python 命令行工具；使用 YAML 测试用例进行基于文件的编写
• aethis-examples — 可运行的规则集（航天器、construction-CAR、消费信贷）和基准场景
• confidently-wrong-benchmark — 论文、225 个场景的基准测试、LegalBench 测试框架

开发

git clone https://github.com/Aethis-ai/aethis-mcp.git
cd aethis-mcp && npm install && npm test && npm run build

许可证

MIT