@ainecto/mcp 0.3.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +204 -88
- package/dist/bin/ainecto.js +1074 -445
- package/dist/bin/ainecto.js.map +1 -1
- package/dist/bin/mcp.js +156 -72
- package/dist/bin/mcp.js.map +1 -1
- package/package.json +4 -7
package/README.md
CHANGED
|
@@ -1,160 +1,276 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ainecto — AiNecto CLI and MCP connector
|
|
2
|
+
|
|
3
|
+
Published as `ainecto`, `@ainecto/mcp` and `@ainecto/cli` — the same code. Command: `ainecto`.
|
|
4
|
+
|
|
5
|
+
**In a terminal, from your repository root:** `npx -y ainecto@latest init` — it asks which role this
|
|
6
|
+
repository's AI sessions should have and which AiNecto project to use, and signs you in through the
|
|
7
|
+
browser if needed.
|
|
8
|
+
|
|
9
|
+
## For AI agents
|
|
10
|
+
|
|
11
|
+
**Ask the user which role this repository's AI sessions should have — Design, Development, Test, or Validation. Never pick one yourself. Then, from the repository root: `npx -y ainecto@latest init --role <role>` (it signs the user in through the browser if needed).**
|
|
12
|
+
|
|
13
|
+
- Use a long command timeout (at least 6 minutes): sign-in waits up to 5 minutes for the user.
|
|
14
|
+
- If `init` lists projects, ask the user which one and re-run with `--project <uuid>`. If it says
|
|
15
|
+
this is not the repository root, re-run from the folder it names.
|
|
16
|
+
- **No restart is needed.** Right after `init`, keep working in the same session through the CLI:
|
|
17
|
+
`ainecto` commands run from the repository read its role on every call (read `.ainecto/HARNESS.md`,
|
|
18
|
+
then `ainecto tools list` and `ainecto tools call <tool> '<json>'`). Do not use MCP tools the session
|
|
19
|
+
started with for that work — they keep the role (or no role) the session started with.
|
|
20
|
+
- A new session is optional and only adds the role's MCP tools (Claude Code: exit, then `claude -c`
|
|
21
|
+
in this folder to keep the conversation; approve the `ainecto` server from `.mcp.json` when asked).
|
|
22
|
+
Codex: save the profile `init` prints and start with `codex -p <role>`.
|
|
23
|
+
- **A server added during a session is not available in that session.** In our test, a server added
|
|
24
|
+
with `claude mcp add` while Claude Code was running did not attach to the running session — that is
|
|
25
|
+
why the CLI is the way to keep going. `/mcp` shows what the current session actually loaded.
|
|
26
|
+
- Inside the repository, `ainecto` commands (`ainecto tools call …`) use the repository's role
|
|
27
|
+
automatically — do not pass `--role`; a different `--role` is refused.
|
|
28
|
+
- Claude Code's auto mode may block running an external package with `npx`. If it does, ask the user
|
|
29
|
+
to allow the command.
|
|
30
|
+
|
|
31
|
+
To connect AiNecto without a repository role (for example before `init`), add the remote server at
|
|
32
|
+
**user scope** under the name `ainecto` — a local-scope entry would hide the `.mcp.json` that `init`
|
|
33
|
+
writes, and a different name would sit next to it as a second server with no role:
|
|
2
34
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- `npx -y @ai-erd/mcp` or `ainecto mcp`: raw stdio-to-HTTP JSON-RPC proxy for AI-ERD MCP.
|
|
8
|
-
- `ainecto <command>`: human CLI for auth and low-level tool calls.
|
|
35
|
+
```bash
|
|
36
|
+
claude mcp add --scope user --transport http ainecto https://ainecto.com/mcp # Claude Code
|
|
37
|
+
codex mcp add ainecto --url https://ainecto.com/mcp # Codex
|
|
38
|
+
```
|
|
9
39
|
|
|
10
|
-
|
|
40
|
+
The client signs the user in on first use. That session has no role until `init` runs and a new
|
|
41
|
+
session starts.
|
|
11
42
|
|
|
12
|
-
##
|
|
43
|
+
## Set up a repository (roles)
|
|
13
44
|
|
|
14
45
|
```bash
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
npm test
|
|
18
|
-
npm run build
|
|
19
|
-
npm link
|
|
46
|
+
npx -y ainecto@latest init # in a terminal: asks for the role and the project
|
|
47
|
+
npx -y ainecto@latest init --role development # agents, scripts, CI: nothing is asked
|
|
20
48
|
```
|
|
21
49
|
|
|
50
|
+
In a terminal (stdin and stdout both a TTY, no `--json`, and not under an agent or CI — `CLAUDECODE`,
|
|
51
|
+
`CI`, `GEMINI_CLI`, `CODEX_SANDBOX`, `CURSOR_AGENT`) `init` asks for what was not given:
|
|
52
|
+
- the role, unless `--role` or `AINECTO_ROLE` is set — by number, with no default. The role already
|
|
53
|
+
set on the repository is the default only when there is one (if its agent configs disagree, there
|
|
54
|
+
is no default);
|
|
55
|
+
- the project, unless `--project` is set — by number; «Create a new project» is offered to Design only.
|
|
56
|
+
|
|
57
|
+
Ctrl+C or Ctrl+D at a question cancels without writing repository files (Ctrl+D exits with 130). A
|
|
58
|
+
sign-in you already completed stays saved, and choosing «Create a new project» creates it right away.
|
|
59
|
+
Anywhere else (an agent's shell, CI) it asks nothing. In both cases:
|
|
60
|
+
|
|
61
|
+
- If this machine is not signed in to AiNecto yet, `init` opens a browser and continues once the user
|
|
62
|
+
approves — **once per machine** (per server), not per role. The sign-in URL is printed first (with
|
|
63
|
+
`--json`, as one JSON line on stderr: `{"event":"login_url","url":…}`), and sign-in gives up after
|
|
64
|
+
5 minutes. It fails at once
|
|
65
|
+
when the command that opens the browser is missing, or (except on Windows, where the exit code is
|
|
66
|
+
not reliable) exits with an error.
|
|
67
|
+
- Outside a terminal, with no `--role`/`AINECTO_ROLE` it uses the role already set on the repository.
|
|
68
|
+
If there is none (or the repository's agent configs disagree) it stops and says to ask the user —
|
|
69
|
+
it never picks a role for you. If the account has more than one project it lists them and stops;
|
|
70
|
+
re-run with `--project <uuid>`. With no project yet,
|
|
71
|
+
only a Design session can create one (`--yes`, optionally `--project-name <name>`); in any other
|
|
72
|
+
role it asks you to have the user create the project, then re-run with the same role.
|
|
73
|
+
- It stops when run from a sub-folder of a git repository, and tells you the root.
|
|
74
|
+
- It writes one `ainecto` server entry carrying `--role` into `.mcp.json` (Claude Code) and
|
|
75
|
+
`.cursor/mcp.json` (Cursor), and prints the Codex profile to use (`codex -p <role>`).
|
|
76
|
+
- `ainecto` commands in the repository use the new role **at once**; MCP tools pick it up in a **new
|
|
77
|
+
session** (a running session's MCP tools keep the role they started with). Roles are a working
|
|
78
|
+
guardrail, not a security boundary.
|
|
79
|
+
- `ainecto init --dry-run` shows what would change (it does not sign in or refresh a sign-in);
|
|
80
|
+
`ainecto init --undo` removes what it wrote.
|
|
81
|
+
|
|
22
82
|
## Commands
|
|
23
83
|
|
|
84
|
+
Prefer `npx -y ainecto@latest <command>`. To install once instead, use `npm install -g ainecto` — but
|
|
85
|
+
install only **one** of `ainecto`, `@ainecto/mcp` and `@ainecto/cli` globally: they are the same code
|
|
86
|
+
and all ship the `ainecto` command, so a second global install conflicts. (`@ainecto/mcp` also carries
|
|
87
|
+
`mcp`, the bridge.)
|
|
88
|
+
|
|
24
89
|
```bash
|
|
25
|
-
ainecto auth login --env
|
|
26
|
-
ainecto auth status
|
|
27
|
-
ainecto auth logout
|
|
28
|
-
|
|
29
|
-
ainecto tools list
|
|
30
|
-
ainecto tools call
|
|
31
|
-
ainecto tools call
|
|
32
|
-
cat payload.json | ainecto tools call
|
|
33
|
-
|
|
34
|
-
ainecto projects list
|
|
35
|
-
ainecto
|
|
36
|
-
ainecto erd apply-changes --env dev -f erd-operations.json --yes
|
|
90
|
+
ainecto auth login # once per machine (and per --env); not per role
|
|
91
|
+
ainecto auth status
|
|
92
|
+
ainecto auth logout
|
|
93
|
+
|
|
94
|
+
ainecto tools list
|
|
95
|
+
ainecto tools call list_projects --json
|
|
96
|
+
ainecto tools call erd_apply_changes -f changes.json --json
|
|
97
|
+
cat payload.json | ainecto tools call erd_apply_changes --json
|
|
98
|
+
|
|
99
|
+
ainecto projects list
|
|
100
|
+
ainecto erd apply-changes -f erd-operations.json --yes
|
|
37
101
|
```
|
|
38
102
|
|
|
39
|
-
|
|
103
|
+
**The role comes from the repository.** Inside a folder set up with `ainecto init` (the command looks
|
|
104
|
+
from the current folder upward for the first `.mcp.json`/`.cursor/mcp.json` with an `ainecto` entry),
|
|
105
|
+
every command uses that folder's role without `--role`. A `--role` or `AINECTO_ROLE` that differs from
|
|
106
|
+
it is refused — the role changes only with `ainecto init --role <role>`, after asking the user. If the
|
|
107
|
+
role there cannot be read (the `@ainecto/mcp` bridge entry without a valid `--role`, configs that
|
|
108
|
+
disagree, broken JSON that mentions `ainecto`, a link that points outside the folder), the command
|
|
109
|
+
stops. An entry that is not this bridge (for example an HTTP
|
|
110
|
+
`url` or `mcp-remote` entry) means no role there. Your home folder itself is never read as a
|
|
111
|
+
repository (`~/.cursor/mcp.json` is Cursor's global config). Outside such a folder there is no role
|
|
112
|
+
(no restriction), and `--role` narrows it.
|
|
113
|
+
Tool names are the server's own names (`list_projects`, `erd_apply_changes`, …). Your AI client
|
|
114
|
+
shows them with its own prefix, for example `mcp__ainecto__list_projects` in Claude Code; the CLI
|
|
115
|
+
does not use that prefix. A tool name that starts with
|
|
116
|
+
the server's older `mcp__ainecto__` prefix is still accepted.
|
|
117
|
+
|
|
118
|
+
Every command takes `--env dev` for `https://dev.ainecto.com/mcp`. Endpoint resolution priority:
|
|
40
119
|
|
|
41
120
|
1. `--endpoint <url>`
|
|
42
121
|
2. `AINECTO_MCP_ENDPOINT`
|
|
43
122
|
3. `--env dev`
|
|
44
|
-
4. production default, `https://
|
|
123
|
+
4. production default, `https://ainecto.com/mcp`
|
|
45
124
|
|
|
46
|
-
Endpoint URLs must use `https:`. Plain `http:` is accepted only for localhost loopback targets such
|
|
125
|
+
Endpoint URLs must use `https:`. Plain `http:` is accepted only for localhost loopback targets such
|
|
126
|
+
as `127.0.0.1`. When `AINECTO_TOKEN` is set, the CLI only sends it to the default prod/dev endpoints
|
|
127
|
+
unless `AINECTO_ALLOW_CUSTOM_ENDPOINT_TOKEN=1` is set for an explicitly trusted custom endpoint.
|
|
47
128
|
|
|
48
|
-
|
|
129
|
+
The commands are `ainecto` and `mcp` (which `npx -y @ainecto/mcp` runs). The `AINECTO_*` environment
|
|
130
|
+
variables above are the **only** names for those settings — do not guess another prefix.
|
|
131
|
+
|
|
132
|
+
## Generated Friendly Commands
|
|
133
|
+
|
|
134
|
+
Every checked-in generated catalog tool is reachable through its deterministic command path. Scalar
|
|
135
|
+
schema fields are exposed as flags, with both kebab-case and schema-case accepted:
|
|
49
136
|
|
|
50
137
|
```bash
|
|
51
|
-
|
|
52
|
-
ainecto
|
|
138
|
+
ainecto documents list --project-uuid <projectUuid>
|
|
139
|
+
ainecto documents list --projectUuid <projectUuid>
|
|
53
140
|
```
|
|
54
141
|
|
|
55
|
-
|
|
142
|
+
Array or object payloads use the first-party CLI JSON payload reader:
|
|
56
143
|
|
|
57
|
-
|
|
144
|
+
```bash
|
|
145
|
+
ainecto documents create -f create-documents.json
|
|
146
|
+
cat erd-operations.json | ainecto erd apply-changes --json
|
|
147
|
+
```
|
|
58
148
|
|
|
59
|
-
|
|
149
|
+
Destructive generated commands prompt in human mode unless `--yes` is supplied. In `--json` mode
|
|
150
|
+
they fail with a structured error unless `--yes` is present.
|
|
60
151
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
152
|
+
Attachment file upload is available through a bespoke command that performs the upload-token, raw
|
|
153
|
+
PUT, and attachment registration flow:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
ainecto attachments upload --document-uuid <documentUuid> ./diagram.png ./notes.pdf
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The generated `request_upload_token` and `upload_attachments` paths remain raw MCP argument-contract
|
|
160
|
+
commands and do not read local files.
|
|
161
|
+
|
|
162
|
+
## Connector Mode
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
ainecto mcp --role <design|development|test|validation> [--env dev]
|
|
70
166
|
```
|
|
71
167
|
|
|
72
|
-
|
|
168
|
+
The package doubles as a stdio-to-HTTP proxy for the resolved `/mcp` endpoint. It proxies
|
|
169
|
+
`initialize`, `tools/list`, and `tools/call`, does not rewrite remote schemas, and does not interpret
|
|
170
|
+
local file references. It uses this machine's one sign-in (`ainecto auth login`, or the sign-in
|
|
171
|
+
`ainecto init` performs) and never opens a browser on its own. Its role comes only from `--role` (or
|
|
172
|
+
`AINECTO_ROLE`) and is sent with every request; the server applies it.
|
|
173
|
+
|
|
174
|
+
This is the entry `ainecto init` writes into a repository's MCP config — you normally do not add it
|
|
175
|
+
by hand:
|
|
73
176
|
|
|
74
177
|
```json
|
|
75
178
|
{
|
|
76
179
|
"mcpServers": {
|
|
77
|
-
"ainecto
|
|
180
|
+
"ainecto": {
|
|
78
181
|
"command": "npx",
|
|
79
|
-
"args": ["-y", "@
|
|
182
|
+
"args": ["-y", "@ainecto/mcp", "--role", "development"]
|
|
80
183
|
}
|
|
81
184
|
}
|
|
82
185
|
}
|
|
83
186
|
```
|
|
84
187
|
|
|
85
|
-
|
|
188
|
+
A bridge without a role has no restriction. If a session inside a set-up repository still has no role,
|
|
189
|
+
another `ainecto` entry (for example Claude Code's local scope) is usually hiding the one `init` wrote —
|
|
190
|
+
check with `claude mcp get ainecto`. An entry under another name does not hide it but adds a second
|
|
191
|
+
server with no role — remove it.
|
|
86
192
|
|
|
87
|
-
|
|
193
|
+
### MCP Registry
|
|
88
194
|
|
|
89
|
-
`
|
|
90
|
-
|
|
195
|
+
`server.json` is the Registry entry `io.github.codelives/ainecto` (same as `package.json#mcpName`). It
|
|
196
|
+
lists only the npm package `@ainecto/mcp` — the per-repository role bridge `init` writes. Registry
|
|
197
|
+
publication requires the npm version it references to carry that `mcpName`, so publish npm first.
|
|
198
|
+
Registration is done by a person:
|
|
91
199
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
200
|
+
1. `npm run release -- --otp=<code>` (below) so that `@ainecto/mcp@<version>` is on npm.
|
|
201
|
+
2. GitHub org namespace login as a `codelives` org **Owner** — a classic PAT with only `read:org`
|
|
202
|
+
works where the browser login did not: `MCP_GITHUB_TOKEN=<pat> mcp-publisher login github`.
|
|
203
|
+
3. `mcp-publisher publish` from this folder.
|
|
96
204
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
`ainecto tools catalog` prints the local generated catalog. Rerun authenticated `sync:tools` when prod or dev `tools/list` changes.
|
|
100
|
-
|
|
101
|
-
## Generated Friendly Commands
|
|
205
|
+
Listing `https://ainecto.com/mcp` as a remote here, or a `com.ainecto/*` name, would need ainecto.com
|
|
206
|
+
domain auth (`mcp-publisher login dns|http --domain ainecto.com`) and is not part of this release.
|
|
102
207
|
|
|
103
|
-
|
|
208
|
+
## Development
|
|
104
209
|
|
|
105
210
|
```bash
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
```bash
|
|
113
|
-
ainecto documents create --env dev -f create-documents.json
|
|
114
|
-
cat task-ops.json | ainecto task apply-changes --env dev --json
|
|
211
|
+
npm install
|
|
212
|
+
npm run typecheck
|
|
213
|
+
npm test
|
|
214
|
+
npm run build
|
|
215
|
+
npm link # puts `ainecto` on your PATH
|
|
115
216
|
```
|
|
116
217
|
|
|
117
|
-
|
|
218
|
+
### Catalog Sync
|
|
118
219
|
|
|
119
|
-
|
|
220
|
+
`sync:tools --check` is intended for publish-time live drift checks. It fails fast when
|
|
221
|
+
`AINECTO_CATALOG_SYNC_TOKEN` is missing, so automatic publish cannot silently fall back to fixtures.
|
|
222
|
+
For local development, `sync:tools` can also use credentials from `ainecto auth login --env <env>`.
|
|
120
223
|
|
|
121
224
|
```bash
|
|
122
|
-
|
|
225
|
+
AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env prod --check
|
|
226
|
+
AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env dev --check
|
|
123
227
|
```
|
|
124
228
|
|
|
125
|
-
The generated
|
|
229
|
+
The checked-in generated catalogs are deterministic output from `tools/list`, live-synced from
|
|
230
|
+
`https://ainecto.com/mcp` and `https://dev.ainecto.com/mcp`. Presentation metadata lives separately in
|
|
231
|
+
`src/core/catalog/enrichments.ts`. `ainecto tools catalog` prints the local generated catalog.
|
|
126
232
|
|
|
127
|
-
|
|
233
|
+
### Local Tarball Smoke
|
|
128
234
|
|
|
129
235
|
```bash
|
|
130
236
|
npm pack
|
|
131
|
-
|
|
132
|
-
npm exec --package ./ainecto-mcp-0.1.4.tgz -- ainecto --help
|
|
237
|
+
npm exec --package ./ainecto-mcp-<version>.tgz -- ainecto --help
|
|
133
238
|
```
|
|
134
239
|
|
|
135
|
-
|
|
240
|
+
### Live Dev MCP Smoke
|
|
136
241
|
|
|
137
|
-
This requires an authenticated dev token from `ainecto auth login --env dev` or a local developer
|
|
242
|
+
This requires an authenticated dev token from `ainecto auth login --env dev` or a local developer
|
|
243
|
+
`AINECTO_TOKEN`.
|
|
138
244
|
|
|
139
245
|
```bash
|
|
140
246
|
npm run smoke:mcp -- --env dev
|
|
141
247
|
```
|
|
142
248
|
|
|
143
|
-
The smoke initializes MCP, reads `tools/list`, calls `
|
|
249
|
+
The smoke initializes MCP, reads `tools/list`, calls `list_projects`, and prints only aggregate
|
|
250
|
+
metadata such as tool count and Task tool exposure.
|
|
144
251
|
|
|
145
|
-
|
|
252
|
+
### Local Attachment Upload Smoke
|
|
146
253
|
|
|
147
|
-
This exercises the full `attachments upload` flow against a local
|
|
148
|
-
|
|
254
|
+
This exercises the full `attachments upload` flow against a local API dev server: OAuth MCP token
|
|
255
|
+
issue, REST fixture document creation, CLI upload, `list_attachments`, and server filesystem byte
|
|
256
|
+
verification.
|
|
149
257
|
|
|
150
258
|
```bash
|
|
151
|
-
npm run smoke:attachments -- --base-url http://localhost:8080 --endpoint http://localhost:8080/mcp --api-root
|
|
259
|
+
npm run smoke:attachments -- --base-url http://localhost:8080 --endpoint http://localhost:8080/mcp --api-root <path-to-api-repo>
|
|
152
260
|
```
|
|
153
261
|
|
|
154
|
-
The smoke creates a temporary user/workspace/project/document and removes the fixture account, local
|
|
262
|
+
The smoke creates a temporary user/workspace/project/document and removes the fixture account, local
|
|
263
|
+
temp file, and stored upload file unless `--keep` is supplied.
|
|
155
264
|
|
|
156
|
-
|
|
265
|
+
### Releasing
|
|
266
|
+
|
|
267
|
+
`npm run release -- --otp=<code>` runs typecheck, test and build once, then publishes that build under
|
|
268
|
+
three names: `@ainecto/mcp` (primary), `ainecto`, and `@ainecto/cli` (only the `ainecto` command).
|
|
269
|
+
`--dry-run` shows what would go out. An already-published name is skipped, so a retry after an expired
|
|
270
|
+
code is safe. The npm account needs write access to the `@ainecto` org (the script checks). Do not
|
|
271
|
+
unpublish any name.
|
|
157
272
|
|
|
158
|
-
|
|
273
|
+
## Known Limitations
|
|
159
274
|
|
|
160
|
-
|
|
275
|
+
- The MCP connector implements newline-delimited stdio JSON-RPC to HTTP JSON-RPC. Streamable HTTP SSE
|
|
276
|
+
responses and `MCP-Session-Id` session handling are not implemented.
|