Ainecto

Ainecto MCP connector for workspace, document, ERD, diagram, task, and attachment workflows.

Open source Open in the app JSON README (API)

About

Ainecto MCP connector for workspace, document, ERD, diagram, task, and attachment workflows.

Details

Kind: MCP servers
Topic: Media, design & games
Publisher: codelives
Origin: official
Category: ferramentas
Transport: local
Version: 0.1.2
Forks: 1
Open pull requests: 1
Last push: 2026-07-12T10:50:54Z
Repository state: ativo
Language: TypeScript
Added: 2026-08-29 03:02:36
Updated: 2026-08-29 03:02:36
Origin id: io.github.codelives/ainecto

README

# @ainecto/mcp

Ainecto MCP connector and first-party CLI.

This package exposes two entry points:

- `npx -y @ainecto/mcp` or `ainecto mcp`: raw stdio-to-HTTP JSON-RPC proxy for Ainecto MCP.
- `ainecto <command>`: human CLI for auth and low-level tool calls.

Phase 1 keeps the connector as a raw proxy. File, stdin, and inline JSON parsing are only available in first-party CLI commands.

## Local Setup

```bash
npm install
npm run typecheck
npm test
npm run build
npm link
```

## Commands

```bash
ainecto auth login --env dev
ainecto auth status --env dev
ainecto auth logout --env dev

ainecto tools list --env dev
ainecto tools call mcp__ainecto__list_projects --env dev --json
ainecto tools call mcp__ainecto__erd_apply_changes -f changes.json --json
cat payload.json | ainecto tools call mcp__ainecto__erd_apply_changes --json

ainecto projects list --env dev
ainecto task list-tasks --env dev --document-uuid <documentUuid> --json
ainecto erd apply-changes --env dev -f erd-operations.json --yes
```

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.

## Connector Mode

```bash
npx -y @ainecto/mcp
ainecto mcp --env dev
```

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.

## MCP Client Installation

Use the direct package configuration until the server is published to the official MCP Registry.

```json
{
  "mcpServers": {
    "ainecto": {
      "command": "npx",
      "args": ["-y", "@ainecto/mcp"]
    }
  }
}
```

For a non-production endpoint, pass CLI flags through the package args:

```json
{
  "mcpServers": {
    "ainecto-dev": {
      "command": "npx",
      "args": ["-y", "@ainecto/mcp", "--env", "dev"]
    }
  }
}
```

The planned official Registry server name is `io.github.codelives/ainecto`, backed by the public npm package `@ainecto/mcp`. Registry publication requires the npm package version referenced by `server.json` to include a matching `mcpName` field in `package.json`.

## 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>`.

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

The checked-in generated catalogs are deterministic output from `tools/list`. The prod and dev catalogs are live-synced snapshots 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. Rerun authenticated `sync:tools` when prod or dev `tools/list` changes.

## 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:

```bash
ainecto task list-tasks --env dev --document-uuid <documentUuid>
ainecto task list-tasks --env dev --documentUuid <documentUuid>
```

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

```bash
ainecto documents create --env dev -f create-documents.json
cat task-ops.json | ainecto task apply-changes --env dev --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:

```bash
ainecto attachments upload --env dev --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.

## Local Tarball Smoke

```bash
npm pack
npx -y ./ainecto-mcp-0.1.4.tgz --help
npm exec --package ./ainecto-mcp-0.1.4.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`.

```bash
npm run smoke:mcp -- --env dev
```

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.

## Local Attachment Upload Smoke

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

```bash
npm run smoke:attachments -- --base-url http://localhost:8080 --endpoint http://localhost:8080/mcp --api-root /Users/ryan/project/workspace/codelive/ainecto-api
```

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.

## Known Limitations

- 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.

Official MCP Registry publish is pending GitHub namespace owner authentication with `mcp-publisher` and metadata submission.

Ainecto

About

Details

README

More