AiNecto

ainecto — AiNecto CLI 和 MCP 连接器

以 ainecto、@ainecto/mcp 和 @ainecto/cli 发布——它们使用相同的代码。命令：ainecto。

每台机器只需运行一次： npx -y ainecto@latest setup——通过浏览器登录（一次），检查连接，并将 Claude Code、Cursor 和 Codex 连接到 AiNecto 服务地址 （https://ainecto.com/mcp）。每个 Agent 在首次连接时都会自行登录 AiNecto。

每个 AI 会话都能看到相同的 AiNecto 工具。工具可以执行哪些更改，由你在其操作的工作区、项目或文档上的 AiNecto 权限决定——服务会拒绝其他操作。没有会话角色（Design / Development / Test / Validation 已在 0.8.0 中移除）。

适用于 AI Agent

运行 npx -y ainecto@latest setup（使用较长的命令超时时间——至少 6 分钟：登录会等待用户，最长 5 分钟）。然后运行 npx -y ainecto@latest doctor，并按提示操作。

• setup 会注册服务地址，因此每个 Agent 首次使用时都要自行登录：Claude Code——在会话中运行 /mcp 并登录 ainecto；Cursor——在 ainecto 的 MCP 设置中出现提示时登录；Codex——在 setup 连接 Codex 时登录（浏览器标签页会打开，登录链接会输出到 stderr；如果未完成，请运行 codex mcp login ainecto）。
• 若要将 AiNecto 的工作规则添加到仓库，请在仓库根目录运行 npx -y ainecto@latest init。它不会询问角色或项目。
• 在会话期间添加的服务在该会话中不可用。 请继续通过命令行操作：npx -y ainecto@latest tools list 和 npx -y ainecto@latest tools call <tool> '<json>'。新会话会加载 MCP 工具。
• 如果结果中提到的工具不在你的工具列表中，说明会话是在该工具添加之前启动的——请启动新会话，或像上面那样通过命令行调用该工具。
• Claude Code 的自动模式可能会阻止使用 npx 运行外部软件包。如果遇到这种情况，请让用户允许该命令。

设置此机器

npx -y ainecto@latest setup              # sign in, check, connect Claude Code · Cursor · Codex
npx -y ainecto@latest setup --dry-run    # show what it would do — no sign-in, no changes
npx -y ainecto@latest setup --local      # connect through the local relay instead (see below)
npx -y ainecto@latest setup --undo       # remove the connections setup made (sign-in stays)
npx -y ainecto@latest status             # who is signed in, your AiNecto role, what is connected
npx -y ainecto@latest doctor             # what is missing, and the one command that fixes each item

setup 会分别连接每个客户端，并报告 connected、updated、kept（其他人添加的 ainecto 条目，保持不变）、not installed 或 failed；如果任何客户端连接失败，它会报告 «partial» 并以状态码 1 退出：

• Claude Code——claude mcp add --transport http -s user ainecto https://ainecto.com/mcp（用户范围）。 在会话中使用 /mcp 登录。
• Cursor——将 "ainecto": { "url": "https://ainecto.com/mcp" } 合并到 ~/.cursor/mcp.json，保留你的其他服务。Cursor 会要求你在 MCP 设置中登录。
• Codex——codex mcp add ainecto --url https://ainecto.com/mcp。Codex 会立即开始登录（浏览器标签页会打开；setup 会将 Codex 的输出（包括登录链接）转发到 stderr）。如果 90 秒内未完成，Codex 会显示为 failed，但仍保持连接——请运行 codex mcp login ainecto（重新运行 setup 会给出相同结果）。

使用 --env dev（或 --endpoint）时，地址会指向对应环境。服务地址没有可固定的版本：服务更新会同时到达所有 Agent。重新运行 setup 时，旧版 setup 写入的条目（npx -y @ainecto/mcp@<version>，带或不带 --role）会被改写为服务地址；setup --undo 会移除这两种条目。

setup --local 会注册本地中继，而不是服务地址——npx -y @ainecto/mcp@<version>（stdio，版本固定为 CLI 版本），所有 Agent 都会使用此机器上的同一个 ainecto 登录。仅当 Agent 无法自行登录服务地址时才使用此选项；再次运行不带 --local 的 setup 会切回服务地址。

setup 和 status 会显示你的 AiNecto 角色（你在 AiNecto 账户设置中指定的工作）。AI 会根据该角色调整说明的表达方式——它不会改变权限。

设置仓库（可选）

npx -y ainecto@latest init               # .ainecto/HARNESS.md, an AGENTS.md block (and CLAUDE.md if present), .ainecto/config.json
npx -y ainecto@latest init --mcp         # also .mcp.json (Claude Code) and .cursor/mcp.json (Cursor), with the server address
npx -y ainecto@latest init --mcp --local # the same files with the local relay instead
npx -y ainecto@latest init --dry-run     # the same plan, nothing written
npx -y ainecto@latest init --undo        # remove what init wrote
npx -y ainecto@latest init --agent tester  # name the agent working in this folder (see below)

• --agent <name> 用于指定在此文件夹中工作的 Agent。它会将名称写入 .ainecto/agent.local（请勿将其提交到 git），并将其写入 .mcp.json、.cursor/mcp.json 和 .codex/config.toml——服务地址条目会添加请求头 X-AiNecto-Agent-Name，本地中继会添加 --agent <name>。重新运行 init 时会保留该名称。在此文件夹中运行 ainecto tools call … 时也会发送相同的名称。服务会检查名称；如果名称被拒绝，init 会在写入任何文件前停止。 仅当 .codex/config.toml 尚不存在（或由 init 写入）时才会写入该文件；Codex 只会在受信任的项目中读取它。

• init 会从服务获取规则——--dry-run 也会获取，因此计划与实际操作一致。如果无法获取（未登录、离线），它会说明哪些文件将改用此软件包的默认文本。

• 如果此设备尚未登录，init 会打开一次浏览器（--dry-run 不会）。首先会输出登录 URL（使用 --json 时，会在 stderr 上输出一行 JSON：{"event":"login_url","url":…}）。

• 如果从 git 仓库的子文件夹中运行，它会停止并告知你仓库根目录。

• --mcp 会写入服务地址，与 setup 一样：.mcp.json 会写入 "ainecto": { "type": "http", "url": "https://ainecto.com/mcp" }（Claude Code 需要 type），而 .cursor/mcp.json 会写入 "ainecto": { "url": "https://ainecto.com/mcp" }。每个 Agent 首次使用时都需要单独登录。--local 则会写入固定版本的本地中继（见 Connector Mode）。

• 较早设置的仓库（.mcp.json 中使用 npx -y @ainecto/mcp…，无论是否带有 --role）： 重新运行 npx -y ainecto@latest init。它会将现有的 ainecto 条目改写为服务地址 （或者使用 --local 时，改写为固定到此版本且不带 --role 的中继），并从 .ainecto/config.json 中移除旧的 project 字段（除非你修改过它）。指向其他位置的 ainecto 条目会保持不变。在此之前，旧条目仍可正常工作：--role 会被接受并忽略。旧标志（--role、--project、--project-name、--yes）会被忽略，并附带一行说明。

命令

建议使用 npx -y ainecto@latest <command>。若要一次性安装，请改用 npm install -g ainecto——但全局安装的 ainecto、@ainecto/mcp 和 @ainecto/cli 只能选一个：它们使用相同的代码，且都会提供 ainecto 命令，因此再次全局安装会产生冲突。（@ainecto/mcp 还包含桥接程序 mcp。）

ainecto auth login          # once per machine (and per --env) — `setup` does this for you
ainecto auth status
ainecto auth logout

ainecto tools list
ainecto tools call list_projects --json
ainecto tools call erd_apply_changes -f changes.json --json
cat payload.json | ainecto tools call erd_apply_changes --json

ainecto projects list
ainecto erd apply-changes -f erd-operations.json --yes

工具名称使用服务自身的名称（list_projects、erd_apply_changes 等）。你的 AI 客户端会显示带有自身前缀的名称，例如 Claude Code 中的 mcp__ainecto__list_projects；CLI 不使用此前缀。以服务旧版前缀 mcp__ainecto__ 开头的工具名称仍然可用。

每条命令都可使用 --env dev，指向 https://dev.ainecto.com/mcp。端点解析优先级：

1. --endpoint <url>
2. AINECTO_MCP_ENDPOINT
3. --env dev
4. 生产环境默认地址 https://ainecto.com/mcp

端点 URL 必须使用 https:。仅当目标是 127.0.0.1 等本地主机环回地址时，才接受普通的 http:。设置了 AINECTO_TOKEN 时，CLI 只会将其发送到默认的生产/开发端点；只有在明确受信任的自定义端点下设置 AINECTO_ALLOW_CUSTOM_ENDPOINT_TOKEN=1 时，才会发送到自定义端点。

命令为 ainecto 和 mcp（由 npx -y @ainecto/mcp 运行）。上文所列的 AINECTO_* 环境变量是这些设置唯一使用的名称——请勿猜测其他前缀。

自动生成的友好命令

每个已纳入版本控制的自动生成目录工具，都可通过其确定性命令路径访问。标量架构字段会公开为标志，同时接受 kebab-case 和 schema-case：

ainecto documents list --project-uuid <projectUuid>
ainecto documents list --projectUuid <projectUuid>

数组或对象负载使用一方提供的 CLI JSON 负载读取器：

ainecto documents create -f create-documents.json
cat erd-operations.json | ainecto erd apply-changes --json

除非指定 --yes，破坏性自动生成命令在人工模式下会提示确认。在 --json 模式下，若未指定 --yes，则会失败并返回结构化错误。

附件文件上传可通过专用命令完成，该命令会执行上传令牌、原始 PUT 和附件注册流程：

ainecto attachments upload --document-uuid <documentUuid> ./diagram.png ./notes.pdf

自动生成的 request_upload_token 和 upload_attachments 路径仍是原始 MCP 参数约定命令，不会读取本地文件。

收件箱轮询 — 供调度器（cron、launchd）使用，仅在有新内容时唤醒 Agent。退出代码：0 表示有新项目，3 表示没有新内容，1 表示错误，2 表示用法错误。notifications poll 会先将批次保存到游标文件，再打印出来；在执行 notifications ack 之前（仅在 Agent 处理完该批次后运行），会重复打印同一批次。agent-todos poll --only-new 仅当待办事项是此前未见过的（记录在已见文件中）时才以 0 退出。两者都接受 --workspace <uuid> 和 --project <uuid>，且可重复指定：匹配任意给定工作区 AND 任意给定项目。每个筛选条件都有独立的通知流，因此每个筛选条件使用一个游标文件。

ainecto notifications poll --direct-only --cursor-file ~/.ainecto/inbox.cursor --json > /tmp/inbox.json \
  && claude -p "Summarize these AiNecto notifications: $(cat /tmp/inbox.json)" \
  && ainecto notifications ack --cursor-file ~/.ainecto/inbox.cursor
ainecto agent-todos poll --only-new --seen-file ~/.ainecto/todos.seen --json > /tmp/todos.json \
  && claude -p "Review these AiNecto to-dos and only summarize them: $(cat /tmp/todos.json)"

底层服务器工具（list_notifications、list_agent_todos、update_agent_todos、list_history）也会成为自动生成的命令（ainecto notifications list、ainecto agent-todos list、ainecto agent-todos update -f …、ainecto history list），前提是服务器已公开这些工具。

连接器模式

ainecto mcp [--env dev]

该软件包也可作为面向已解析 /mcp 端点的 stdio-to-HTTP 代理。它会代理 initialize、tools/list 和 tools/call，不会改写远程架构，也不会解析本地文件引用。它使用此机器上的单次登录（通过 ainecto setup、ainecto auth login，或由 ainecto init 执行的登录），且绝不会自行打开浏览器。

这是 setup --local 和 init --mcp --local 写入的条目 — 通常无需手动添加（不带 --local 时，它们会改为写入服务器地址，如上所述）：

{
  "mcpServers": {
    "ainecto": {
      "command": "npx",
      "args": ["-y", "@ainecto/[email protected]"]
    }
  }
}

带有 --role <name>（或 AINECTO_ROLE）的旧条目仍会启动：该值会被忽略，一条单行说明会输出到 stderr，服务器只会记录仍在使用旧设置。如果会话中看不到 AiNecto 工具，可能是另一个 ainecto 条目（例如 Claude Code 的本地作用域）隐藏了它 — ainecto doctor 可以检查这一点。

MCP Registry

server.json 是 Registry 条目 com.ainecto/mcp（与 package.json#mcpName 相同）。它列出了服务器地址 https://ainecto.com/mcp（远程、可流式传输的 HTTP — 即 setup 注册的地址）和 npm 软件包 @ainecto/mcp（即 setup --local 和 init --mcp --local 写入的桥接程序）。发布到 Registry 要求其引用的 npm 版本带有该 mcpName，因此请先发布 npm。注册由人员完成：

1. 运行 npm run release -- --otp=<code>（见下文），将 @ainecto/mcp@<version> 发布到 npm。
2. 登录 ainecto.com 域名（HTTP：https://ainecto.com/.well-known/mcp-registry-auth 必须提供公钥；私钥位于 macOS 钥匙串中）： mcp-publisher login http --domain ainecto.com --private-key "$(security find-generic-password -s codelive-mcp-registry -a ainecto.com -w)"。
3. 在此文件夹中运行 mcp-publisher publish。

截至 0.8.1，条目为 io.github.codelives/ainecto（仅软件包）；首次发布 com.ainecto/mcp 后，该条目标记为已弃用。详情见 docs/mcp-registry-registration.md。

开发

npm install
npm run typecheck
npm test
npm run build
npm link            # puts `ainecto` on your PATH

目录同步

sync:tools --check 用于发布时检查实时数据是否存在偏差。缺少 AINECTO_CATALOG_SYNC_TOKEN 时会立即失败，避免自动发布悄悄回退到固定数据。 本地开发时，sync:tools 也可以使用通过 ainecto auth login --env <env> 获取的凭据。

AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env prod --check
AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env dev --check

签入的生成目录是 tools/list 的确定性输出，由 https://ainecto.com/mcp 和 https://dev.ainecto.com/mcp 实时同步而来。展示元数据单独存放在 src/core/catalog/enrichments.ts 中。ainecto tools catalog 会输出本地生成的目录。

本地 Tarball 冒烟测试

npm pack
npm exec --package ./ainecto-mcp-<version>.tgz -- ainecto --help

开发环境实时 MCP 冒烟测试

此测试需要通过 ainecto auth login --env dev 获取经过身份验证的开发环境令牌，或本地开发者 AINECTO_TOKEN。

npm run smoke:mcp -- --env dev

此冒烟测试会初始化 MCP、读取 tools/list、调用 list_projects，并且只输出工具数量、Task 工具是否暴露等汇总元数据。

本地附件上传冒烟测试

此测试会针对本地 API 开发服务器完整执行 attachments upload 流程：签发 OAuth MCP 令牌、创建 REST 测试文档、通过 CLI 上传、调用 list_attachments，并验证服务器文件系统中的字节内容。

npm run smoke:attachments -- --base-url http://localhost:8080 --endpoint http://localhost:8080/mcp --api-root <path-to-api-repo>

此冒烟测试会创建临时用户／工作区／项目／文档，除非提供 --keep，否则会删除测试账户、本地临时文件和已存储的上传文件。

发布

npm run release -- --otp=<code> 会运行一次类型检查、测试和构建，然后以三个名称发布该构建：@ainecto/mcp（主要名称）、ainecto 和 @ainecto/cli（仅提供 ainecto 命令）。--dry-run 会显示即将发布的内容。已发布的名称会被跳过，因此验证码过期后重试也是安全的。npm 账户需要拥有 @ainecto 组织的写入权限（脚本会进行检查）。请勿取消发布任何名称。

已知限制

• MCP 连接器实现了以换行符分隔的 stdio JSON-RPC 到 HTTP JSON-RPC 的转换。尚未实现 Streamable HTTP SSE 响应和 MCP-Session-Id 会话处理。