AiNecto

ainecto — AiNecto CLI and MCP connector

Published as ainecto, @ainecto/mcp and @ainecto/cli — the same code. Command: ainecto.

Once per machine: npx -y ainecto@latest setup — signs you in through the browser (once), checks the connection, and connects Claude Code, Cursor, and Codex to the AiNecto server address (https://ainecto.com/mcp). Each agent then signs in to AiNecto by itself the first time it connects.

Every AI session sees the same AiNecto tools. What a tool may change is decided by your AiNecto permissions on the workspace, project, or document it touches — the server refuses the rest. There are no session roles (Design / Development / Test / Validation were removed in 0.8.0).

For AI agents

Run npx -y ainecto@latest setup (use a long command timeout — at least 6 minutes: sign-in waits up to 5 minutes for the user). Then run npx -y ainecto@latest doctor and do what it says.

• setup registers the server address, so each agent signs in on its own the first time: Claude Code — run /mcp in a session and sign in to ainecto; Cursor — sign in when ainecto asks in its MCP settings; Codex — signs in while setup connects it (a browser tab opens and the sign-in link is printed to stderr; if it did not finish, run codex mcp login ainecto).
• To add AiNecto's working rules to a repository, run npx -y ainecto@latest init from its root. It does not ask for a role or a project.
• A server added during a session is not available in that session. Keep working through the CLI: npx -y ainecto@latest tools list and npx -y ainecto@latest tools call <tool> '<json>'. A new session loads the MCP tools.
• If a result names a tool that is not in your tool list, the session started before that tool was added — start a new session or call it through the CLI as above.
• Claude Code's auto mode may block running an external package with npx. If it does, ask the user to allow the command.
• ChatGPT, Claude and other apps: see https://ainecto.com/docs/get-started/connect-your-agent/

Set up this machine

npx -y ainecto@latest setup              # sign in, check, connect Claude Code · Cursor · Codexnpx -y ainecto@latest setup --dry-run    # show what it would do — no sign-in, no changesnpx -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 connectednpx -y ainecto@latest doctor             # what is missing, and the one command that fixes each item

setup connects each client separately and reports connected, updated, kept (someone else's ainecto entry, left untouched), not installed, or failed; if any client fails it says «partial» and exits 1:

• Claude Code — claude mcp add --transport http -s user ainecto https://ainecto.com/mcp (user scope). Sign in with /mcp in a session.
• Cursor — merges "ainecto": { "url": "https://ainecto.com/mcp" } into ~/.cursor/mcp.json, keeping your other servers. Cursor asks you to sign in from its MCP settings.
• Codex — codex mcp add ainecto --url https://ainecto.com/mcp. Codex starts its sign-in right away (a browser tab opens; setup passes Codex's output, with the sign-in link, through to stderr). If that did not finish within 90 seconds, Codex shows as failed but stays connected — run codex mcp login ainecto (re-running setup says the same).

With --env dev (or --endpoint) the address is that environment's. The server address has no version to pin: a server update reaches every agent at once. Entries an older setup wrote (npx -y @ainecto/mcp@<version>, with or without --role) are rewritten to the server address when you re-run setup; setup --undo removes either kind.

setup --local registers the local relay instead — npx -y @ainecto/mcp@<version> (stdio, pinned to the CLI version), which uses this machine's one ainecto sign-in for every agent. Use it only when an agent cannot sign in to the server address by itself; running setup again without --local moves back to the server address.

Your AiNecto role (your job, set in AiNecto's account settings) is shown by setup and status; AI uses it to pitch explanations — it does not change permissions.

Set up a repository (optional)

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

• --agent <name> names the agent that works in this folder. It writes the name to .ainecto/agent.local (keep it out of git) and puts it in .mcp.json, .cursor/mcp.json and .codex/config.toml — the server address entries get the header X-AiNecto-Agent-Name, the local relay gets --agent <name>. Re-running init keeps the name. ainecto tools call … run in this folder sends the same name. The server checks the name; a name it refuses stops init before any file is written. .codex/config.toml is written only when it does not exist yet (or init wrote it); Codex reads it only in a trusted project.

• init fetches the rules from the server — --dry-run too, so the plan is the real one. If it cannot (not signed in, offline), it says which files would get this package's default text instead.

• If this machine is not signed in yet, init opens the browser once (--dry-run never does). The sign-in URL is printed first (with --json, as one JSON line on stderr: {"event":"login_url","url":…}).

• It stops when run from a sub-folder of a git repository, and tells you the root.

• --mcp writes the server address, like setup: .mcp.json gets "ainecto": { "type": "http", "url": "https://ainecto.com/mcp" } (Claude Code needs the type) and .cursor/mcp.json gets "ainecto": { "url": "https://ainecto.com/mcp" }. Each agent signs in by itself the first time. --local writes the pinned local relay instead (see Connector Mode).

• Repositories set up earlier (.mcp.json with npx -y @ainecto/mcp…, with or without --role): re-run npx -y ainecto@latest init. It rewrites the existing ainecto entry to the server address (or, with --local, to the relay pinned to this version without --role), and drops the old project field from .ainecto/config.json (unless you changed it). An ainecto entry pointing somewhere else is left alone. Until then the old entry keeps working: --role is accepted and ignored. Old flags (--role, --project, --project-name, --yes) are ignored with a one-line note.

Commands

Prefer npx -y ainecto@latest <command>. To install once instead, use npm install -g ainecto — but install only one of ainecto, @ainecto/mcp and @ainecto/cli globally: they are the same code and all ship the ainecto command, so a second global install conflicts. (@ainecto/mcp also carries mcp, the bridge.)

ainecto auth login          # once per machine (and per --env) — `setup` does this for youainecto auth statusainecto auth logout
ainecto tools listainecto tools call list_projects --jsonainecto tools call erd_apply_changes -f changes.json --jsoncat payload.json | ainecto tools call erd_apply_changes --json
ainecto projects listainecto erd apply-changes -f erd-operations.json --yes

Tool names are the server's own names (list_projects, erd_apply_changes, …). Your AI client shows them with its own prefix, for example mcp__ainecto__list_projects in Claude Code; the CLI does not use that prefix. A tool name that starts with the server's older mcp__ainecto__ prefix is still accepted.

Every command takes --env dev for https://dev.ainecto.com/mcp. Endpoint resolution priority:

1. --endpoint <url>
2. AINECTO_MCP_ENDPOINT
3. --env dev
4. production default, https://ainecto.com/mcp

Endpoint URLs must use https:. Plain http: is accepted only for localhost loopback targets such as 127.0.0.1. When AINECTO_TOKEN is set, the CLI only sends it to the default prod/dev endpoints unless AINECTO_ALLOW_CUSTOM_ENDPOINT_TOKEN=1 is set for an explicitly trusted custom endpoint.

The commands are ainecto and mcp (which npx -y @ainecto/mcp runs). The AINECTO_* environment variables above are the only names for those settings — do not guess another prefix.

Generated Friendly Commands

Every checked-in generated catalog tool is reachable through its deterministic command path. Scalar schema fields are exposed as flags, with both kebab-case and schema-case accepted:

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

Array or object payloads use the first-party CLI JSON payload reader:

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

Destructive generated commands prompt in human mode unless --yes is supplied. In --json mode they fail with a structured error unless --yes is present.

Attachment file upload is available through a bespoke command that performs the upload-token, raw PUT, and attachment registration flow:

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

The generated request_upload_token and upload_attachments paths remain raw MCP argument-contract commands and do not read local files.

Inbox polling — for a scheduler (cron, launchd) that wakes an agent only when something is new. Exit codes: 0 new items, 3 nothing new, 1 error, 2 usage error. notifications poll saves the batch to the cursor file before printing it and prints the same batch again until notifications ack (run it only after the agent handled the batch). agent-todos poll --only-new exits 0 only for to-dos it has not seen before (kept in the seen file). Both take --workspace <uuid> and --project <uuid>, each repeatable: any of the given workspaces AND any of the given projects. Each filter is its own notification stream, so use one cursor file per filter.

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.cursorainecto 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)"

The server tools behind them (list_notifications, list_agent_todos, update_agent_todos, list_history) are generated commands too (ainecto notifications list, ainecto agent-todos list, ainecto agent-todos update -f …, ainecto history list) once the server exposes them.

Terminal Sessions

ainecto term keeps terminal sessions running after you close the terminal window — no tmux or cmux needed. A background process, started on demand, owns each session and keeps its screen, so agents and scripts can type into a session and read its screen, and you can attach from any terminal app. It runs on this machine only; it does not use your AiNecto sign-in.

ainecto term new api --cwd ~/code/api -- claude   # start a session (without a command: your login shell)ainecto term ls [--json]ainecto term send api "run the tests"             # types the text, without Enterainecto term key api enter                        # one key — see belowainecto term read api [--lines N] [--scrollback] [--json]ainecto term wait api --match 'passed' [--timeout 600]   # until a screen line matches (seconds)ainecto term attach api                           # detach with Ctrl-\ then dainecto term kill apiainecto term kill-server                          # every session and the background processainecto term restore                              # after a reboot: start again what was running

• Keys for key: enter, tab, shift-tab, escape, backspace, delete, space, up, down, left, right, home, end, pageup, pagedown, ctrl-a … ctrl-z (ctrl+c, esc and return are accepted too).
• send --paste sends the text as a bracketed paste when the app asked for one. To send text that starts with -, put it after --.
• In attach, press Ctrl-\ twice to send one Ctrl-\ to the app.
• Inside a session, AINECTO_TERM_SESSION holds its name. A name does not change; to rename, kill the session and start it again.
• restore starts again each session that was running (name, folder, command) with the environment of the shell you run it from. It does not bring back what the programs had in memory, and nothing restarts on its own after a reboot. A session that exits by itself is forgotten; kill and kill-server forget theirs.
• Files are in ~/.ainecto/term/ (folder only you can read): the control socket, sessions.json (what restore starts) and daemon.log (one line per request and one per answer; kept to 10 MB plus one older file, daemon.log.1). Typed text, screens and environment values are not logged.
• How long a command waits, three separate limits:
  • Each request to the running background process waits up to 10 seconds for its answer; then the command stops with an error and removes nothing.
  • Starting the background process waits up to 10 seconds per try for it to report ready, at most 3 tries.
  • wait itself waits until --timeout (without it, until the pattern appears or the session ends).
• Platforms: macOS, and Linux with glibc on Node.js 20.8.0 or newer (the rest of the CLI runs on Node 18). Not Windows yet. It uses the optional dependency node-pty, which ships prebuilt binaries — no compiler needed. If it could not be installed, ainecto term says so and the other commands keep working.

Connector Mode

ainecto mcp [--env dev]

The package doubles as a stdio-to-HTTP proxy for the resolved /mcp endpoint. It proxies initialize, tools/list, and tools/call, does not rewrite remote schemas, and does not interpret local file references. It uses this machine's one sign-in (ainecto setup, ainecto auth login, or the sign-in ainecto init performs) and never opens a browser on its own.

This is the entry setup --local and init --mcp --local write — you normally do not add it by hand (without --local they write the server address instead, as above):

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

An older entry with --role <name> (or AINECTO_ROLE) still starts: the value is ignored, a one-line note goes to stderr, and the server only records that an old setting is still in use. If a session does not see the AiNecto tools, another ainecto entry (for example Claude Code's local scope) may be hiding it — ainecto doctor checks this.

MCP Registry

server.json is the Registry entry com.ainecto/mcp (same as package.json#mcpName). It lists the server address https://ainecto.com/mcp (remote, streamable HTTP — what setup registers) and the npm package @ainecto/mcp (the bridge setup --local and init --mcp --local write). Registry publication requires the npm version it references to carry that mcpName, so publish npm first. Registration is done by a person:

1. npm run release -- --otp=<code> (below) so that @ainecto/mcp@<version> is on npm.
2. Domain login for ainecto.com (HTTP: https://ainecto.com/.well-known/mcp-registry-auth must serve the public key; the private key is in the macOS keychain): 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 from this folder.

Up to 0.8.1 the entry was io.github.codelives/ainecto (package only); it is marked deprecated after the first com.ainecto/mcp publish. Details in docs/mcp-registry-registration.md.

Development

npm installnpm run typechecknpm testnpm run buildnpm link            # puts `ainecto` on your PATH

Catalog Sync

sync:tools --check is intended for publish-time live drift checks. It fails fast when AINECTO_CATALOG_SYNC_TOKEN is missing, so automatic publish cannot silently fall back to fixtures. For local development, sync:tools can also use credentials from ainecto auth login --env <env>.

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

The checked-in generated catalogs are deterministic output from tools/list, live-synced from https://ainecto.com/mcp and https://dev.ainecto.com/mcp. Presentation metadata lives separately in src/core/catalog/enrichments.ts. ainecto tools catalog prints the local generated catalog.

Local Tarball Smoke

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

Live Dev MCP Smoke

This requires an authenticated dev token from ainecto auth login --env dev or a local developer AINECTO_TOKEN.

npm run smoke:mcp -- --env dev

The smoke initializes MCP, reads tools/list, calls list_projects, and prints only aggregate metadata such as tool count and Task tool exposure.

Local Attachment Upload Smoke

This exercises the full attachments upload flow against a local API dev server: OAuth MCP token issue, REST fixture document creation, CLI upload, list_attachments, and server filesystem byte verification.

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

The smoke creates a temporary user/workspace/project/document and removes the fixture account, local temp file, and stored upload file unless --keep is supplied.

Releasing

npm run release -- --otp=<code> runs typecheck, test and build once, then publishes that build under three names: @ainecto/mcp (primary), ainecto, and @ainecto/cli (only the ainecto command). --dry-run shows what would go out. An already-published name is skipped, so a retry after an expired code is safe. The npm account needs write access to the @ainecto org (the script checks). Do not unpublish any name.

Known Limitations

• The MCP connector implements newline-delimited stdio JSON-RPC to HTTP JSON-RPC. Streamable HTTP SSE responses and MCP-Session-Id session handling are not implemented.