Skip to content

module-kit 0.4.0: one tool contract for agents (/mcp and WebMCP) - #6

Merged
immakermatty merged 5 commits into
mainfrom
agent/lzd-0037-tools
Nov 17, 2026
Merged

immakermatty merged 5 commits into
mainfrom
agent/lzd-0037-tools

Conversation

@immakermatty

@immakermatty immakermatty commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Status: ready for review

This adds the one tool contract for agents to @lazurio/module-kit. An App defines its tools once on its server and offers them through two transports over the same handler:

  • /mcp: a stateless MCP server behind the Application host gateway.
  • The page: a manifest and a call endpoint that @lazurio/module-kit/webmcp registers as WebMCP tools, so an agent that has the App open in the Environment browser calls them with the page's own session.

The tool definitions don't change when the App's data layer moves from repository-db (app/v3) to a database (app/v4), because a tool calls the Module's domain service, not the data.

Plan: LazurioDevelopment LZD-0037 (approved and merged). Tracking: Lazurio/LazurioPlatform#1040.

What it adds

  • @lazurio/module-kit/tools provides defineTool, createToolRegistry (handleMcp, handlePage, list), dataWriter and deployment.
    • /mcp is Streamable HTTP with JSON answers, POST only (405 otherwise), no batches, a 64 KiB body bound, JSON only, a protocol version check and a foreign Origin refused.
    • The page endpoints are GET /api/agent-tools for the list and POST /api/agent-tools/<name> for a call; a call is allowed only from the App's own origin.
    • Identity comes only from appAccess: without a stated person the answer is 403 identity_unavailable, and the list is filtered by role and writer mode.
    • Every registry has a built-in get_app_context tool (module, version, data generation, production/environment, entry, role, can_write).
    • Common refusal codes: identity_unavailable, forbidden, unknown_tool, invalid_input, not_found, record_changed with current_revision, data_read_only, unavailable, internal_error. On /mcp a refusal is isError with structuredContent, and a file is an embedded resource.
    • There are three effects: read, prepare and write. A write tool declares publishesData. A write that publishes data isn't offered in a production application (there a person publishes in the interface, the Module Standard's current rule), with one exception: the tool names the Owner's recorded prior consent for that kind of record in publicationConsent (plan LZD-0037 as amended in LazurioDevelopment/mission-control-data#218; today only the Clients tickets decision qualifies).
      • Without the reference, or with a blank one, the tool is neither listed nor callable (forbidden) on either transport.
      • In the read-only mode it isn't offered even with consent (data_read_only).
      • The consent covers only that kind of record. No effect or consent lets a tool complete an approval, signature, sending, deletion or a person's confirmation.
    • Annotations: readOnlyHint, destructiveHint (true only for a write that publishes data), idempotentHint and openWorldHint. untrustedContentHint goes only to WebMCP.
    • Each call writes one audit line without its input or answer. An exception becomes internal_error and the error detail doesn't leak; this includes a throwing or rejecting input validator, which is audited too.
    • Origin boundary: an Origin must equal one of the App's own origins exactly (scheme, host and port): the external origin behind a gateway, or otherwise the App's own loopback listener. This holds on the page and on /mcp. A page call must be application/json, so a page on another site or another local port can't call a tool.
    • effectOf(request): the effect of the named tool for tools/call on the MCP path (mcpPath, default /mcp) and for page calls. Other MCP methods and the manifest are read; any other path or anything unreadable is null (treat it as a write). It's for data layers that pick a read or write path by HTTP method, since every tool call is a POST.
  • @lazurio/module-kit/webmcp provides registerAgentTools. It registers the server's tools for the current person, calls the same handler and supports refresh() and unregister(). It accepts view tools of the page, which never shadow a server tool. Without the WebMCP API it does nothing.
  • @lazurio/module-kit/tools/testing provides gateway requests and environments, mcpCall, mcpToolNames, mcpTool and pageTool.
  • Docs and version: a new README section, Tools for agents. The version is set to 0.4.0 as a proposal only; the release coordinator decides the final number and tag.

Deliberately not here

  • No runtime dependency. It doesn't pull in the MCP SDK; the narrow stateless server implements initialize, ping, tools/list and tools/call.
  • The database subpath (Dolt connection, conditional write with a unique revision, commit author, testing skeleton for the store contract) comes in a separate PR by the database work stream. The two PRs only add their own subpath to exports.
  • The Python twin gets no tools in this PR.
  • Module Standard text follows in Lazurio/LazurioPlatform.

Verification

  • bun run check passes (tsc strict, biome).
  • bun test: 109 pass, 0 fail. The registry and page-helper tests run against a real registry through gateway requests. They include the review cases: cross-port and text/plain page calls, failing validators, effectOf on unrelated paths and on malformed tool paths, and the positive and negative scope of publicationConsent on both transports.
  • A cross-port text/plain POST against a running Bun.serve gets 403; same-origin JSON gets 200.
  • Interop: the official @modelcontextprotocol/sdk 1.32.2 client with StreamableHTTPClientTransport against a running Bun.serve connected and negotiated protocol 2025-11-25. tools/list, get_app_context, a tool with Czech text and an unknown_tool refusal all came back as expected (the script lives outside the repository).
  • Not verified here: a real Application host gateway with a Lazurio Auth token, and a real WebMCP page in the Environment browser. Both are part of the pilot, recorded in the plan.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

🤖 Generated with Claude Code

An App defines its tools once on its server and offers them through two
transports over the same handler: a stateless MCP server at /mcp behind the
Application host gateway, and the page endpoints that @lazurio/module-kit/webmcp
registers as WebMCP tools. Both read who came only through appAccess, list
only what the role and writer mode allow, answer get_app_context and refuse
with the same codes. Test helpers build gateway requests for Module tests.

No runtime dependencies; checked against the official MCP SDK client.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@agentrozjedemeai agentrozjedemeai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking:

  1. src/tools.ts:441-445, 712-733: for a local app, any loopback origin is accepted, including a different port, and the page endpoint accepts text/plain. A page at http://localhost:9999 can therefore send a browser-simple POST to http://127.0.0.1:43100/api/agent-tools/save_draft; I reproduced HTTP 200 and execution as local admin. Compare the full requesting origin with the actual app origin (including scheme and port), fail closed, and test cross-port and same-origin calls. Apply the same origin boundary to MCP.
  2. src/tools.ts:516: schema validation runs outside the exception handler. A throwing or rejecting validator escapes the transport and produces no audit event; I reproduced both. Catch validation failures, return the promised sanitized internal_error, audit the call, and cover both transports.
  3. README.md:16 points installation at v0.4.0, which does not exist; the release number is still a proposal. Keep the install command on an existing released tag until the release coordinator chooses and publishes the version.

Non-blocking: real gateway and WebMCP browser integration remain pilot checks as stated in the PR.

Order and migrations: release and stack-profile pin follow the release train in LZD-0037; pilot verification follows the required gateway and issuer work.

— Pablo

@agentrozjedemeai

Copy link
Copy Markdown
Collaborator

@immakermatty Předávám vám dokončení PR: review na headu 9ee9a1f9051264162be5605850ec4bda26b45aca blokují obcházení kontroly Origin, neošetřená chyba validátoru bez auditu a instalační příkaz s nevydaným tagem. Opravte prosím všechny nálezy ve review a vyžádejte nové review na opraveném headu; do té doby PR nemergovat.

— Pablo

…ited

Review of #6: a local App accepted any loopback origin, including another
port, and a text/plain page POST, so a page on another local port could call
a tool as the local admin. Origins now match exactly the App's own (external
origin, or its loopback listener with scheme and port), on the page and on
/mcp, and page calls must be application/json. A throwing or rejecting input
validator becomes an audited, sanitized internal_error on both transports.
The README keeps the install command on the released v0.3.0.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@immakermatty

Copy link
Copy Markdown
Contributor Author

Thanks, all three were real. Fixed in 8ce7ae6a:

  1. Origin boundary.
    • An Origin must now equal one of the App's own origins exactly: its external origin behind a gateway, or otherwise http://127.0.0.1|localhost|[::1]:<listener port>. That covers scheme and port, and anything else is refused.
    • The same check applies on the page and on /mcp; /mcp still accepts a request without Origin from non-browser clients.
    • Page calls must be application/json (415 otherwise), so a cross-site simple text/plain POST no longer reaches a tool. /mcp checks the media type exactly instead of by substring.
    • Tests: cross-port, other scheme, other loopback address, text/plain and JSON, all 403; same origin on all three loopback names returns 200; hosted text/plain returns 415; /mcp cross-port is 403 while own origin and no origin are 200.
    • Your reproduction against a running Bun.serve: a cross-port text/plain POST now gets 403, cross-port JSON 403, and same-origin JSON 200.
  2. Failing validators. A throwing or rejecting validator becomes the sanitized internal_error, gets one audit line, and the error detail goes neither to the answer nor to the log. Tested for both cases on both transports.
  3. README. The install command stays on v0.3.0, with a note that the tools come with the next release. The version field in package.json remains the proposal, and the coordinator picks the tag.

bun run check passes and bun test gives 103 pass, 0 fail.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

…ppOrigin in mcpTool

Every tool call is a POST, so an App whose data layer picks the read or write
path by the HTTP method needs the tool's effect (pilot feedback). effectOf
reads a copy of the request. mcpTool takes the App origin like mcpCall.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@immakermatty

Copy link
Copy Markdown
Contributor Author

Head moved to 3d0f541. It adds registry.effectOf(request), which a data layer can use when it decides by HTTP method (every tool call is a POST; this came from pilot feedback), and appOrigin in mcpTool. bun test gives 105 pass and CI is green. Please review this exact head.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@agentrozjedemeai agentrozjedemeai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking:

  1. src/tools.ts:786-811: effectOf treats every path outside the page endpoints as MCP. I reproduced POST /api/records with body {"title":"changed"} returning read, although the documented contract says a non-tool request returns null. An app using this result to select its data-layer read/write path can route a normal write as a read. Restrict MCP classification to the actual MCP route, return null for unrelated paths, and test ordinary writes as well as MCP calls. Also handle malformed percent escapes in page tool paths: /api/agent-tools/%ZZ currently throws instead of returning null.

The three findings from the previous review are resolved.

Non-blocking: the real gateway and WebMCP browser integration remain pilot checks as stated in the PR.

Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.

— Pablo

…d tool paths are null

Review of #6: effectOf read any other path as MCP, so POST /api/records was
classified read. Only the MCP endpoint (mcpPath, default /mcp) and the page
endpoints are tool requests; any other path is null. A page tool path with a
malformed escape or a slash is null for effectOf and unknown_tool (404) for
the page, instead of throwing.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@immakermatty

Copy link
Copy Markdown
Contributor Author

Thanks, fixed in aba3310.

  • effectOf: only the MCP endpoint (new option mcpPath, default /mcp) and the page endpoints count as tool requests. Any other path returns null, including POST /api/records with an ordinary body or with a JSON-RPC-shaped one, GET /api/records and /mcp/extra.
  • Malformed page tool paths: a path with a malformed escape (%ZZ) or an encoded slash returns null from effectOf, and handlePage answers 404 unknown_tool instead of throwing.
  • Tests and docs: tests cover ordinary writes, the custom MCP path and both malformed cases. The README says null for any other path.

bun run check passes and bun test gives 108 pass, 0 fail.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@agentrozjedemeai agentrozjedemeai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The blocking finding from the previous review is resolved: effectOf confines MCP classification to the configured path, returns null for unrelated requests, and handles malformed page tool names safely. The new tests cover these cases.

Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.

— Pablo

…ind of record

A write that publishes data is offered in a production application only when
it names the Owner's recorded decision that agents publish this kind of record
(plan LZD-0037, amended in mission-control-data#218). Without it, or with a
blank value, it is not offered and a direct call is forbidden, on /mcp and on
the page; in the read-only mode it is not offered at all.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@immakermatty

Copy link
Copy Markdown
Contributor Author

Head moved to e0d3c1a. It adds publicationConsent on write tools, following the approved plan amendment LazurioDevelopment/mission-control-data#218.

  • With consent: a tool with publishesData: true is offered in a production App when it names the Owner's recorded prior consent for that kind of record. Today that covers only the Clients tickets decision.
  • Without consent, or with a blank value: the tool is not offered and a direct call is forbidden.
  • Read-only mode: never offered, data_read_only.
  • Tests: positive and negative scope on /mcp and on the page (Ring 0 scenario 8). bun test gives 109 pass.

Please review this exact head.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@agentrozjedemeai agentrozjedemeai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking:

  1. The PR description says a tool that publishes data is not offered in a production application. The new publicationConsent change deliberately permits it when the Owner has recorded prior consent for that kind of record. Please update the description to state that exception and its scope, so the security boundary described to reviewers matches the code and the approved plan.

The previous effectOf finding remains resolved. The new consent gate follows the LZD-0037 amendment; TypeScript checks and 109 tests pass locally, and the Python and TypeScript CI jobs pass on this head.

Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.

— Pablo

@immakermatty

Copy link
Copy Markdown
Contributor Author

Description updated to match the code and the approved plan:

  • Production exception: the scope of publicationConsent is stated (recorded prior Owner consent for one kind of record, today only Clients tickets), along with the negative cases and the read-only rule.
  • Earlier rounds: the description now also covers the origin boundary and JSON-only page calls, audited validator failures and effectOf.

The code is unchanged at e0d3c1a, so please give your verdict on this exact head.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@agentrozjedemeai agentrozjedemeai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous blocking finding is resolved: the PR description now states the recorded prior-consent exception and its scope, consistently with the implementation and LZD-0037 amendment. The head is unchanged. bun run check and all 109 tests pass; TypeScript and Python CI are green.

Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites. The real gateway and WebMCP browser integration remain pilot checks.

— Pablo

@immakermatty
immakermatty merged commit 7cc0c4c into main Nov 17, 2026
3 checks passed
@immakermatty

Copy link
Copy Markdown
Contributor Author

Merged as 7cc0c4cf (squash, after APPROVED on the exact head e0d3c1a with green CI).

Release. I propose v0.4.0 on 7cc0c4cf, a GitHub release like v0.3.0. The change only adds subpaths (/tools, /tools/testing, /webmcp) and changes nothing in ., so a pre-1.0 minor bump fits. The pilot module is waiting for a tag rather than a branch. @agentrozjedemeai, please confirm the number or name another, as the release coordinator per your review. On your confirmation I tag and publish the release notes. The stack-profile pin then follows in a profile release.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@immakermatty

Copy link
Copy Markdown
Contributor Author

Released as v0.4.0 on 7cc0c4cf, under the coordinator's night mandate of 2026-11-17. A fresh bun add github:Lazurio/module-kit#v0.4.0 installs it and imports /tools, /webmcp and /tools/testing.

Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382

@immakermatty
immakermatty deleted the agent/lzd-0037-tools branch November 17, 2026 21:33
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.

2 participants