aimm-scaffold

AIMM scaffold

aimm-mcp is a local MCP server that stores SQL-data-model metadata in one JSON file per project: <slug>.aimm.json. Project files live in a folder of the user's choice (defaults to ~/Documents/AIMM/), so a team can keep them in a shared repo and hand-edit / diff / PR the same way they do any other code artefact.

Where state lives

~/Documents/AIMM/                   ← machine-local, never moves
├── state.json                        which folder + which active file
├── discovered_joins.json             scan output (not project state)
└── diagnostics.log                   ODBC query append-log

<projects_folder>/                  ← configurable; defaults to ~/Documents/AIMM/
├── customer_warehouse.aimm.json      one project
├── reporting_model.aimm.json         another project
└── …

Every project-touching write tool reads → mutates → atomic-writes the active project file.

Session bootstrap — required before any project tool runs

Tools that read or write a project will error with "project file not selected" until an active project is set. Don't try to work around this: ask the user which project they want.

1. Inspect the current pointer. aimm_show_active_project() returns projects_folder + active_project_file + status. Call this first.

2. If a different projects folder is needed, ask the user where their .aimm.json files live (typically a team repo). Then: aimm_set_projects_folder({path: "/abs/path/to/folder"}). This also clears the active pointer.

3. See what's available. aimm_list_projects() returns the filename, internal project name, and updated_at for each *.aimm.json in the folder.

4. Pick one. aimm_set_active_project({filename: "customer_warehouse.aimm.json"}). Subsequent tool calls now read and write that file.

5. Or create a new one. aimm_init_project({name: "Customer Warehouse", description?, dialect?}). Writes customer_warehouse.aimm.json (slug from name) into the current folder and sets it active. If the file already exists, call aimm_set_active_project instead.