aiquila CLAUDE.md

AIquila — Claude Code Configuration

Project Overview

Monorepo with two independently versioned components:

• mcp-server/ — TypeScript/Node.js MCP server (npm package: aiquila-mcp, admin account: aiquila on npmjs.com; versioned in package.json)
• nextcloud-app/ — PHP 8.4 Nextcloud app (Composer, versioned in appinfo/info.xml)

Docs live in docs/. Docker environments in docker/ (dev: installation/, prod: standalone/).

Key Commands

All MCP server commands run from mcp-server/:

npm run build      # compile TypeScript → dist/
npm run dev        # hot reload via tsx (stdio transport by default)
npm test           # vitest unit tests
npm run lint       # eslint (warnings ok, errors fail CI)
npm run format     # prettier --write src/  (auto-fix formatting)
npx prettier --check src/   # check only — run before committing

CI requires both npm run lint and npx prettier --check src/ to pass. Always run npm run format after editing TypeScript files.

HTTP transport locally:

MCP_TRANSPORT=http npm run dev   # serves at http://localhost:3339/mcp

Docker (standalone — external Nextcloud):

cd docker/standalone && make up
make logs-follow
make test

Nextcloud app — static analysis

Psalm runs over lib/ at errorLevel=3 and CI fails on any error:

cd nextcloud-app && composer psalm

OCP\* resolves through vendor/nextcloud/ocp (parsed via <extraFiles>); the private OC\ classes the app touches are stubbed in tests/stubs/. There is no baseline — fix findings rather than adding one.

Nextcloud app — OpenAPI spec

After editing a controller annotated with #[OpenAPI], regenerate and commit the spec (CI fails on a mismatch):

cd nextcloud-app && vendor/bin/generate-spec   # updates openapi.json + openapi-full.json

Nextcloud app — local dev testing

To test working-tree changes in the dev stack (docker/installation/) and check for runtime errors:

cd docker/installation
make build-tarball            # repackage nextcloud-app/ from the working tree
make up                       # IMPORTANT: rebuilds the image with the new tarball
# The post-install hook only runs on first install, so re-extract manually after a recreate:
docker compose exec -T nextcloud bash /docker-entrypoint-hooks.d/post-installation/aiquila-install.sh
docker compose exec -T nextcloud su -p www-data -s /bin/sh -c "php /var/www/html/occ upgrade"   # if migrations changed