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）に接続します。各エージェントは、初回接続時にそれぞれ AiNecto にサインインします。

すべての AI セッションで、同じ AiNecto ツールを利用できます。ツールで変更できる内容は、操作対象のワークスペース、プロジェクト、ドキュメントに対して設定された AiNecto の権限によって決まり、それ以外はサーバーが拒否します。セッションロールはありません（Design / Development / Test / Validation は 0.8.0 で廃止されました）。

AI エージェント向け

npx -y ainecto@latest setup を実行してください（長めのコマンドタイムアウトを設定してください。サインインではユーザーの操作を最大 5 分待つため、少なくとも 6 分にしてください）。その後、npx -y ainecto@latest doctor を実行し、表示される指示に従ってください。

• setup はサーバーのアドレスを登録するため、各エージェントは初回にそれぞれサインインします。Claude Code — セッションで /mcp を実行し、ainecto にサインインします。Cursor — MCP 設定で ainecto から求められたらサインインします。Codex — setup による接続時にサインインします（ブラウザーのタブが開き、サインインリンクが stderr に出力されます。完了しなかった場合は codex mcp login ainecto を実行してください）。
• リポジトリに AiNecto の作業ルールを追加するには、そのルートで npx -y ainecto@latest init を実行します。ロールやプロジェクトは尋ねられません。
• セッション中に追加したサーバーは、そのセッションでは利用できません。 CLI を使って作業を続けてください：npx -y ainecto@latest tools list および npx -y ainecto@latest tools call <tool> '<json>'。新しいセッションでは MCP ツールが読み込まれます。
• 結果にツール一覧にないツールが記載されている場合、そのセッションはツールが追加される前に開始されています。新しいセッションを開始するか、上記のように CLI から呼び出してください。
• 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 — ~/.cursor/mcp.json に "ainecto": { "url": "https://ainecto.com/mcp" } を追加し、他のサーバー設定は保持します。Cursor の MCP 設定からサインインを求められます。
• Codex — codex mcp add ainecto --url https://ainecto.com/mcp。Codex はすぐにサインインを開始します（ブラウザーのタブが開き、サインインリンクを含む Codex の出力が setup によって stderr に渡されます）。90 秒以内に完了しなかった場合、Codex は failed と表示されますが、接続は維持されます。codex mcp login ainecto を実行してください（setup を再実行しても同じ表示になります）。

--env dev（または --endpoint）を指定すると、アドレスにはその環境のものが使われます。サーバーアドレスに固定するバージョンはありません。サーバーが更新されると、すべてのエージェントに同時に反映されます。以前の setup が書き込んだエントリー（--role の有無を問わず npx -y @ainecto/mcp@<version>）は、setup を再実行するとサーバーアドレスに書き換えられます。setup --undo はどちらの種類も削除します。

setup --local を指定すると、代わりにローカルリレーを登録します。つまり、CLI バージョンに固定された npx -y @ainecto/mcp@<version>（stdio）を使い、このマシンの ainecto サインインをすべてのエージェントで共有します。エージェントがサーバーアドレスに自力でサインインできない場合にのみ使用してください。--local を指定せずに setup を再実行すると、サーバーアドレスに戻ります。

AiNecto のロール（AiNecto のアカウント設定で設定する職務）は、setup と status に表示されます。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> は、このフォルダーで作業するエージェントの名前を指定します。名前は .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 の場合、標準エラー出力に 1 行の 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" } が設定されます。各エージェントは初回にそれぞれサインインします。--local は、代わりにバージョンが固定されたローカルリレーを書き込みます（「コネクターモード」を参照）。

• 以前に設定したリポジトリ（--role の有無を問わず、.mcp.json に npx -y @ainecto/mcp… がある場合）：npx -y ainecto@latest init を再実行してください。既存の ainecto エントリはサーバーアドレスに書き換えられます（または、--local の場合は、--role なしでこのバージョンに固定されたリレーに書き換えられます）。また、変更していない限り、.ainecto/config.json から古い project フィールドが削除されます。別の場所を指す ainecto エントリはそのまま残ります。それまでは、古いエントリも引き続き動作します。--role は受け付けられますが、無視されます。古いフラグ（--role、--project、--project-name、--yes）は、1 行のメッセージを表示して無視されます。

コマンド

npx -y ainecto@latest <command> の使用を推奨します。一度だけインストールする場合は、npm install -g ainecto を使用してください。ただし、ainecto、@ainecto/mcp、@ainecto/cli のうちグローバルにインストールするのは1 つだけにしてください。これらは同じコードで、いずれも ainecto コマンドを提供するため、2 つ目をグローバルにインストールすると競合します（@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__ プレフィックスで始まるツール名も引き続き受け付けられます。

すべてのコマンドで、https://dev.ainecto.com/mcp を指定するには --env dev を使用できます。エンドポイントの解決順は次のとおりです。

1. --endpoint <url>
2. AINECTO_MCP_ENDPOINT
3. --env dev
4. 本番環境のデフォルトである https://ainecto.com/mcp

エンドポイント URL には https: を使用する必要があります。http: が認められるのは、127.0.0.1 などの localhost ループバック先に限られます。AINECTO_TOKEN が設定されている場合、明示的に信頼したカスタムエンドポイントに対して AINECTO_ALLOW_CUSTOM_ENDPOINT_TOKEN=1 が設定されていない限り、CLI はデフォルトの本番／開発エンドポイントにのみトークンを送信します。

コマンドは ainecto と mcp です（npx -y @ainecto/mcp を実行すると mcp が起動します）。上記の設定に使う環境変数名は AINECTO_* だけです。別のプレフィックスを推測して使わないでください。

自動生成されたフレンドリーなコマンド

チェックイン済みの自動生成カタログツールには、それぞれ決定的なコマンドパスからアクセスできます。スカラー型のスキーマフィールドはフラグとして公開され、ケバブケースとスキーマの大文字・小文字のどちらでも指定できます。

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 が指定されていないと構造化エラーで失敗します。

添付ファイルのアップロードには、アップロードトークンの取得、raw PUT、添付ファイルの登録のフローを実行する専用コマンドを使用できます。

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

自動生成された request_upload_token と upload_attachments のパスは、引き続き MCP 引数コントラクトをそのまま扱うコマンドであり、ローカルファイルを読み込みません。

受信トレイのポーリング — 新着があった場合にのみエージェントを起動するスケジューラー（cron、launchd）向けです。終了コード：0 は新着あり、3 は新着なし、1 はエラー、2 は使用方法のエラーです。notifications poll はバッチをカーソルファイルに保存してから出力し、notifications ack を実行するまで同じバッチを繰り返し出力します（エージェントがバッチを処理した後にのみ実行してください）。agent-todos poll --only-new は、未確認の ToDo（確認済みの項目は確認済みファイルに記録されます）がある場合にのみ終了コード 0 を返します。どちらも --workspace <uuid> と --project <uuid> を受け付け、各オプションは繰り返し指定できます。指定したワークスペースのいずれか、かつ指定したプロジェクトのいずれかが対象になります。各フィルターは独立した通知ストリームなので、フィルターごとにカーソルファイルを使用してください。

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）を含む古いエントリでも引き続き起動します。その値は無視され、1 行のメッセージが stderr に出力され、サーバーには古い設定がまだ使われていることだけが記録されます。セッションで AiNecto ツールが見つからない場合は、別の ainecto エントリ（たとえば Claude Code のローカルスコープ）が隠している可能性があります。ainecto doctor で確認できます。

MCP レジストリ

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. @ainecto/mcp@<version> が npm に公開されるよう、npm run release -- --otp=<code>（下記）を実行します。
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

Dev MCP のライブスモークテスト

ainecto auth login --env dev で取得した認証済みの 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> は、型チェック、テスト、ビルドをそれぞれ一度実行した後、そのビルドを次の3つの名前で公開します。@ainecto/mcp（メイン）、ainecto、@ainecto/cli（ainecto コマンドのみ）。 --dry-run を指定すると、公開される内容を確認できます。すでに公開済みの名前はスキップされるため、コードの有効期限が切れた後に再試行しても安全です。npm アカウントには @ainecto 組織への書き込みアクセス権が必要です（スクリプトで確認します）。いずれの名前も公開取り消しをしないでください。

既知の制限事項

• MCP コネクターは、改行区切りの stdio JSON-RPC を HTTP JSON-RPC に変換します。ストリーミング可能な HTTP SSE レスポンスと MCP-Session-Id によるセッション処理は実装されていません。