Repository navigation
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
Open
docs(publishing): answer the agent's question on the MCP page, and give the site root real content#344jswir wants to merge 2 commits into
jswir wants to merge 2 commits into
Conversation
…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>
This was referenced Sep 22, 2026
Closed
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.htmlusedlayouts/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/documentationlink 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 addalongside 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:
--server_root <dir>with no config starts a server that reportsservingwith 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.malloy_*names, and describedget_contextparameters it no longer takes. It now lists the eight tools Publisher registers, includinglist_packages,get_statusandsearch_database_schema, which the page never mentioned.0.0.0.0, so port 4040 is open. The MCP port binds127.0.0.1by default (server.ts:259). The REST port binds0.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.htmlinterpolated{{ site.baseurl }}twice in all four of its URLs. Harmless only because every npm script passes--baseurl ''. That layout is still used bysrc/slack.htmlanddocumentation/samples.malloynb.Verification
npm run build-prod, which is what CI runs.origin/mainreports the same 1539 — these changes add none.mcp_agents.htmlandsamples.htmlboth still render correctly.I have not tried to fix the pre-existing build errors; they look unrelated (undefined
airportsin visualization notebooks) and belong in their own PR.