@ainecto/mcp 0.1.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.
Files changed (6) hide show
  1. package/README.md +128 -0
  2. package/dist/bin/ainecto.js +1691 -0
  3. package/dist/bin/ainecto.js.map +1 -0
  4. package/dist/bin/mcp.js +586 -0
  5. package/dist/bin/mcp.js.map +1 -0
  6. package/package.json +35 -0
package/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # @ainecto/mcp
2
+
3
+ Ainecto MCP connector and first-party CLI.
4
+
5
+ This package exposes two entry points:
6
+
7
+ - `npx -y @ainecto/mcp` or `ainecto mcp`: raw stdio-to-HTTP JSON-RPC proxy for Ainecto MCP.
8
+ - `ainecto <command>`: human CLI for auth and low-level tool calls.
9
+
10
+ Phase 1 keeps the connector as a raw proxy. File, stdin, and inline JSON parsing are only available in first-party CLI commands.
11
+
12
+ ## Local Setup
13
+
14
+ ```bash
15
+ npm install
16
+ npm run typecheck
17
+ npm test
18
+ npm run build
19
+ npm link
20
+ ```
21
+
22
+ ## Commands
23
+
24
+ ```bash
25
+ ainecto auth login --env dev
26
+ ainecto auth status --env dev
27
+ ainecto auth logout --env dev
28
+
29
+ ainecto tools list --env dev
30
+ ainecto tools call mcp__ainecto__list_projects --env dev --json
31
+ ainecto tools call mcp__ainecto__erd_apply_changes -f changes.json --json
32
+ cat payload.json | ainecto tools call mcp__ainecto__erd_apply_changes --json
33
+
34
+ ainecto projects list --env dev
35
+ ainecto task list-tasks --env dev --document-uuid <documentUuid> --json
36
+ ainecto erd apply-changes --env dev -f erd-operations.json --yes
37
+ ```
38
+
39
+ Endpoint resolution priority:
40
+
41
+ 1. `--endpoint <url>`
42
+ 2. `AINECTO_MCP_ENDPOINT`
43
+ 3. `--env dev`
44
+ 4. production default, `https://ainecto.com/mcp`
45
+
46
+ ## Connector Mode
47
+
48
+ ```bash
49
+ npx -y @ainecto/mcp
50
+ ainecto mcp --env dev
51
+ ```
52
+
53
+ The connector proxies `initialize`, `tools/list`, and `tools/call` to the resolved `/mcp` endpoint. It does not rewrite remote schemas or interpret local file references.
54
+
55
+ ## Catalog Sync
56
+
57
+ `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.
58
+ For local development, `sync:tools` can also use credentials from `ainecto auth login --env <env>`.
59
+
60
+ ```bash
61
+ AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env prod --check
62
+ AINECTO_CATALOG_SYNC_TOKEN=... npm run sync:tools -- --env dev --check
63
+ ```
64
+
65
+ The checked-in generated catalogs are deterministic output from `tools/list`. The dev catalog has been live-synced from `https://dev.ainecto.com/mcp`; the prod catalog remains a seed fixture until prod auth is available. Presentation metadata lives separately in `src/core/catalog/enrichments.ts`.
66
+
67
+ `ainecto tools catalog` prints the local generated catalog. Prod output is fixture-only until authenticated prod live sync updates `generated.prod.ts` and `tools-list.prod.json`.
68
+
69
+ ## Generated Friendly Commands
70
+
71
+ 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:
72
+
73
+ ```bash
74
+ ainecto task list-tasks --env dev --document-uuid <documentUuid>
75
+ ainecto task list-tasks --env dev --documentUuid <documentUuid>
76
+ ```
77
+
78
+ Array or object payloads use the existing first-party CLI JSON payload reader:
79
+
80
+ ```bash
81
+ ainecto documents create --env dev -f create-documents.json
82
+ cat task-ops.json | ainecto task apply-changes --env dev --json
83
+ ```
84
+
85
+ Destructive generated commands prompt in human mode unless `--yes` is supplied. In `--json` mode they fail with a structured error unless `--yes` is present.
86
+
87
+ Attachment file upload is available through a bespoke command that performs the upload-token, raw PUT, and attachment registration flow:
88
+
89
+ ```bash
90
+ ainecto attachments upload --env dev --document-uuid <documentUuid> ./diagram.png ./notes.pdf
91
+ ```
92
+
93
+ The generated `request_upload_token` and `upload_attachments` paths remain raw MCP argument-contract commands and do not read local files.
94
+
95
+ ## Local Tarball Smoke
96
+
97
+ ```bash
98
+ npm pack
99
+ npx -y ./ainecto-mcp-0.1.0.tgz --help
100
+ npm exec --package ./ainecto-mcp-0.1.0.tgz -- ainecto --help
101
+ ```
102
+
103
+ ## Live Dev MCP Smoke
104
+
105
+ This requires an authenticated dev token from `ainecto auth login --env dev` or a local developer `AINECTO_TOKEN`.
106
+
107
+ ```bash
108
+ npm run smoke:mcp -- --env dev
109
+ ```
110
+
111
+ The smoke initializes MCP, reads `tools/list`, calls `mcp__ainecto__list_projects`, and prints only aggregate metadata such as tool count and Task tool exposure.
112
+
113
+ ## Local Attachment Upload Smoke
114
+
115
+ This exercises the full `attachments upload` flow against a local `ainecto-api` dev server:
116
+ OAuth MCP token issue, REST fixture document creation, CLI upload, `list_attachments`, and server filesystem byte verification.
117
+
118
+ ```bash
119
+ npm run smoke:attachments -- --base-url http://localhost:8080 --endpoint http://localhost:8080/mcp --api-root /Users/ryan/project/workspace/codelive/ainecto-api
120
+ ```
121
+
122
+ 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.
123
+
124
+ ## Known Limitations
125
+
126
+ - The MCP connector currently implements newline-delimited stdio JSON-RPC to HTTP JSON-RPC. Streamable HTTP SSE responses and `MCP-Session-Id` session handling are not implemented in Phase 1.
127
+
128
+ Public publish is blocked until the npm `@ainecto` org and publish secrets are ready.