Skip to content

docs(publishing): answer the agent's question on the MCP page, and give the site root real content - #344

Open
jswir wants to merge 2 commits into
malloydata:mainfrom
jswir:docs/mcp-agent-job
Open

jswir wants to merge 2 commits into
malloydata:mainfrom
jswir:docs/mcp-agent-job

Conversation

@jswir

@jswir jswir commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Why

Someone asking an AI assistant "how do I let a coding agent query my warehouse safely" does not currently reach these pages, and the two pages most likely to be cited are the two least able to answer.

What changed

The site root served a redirect shim. src/index.html used layouts/redirect.html, which emits <title>Page Redirection</title>, ~15 words of body, and a one-second meta-refresh. Deployment is GitHub Pages so a real 301 is not available from this repo — but the root does not need to redirect at all. It now serves a short landing page: what Malloy is, what Publisher is, how to serve a model over MCP, and links into the docs. The /documentation link stays first so humans still get there in one click.

The MCP page opened with a feature description — "Connect AI assistants to your Malloy semantic models using the Model Context Protocol". It now opens with the question people arrive with, and answers it: the agent queries the semantic model, so it works from the sources, joins and measures you defined and cannot invent a table or write arbitrary SQL against production.

The quick start now shows claude mcp add alongside the JSON config, and a short section covers moving the same model from local DuckDB to a warehouse. Stdio bridging and reload semantics are unchanged; they now follow the job rather than preceding it.

Second commit: the page was out of date with Publisher. Three fixes:

  • Start command. --server_root <dir> with no config starts a server that reports serving with no packages. Both the MCP page and the new landing page now lead with the bundled examples (npx @malloy-publisher/server@latest) and the scaffolder for your own data, then show a check that packages actually loaded.
  • Tool reference. It used the pre-rename malloy_* names, and described get_context parameters it no longer takes. It now lists the eight tools Publisher registers, including list_packages, get_status and search_database_schema, which the page never mentioned.
  • Security note. It said Publisher binds 0.0.0.0, so port 4040 is open. The MCP port binds 127.0.0.1 by default (server.ts:259). The REST port binds 0.0.0.0, and REST reaches the same data, so the warning now names that port.

TOC: MCP for AI Agents moves from sixth to second in Publishing, directly after Publish Your Models.

Incidental fix: layouts/redirect.html interpolated {{ site.baseurl }} twice in all four of its URLs. Harmless only because every npm script passes --baseurl ''. That layout is still used by src/slack.html and documentation/samples.malloynb.

Verification

npm run build-prod, which is what CI runs.

  • The build reports 1539 pre-existing errors on this checkout. A clean build of origin/main reports the same 1539 — these changes add none.
  • All nine links from the new root page resolve.
  • The root renders with a real title and 442 words, previously 15.
  • mcp_agents.html and samples.html both still render correctly.

I have not tried to fix the pre-existing build errors; they look unrelated (undefined airports in visualization notebooks) and belong in their own PR.

…ve the site root real content

Three changes, all aimed at the same problem: someone asking an AI assistant
how to let an agent query their warehouse never reaches these pages.

The site root was a redirect shim. src/index.html used layouts/redirect.html,
which emits <title>Page Redirection</title>, about fifteen words of body, and
a one-second meta-refresh. Deployment is GitHub Pages, so a real 301 is not
available from this repo -- but the root does not need to redirect at all. It
now serves a short landing page: what Malloy is, what Publisher is, how to
serve a model over MCP, and links into the docs. The /documentation link stays
first so humans still get there in one click.

The MCP page opened with a feature description ("Connect AI assistants to your
Malloy semantic models using the Model Context Protocol"). It now opens with
the question people actually arrive with -- how do I let an agent near my data
without it writing arbitrary SQL -- and answers it: the agent queries the
semantic model, so it works from the sources, joins and measures you defined
and cannot invent a table. The quick start now shows `claude mcp add` alongside
the JSON config, and a short section covers moving the same model from local
DuckDB to a warehouse. The tool reference, stdio bridging, reload semantics and
the security warning are unchanged and simply follow the job rather than
preceding it.

MCP for AI Agents moves from sixth to second in the Publishing section of the
table of contents, directly after Publish Your Models.

Also fixes layouts/redirect.html, which interpolated {{ site.baseurl }} twice
in all four of its URLs. Harmless only because every npm script passes
--baseurl '' -- it would have produced doubled paths under any other baseurl.
That layout is still used by src/slack.html and documentation/samples.malloynb.

Verified with `npm run build-prod`, which is what CI runs. The build reports
1539 pre-existing errors on this checkout, identical to a clean build of
origin/main -- these changes add none. All nine links from the new root page
resolve, and the root now renders with a real title and 442 words instead of
fifteen.

Signed-off-by: James Swirhun <james@credibledata.com>
…a, and the real bind defaults

The MCP page and the new landing page would have sent readers to three
things that do not work on current Publisher:

- `--server_root ./packages` with no config starts a server that reports
  "serving" with no packages. Both pages now lead with the bundled
  examples (`npx @malloy-publisher/server@latest`) and the scaffolder for
  your own data, then check that packages actually loaded.
- The tool names were the pre-rename `malloy_*` set, and get_context's
  parameters described a shape it no longer takes. The tool reference now
  lists the eight tools Publisher registers, including list_packages,
  get_status and search_database_schema, which the page never mentioned.
- The security note said Publisher binds 0.0.0.0, so port 4040 is open.
  The MCP port binds 127.0.0.1 by default; it is the REST port that binds
  0.0.0.0, and REST reaches the same data.

Signed-off-by: James Swirhun <james@credibledata.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant