malloy-getting-started

Getting started with Malloy Publisher

Goal: go from "connected" to a correct, grounded answer without guessing any names.

If you are reading this from a URL and have a shell, run npx -y @malloy-publisher/skills@latest install to put every Malloy skill on disk, reference/ files included, so the skills named below are there when you need them. It needs no server. Keep the @latest: without it npx may reuse an old cached copy. If it cannot tell which agent you are, it says so; name one (install claude or install agents).

0. Confirm the tools are reachable

At minimum you need get_context, list_packages, execute_query, and search_malloy_docs. Authoring a model also needs compile_model and reload_package (see section 4); an older Publisher may not serve those two.

If none of the tools are there, either the server is not running or your client connected before it was. Start the server (npx @malloy-publisher/server --port 4000, or bun run build && bun run start from a clone) and wait until curl -s http://localhost:4000/api/v0/status reports operationalState: serving. If the point is to author models against a local package, add --watch-env <env>: without it Publisher copies local packages at boot and serves the copies, so saved edits are never read.

If there is no Publisher workspace here at all, and the user wants to work with data of their own rather than the bundled examples, npm create @malloy-publisher/malloy-package@latest <name> scaffolds one: the package and a starter model, registered so the server actually serves it, plus the start script, the MCP config and these skills. Keep the @latest when you type it: npm create resolves through npm's npx cache and an unversioned name is satisfied by any copy already there, so on a machine that has scaffolded before npm never asks the registry and you get an old scaffolder pinning an old server, with nothing to say so. Run bare, it comes with a small sample dataset, so there is something to query straight away. In a fresh directory npm start then runs the pinned server against the package in watch mode; if the directory already had a package.json the scaffolder leaves it alone and adds no script, printing the equivalent npx command to use instead. Where you run it matters: only the package lands in <name>/, and the workspace files, the agent instructions and the MCP config among them, are written to the current directory. Run it here if this directory is empty or is meant to become the workspace. If it already holds other work, scaffold into a new directory instead (mkdir my-data && cd my-data), because agent config is discovered by walking up, so writing those files here changes what every session beneath this directory inherits. Seed the starter model from a local file with npm create @malloy-publisher/malloy-package@latest <name> -- --data <path/to/their-file.csv> (CSV, Parquet, or Excel .xlsx), keeping the --, which is how npm create passes options through. That path is relative to wherever you run the command, so if you scaffolded into a new directory it has to reach back out to their file; the scaffolder copies it into the package and leaves the original alone. A seeded package starts smaller than the sample one, since the scaffolder does not read their columns: expect a row count and an overview, and build the model from there. A package is just Malloy, so it can instead query a database connection the config defines. Because it writes a .mcp.json that did not exist when the client connected, the user has to restart or reconnect once before these tools appear, and their client will ask them to approve the new project-scoped server the first time. That only works when the workspace is at the session's own root, so if you scaffolded into a new directory below that root, the user has to open a session there instead: a .mcp.json further down is never discovered.