- Node.js 24 or newer, with npm
- Git
- A database to test against. SQLite needs nothing installed and is enough for most work; the other adapters need a reachable server.
There is no Docker Compose file, no .env handling and no migration tooling in
this repository. Argos connects to databases you already have; it does not
create or manage any.
git clone https://github.com/AraneaDev/argos.git
cd Argos
npm install
npm run buildnpm install runs husky, which installs the pre-commit hook. npm run build
type-checks first, then compiles to dist/ and marks the two entry points
executable.
Create a configuration to work against:
npm run setup # interactive wizard
# or
cp config.ini.template config.ini && $EDITOR config.ini
chmod 600 config.iniThe quickest useful configuration is a SQLite file, which needs no server:
[database.scratch]
type=sqlite
file=./scratch.sqlite
select_only=true
[extension]
max_rows=1000
query_timeout=30000Run the server against it:
node dist/cli.js serve --config ./config.iniIt waits for JSON-RPC on stdin and logs to argos.log. It will look idle,
because it is: the client drives it. Ctrl+C to stop.
To exercise it the way a client does, register the local build:
claude mcp add argos-dev -- node "$(pwd)/dist/cli.js" serve --config "$(pwd)/config.ini"| Command | What it does |
|---|---|
npm run dev |
tsc --watch; rebuilds dist/ as you edit |
npm test |
The whole suite |
npm run test:watch |
The suite in watch mode |
npm run test:unit / test:integration |
One tree at a time |
npm run test:coverage |
Suite plus a coverage report in coverage/ |
npm run type-check |
tsc --noEmit, no output written |
npm run lint |
ESLint with --fix |
npm run lint:check |
ESLint without fixing, as CI runs it |
npm run format / format:check |
Prettier, writing or checking |
npm run validate |
lint:check, format:check, type-check, test — run this before pushing |
npm run validate-docs |
Checks the docs against the code for the things it can verify |
npm run build |
Clean, type-check, compile |
npm run build:fast |
esbuild bundle; quicker, for iterating |
npm run validate is what CI runs, so a clean run locally means a clean run
there.
The pre-commit hook runs automatically and will:
- refuse files that look like credentials, including a private key pasted into a test fixture
- run Prettier and ESLint over the staged files
If it blocks something you believe is fine, look at what it matched before
reaching for --no-verify: that flag skips the formatting and linting too. The
hook is in .husky/pre-commit and is short enough to read.
Commit messages follow Conventional Commits, and the PR title is checked separately because a squash merge takes the title as the commit subject.
The server never writes to stdout: that stream carries JSON-RPC, and anything
else on it breaks the client. Everything goes to argos.log, rotated to
argos.log.1 on each start.
tail -f argos.log
grep -E '\[(ERROR|CRITICAL)\]' argos.logSSH_DEBUG=true adds the ssh2 handshake trace to the same file. There is no
general verbosity switch; the level is INFO.
For a single test, jest's own filtering is usually enough:
npx jest tests/unit/adapters/mysql-adapter.test.ts -t "full table scan"To step through code, run jest under the inspector:
node --inspect-brk node_modules/.bin/jest --runInBand tests/unit/some.test.tssrc/
index.ts entry point; starts the server
setup.ts entry point; the configuration wizard
classes/ SQLMCPServer and the managers it coordinates
database/adapters/ one adapter per engine, over a shared base class
tools/ MCP tool definitions, dispatcher, handlers
types/ shared types
utils/ config, logging, errors, auditing
tests/
unit/ mirrors src/
integration/ server and tunnel behaviour end to end
fixtures/ shared test data
examples/ templates to copy, including a custom adapter
scripts/ validate-documentation.js, verify-sqlite-streaming.cjs
Start from examples/custom-adapters/adapter-template.ts, which implements
every abstract member of DatabaseAdapter with each one commented. Register the
finished class in src/database/adapters/AdapterFactory.ts, and add a test file
mirroring the existing adapter tests.
See Database Layer for what the base class provides and what the subclass owes it.