Skip to content

MCP follow-ups: propose_field scope, /mcp brake and thread caps, read-only pin, dev /mcp, live agent thread, class-aware note (#22) - #68

Merged
doxuta merged 14 commits into
mainfrom
slice/mcp-followups
Oct 27, 2026
Merged

doxuta merged 14 commits into
mainfrom
slice/mcp-followups

Conversation

@doxuta

@doxuta doxuta commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Issue #22 asks for six MCP follow-ups, and a seventh was added in a comment. Each one is fixed or measured below. The verification proves every fix.

Items

  1. propose_field: the caller's drafts, and the caller's tenant
    • The sibling check was already fixed in fix(ai): propose_field refuses a duplicate, reserved names in the tool contract, canonical table lookups (#30 items 3, 6) #40 (3ad3d41): checkAddFieldRefs(ctx, …) now receives the caller's context instead of context.Background(). Nothing pinned it, so this PR adds tests:
      • A unit test with a reader that shows the draft only to a ReadDraft Caller. It runs in a turn and through RunTool, the MCP entry point.
      • An integration test over a real /mcp on a delivered project. The builder adds hold to status as a draft, and a dependent value keyed on hold is accepted.
    • New: a table that is neither live in the tenant nor drafted (in this turn, or earlier in the MCP thread) now gets ENTITY_NOT_FOUND. This is the same answer propose_layout and propose_records give.
      • The tests cover another tenant's table and an unknown name, both in-app and over /mcp.
      • Two option-parity test cases had been proposing onto tenant-B's table and were buffered. They now name a table that tenant-A has.
  2. /mcp brake and thread caps
    • middleware.MCPRateLimit sits on the /mcp route in main.go and is built on the API's sliding window (memRateLimiter).
      • A token not yet seen working spends its client IP's lookup budget. That budget is APIKEY_PROBE_MAX_PER_MIN, the same one the nxk_ probe brake uses.
      • A token the handler answered with a 2xx spends its own budget, DATA_RATE_LIMIT_PER_MIN. Real agents behind one address therefore never wait on a prober's budget.
      • A 401 forgets the token, so a revoked key falls back to the IP budget.
      • A refused request gets the canonical 429 RATE_LIMITED with Retry-After.
    • Thread caps:
      • A thread takes at most 200 turns. Past that, a proposal gets THREAD_FULL and tells the agent to ask for a new key. Reads still work.
      • One proposal row is capped at 256 KiB (PROPOSAL_TOO_LARGE). Before this, the SDK's 4 MiB body limit was the only bound.
    • Tests:
      • Unit tests for the middleware.
      • An integration test against the real handler and token store.
      • The TestMCP_ integration router now carries the brake at its default budgets, as main.go does.
      • The main.go wiring is pinned like the other brakes.
  3. Structural pin
  4. next dev /mcp
    • The proxy behind app/api/v1/[...path] moved to lib/devProxy.ts, which takes the upstream path.
    • app/mcp/route.ts uses it for GET, POST and DELETE. It returns 404 outside development, as before.
  5. Open agent thread refresh
    • McpConnect passes the key's expiry to openThread.
    • Until the key expires, the open thread re-reads itself on focus, and every 5 s while the tab is visible.
    • It stops after 10 minutes with no new card; a focus wakes it again. An expired key stops it for good.
    • Read-back turns keep their m_<seq> ids, so cards already applied stay applied.
    • A turn sent from the tab itself stops the re-read.
  6. Tool list size: measured, no change. Numbers are below.
  7. The note after a proposal follows the change class (from the comment on MCP follow-ups (LOW) #22)
    • The note in a proposal's result now reads metaversion.ClassOf from the card's change envelope:
      • A draft type: "once the project is delivered it goes to drafts and reaches users when it is published".
      • Any other type (access, relationships, approvals, work queues, records): "it takes effect as soon as it is applied: there is no draft or publish step for it".
    • Tool descriptions and server instructions now say only what holds for every class: a human reviews and applies the card.

Item 6, measured on this branch after #58 and #66

bytes
ai.ToolDefinitions() sent per model call (26 tools) 52,109 before and after
of which tool descriptions / parameter schemas 16,051 / 33,635 (22,462 of the schemas are property descriptions)
one field-options contract repeated in propose_entity, propose_field, propose_edit_field 3,164 × 3 (6,328 duplicated)
HTML escapes (< …) 126 × 5 = 630
MCP tools/list (26 tools) 56,959 → 56,734 (the class-neutral note: −15 B × 15 propose tools)

No change was made to what the model reads:

  • The duplicated contract is the only sizeable lever. Replacing two copies with a pointer to propose_field.options would change what an MCP client sees when it loads tools one at a time (deferred tool search). It cannot be checked here without a live model.
  • The HTML escapes change wire bytes only, because the gateway decodes them before tokenizing.
  • Shorter English descriptions are a model-behaviour change and should be measured with builder-bench (live model).

Verification

  • Fixes broken on purpose, each seen red, then restored:
    • Item 1: ENTITY_NOT_FOUND branch removed, plus context.Background() put back. Red in unit and in the MCP integration test.
    • Item 2: brake disabled. Red in unit and in the integration test (step 4: 401; want 429). Caps disabled: red. Wiring pin with ProbeMax: 0: red.
    • Item 3: a write-capable field added to toolExecutor. Red.
    • Item 4: /mcp proxied to /api/v1/mcp. Red.
    • Item 5: follow effect disabled: red. Idle stop removed: red.
    • Item 7: old notes restored: red.
  • Click-through. The browser run used next dev --webpack with NEXT_PUBLIC_API_BASE=/api/v1 and its own API on a throwaway DB seeded by seed-demo.py. The "agent" was a plain JSON-RPC client; no model was called. Output:
    item 4: printed endpoint = http://localhost:13391/mcp
    item 4: initialize via the printed endpoint -> 200 server=nexus; tools/list -> 200, 26 tools
    item 1: propose_field on a table the tenant lacks -> {"error":"ENTITY_NOT_FOUND: entity \"vf_ghosts\" …","ok":false}
    item 5: thread open with 1 card(s)
    item 5: new card shown after 5008 ms without a reopen; cards 1 -> 2
    rep: url=http://localhost:13391/home sees the key button=false
    rep: POST /admin/mcp-tokens -> 403
    page errors: 0
    
  • Screenshots of the keys page at 1440 and 390 (ui-shots.mjs): overflow 0, page errors 0.
  • Demo-loop replay was not run locally: ai.ToolDefinitions() is unchanged (only the MCP-side note changed), and neither cassette calls propose_field. CI ran it anyway, and both the vi and en replays pass (below).

Gates (last lines)

  • gofmt -l . → empty
  • go vet ./... → ok
  • go test ./... → exit 0
  • go build ./cmd/server/ → ok
  • bash scripts/run-integration.sh -race -run '(?i)(mcp|propose|ratelimit|tool)' -timeout 50m ./internal/ai/ ./internal/mcpserver/ ./internal/handlers/ ./internal/middleware/ → run-integration: PASS=511 SKIP=0 go-test-exit=0
  • After the integration router change: -race -run 'TestMCP_' → run-integration: PASS=20 SKIP=0 go-test-exit=0
  • python3 scripts/check-orphan-endpoints.py --strict → ✅ Không có endpoint mồ côi.
  • Web:
    • npx tsc --noEmit → ok
    • npx vitest run --changed origin/main → Tests 1244 passed (1244)
    • npx eslint on the 9 touched files → ok

CI on dbedc59, before the LOW fixes (all 7 checks pass)

check result
go integration (MySQL 8, full suite, -race) pass, 33m59s
go (vet, gofmt, test -race, build, orphan gate) pass
web (build, tsc, vitest, eslint) pass
demo loop, vi cassette pass
demo loop, en cassette pass
one-command demo pass
careful guardrail pass

Verifier LOWs, fixed on this branch (48137c4, 7cf0b0f, ee988ab, 7b8217d)

  1. The note follows NewHidden (48137c4). The note after a proposal now has three effects:
    • Applies at once: access, approvals, work queues, records.
    • Created at apply but hidden from the customer until a publish: a new N-N relation, table or field.
    • Goes to drafts: an edit of a draft type.
    • TestProposedNote_FollowsTheChangeClassPerKind checks 16 kinds of envelope.
    • On the verifier's TestProbe_NotePerKind, relationship, field and entity now get the hidden-until-publish note.
  2. A follow read never replaces a message just sent (7cf0b0f).
    • The read lands through a state updater that looks at the turns as they are when it lands, and drops itself if the builder sent a turn meanwhile.
    • New tests cover:
      • the race (probe P3);
      • a hidden tab, which does not read until it is shown again;
      • the builder's own turn, which stops the re-read;
      • a late read, which never lands in another thread opened meanwhile.
    • Each test was seen red with its guard removed.
  3. The read-only pin reads every type assertion (ee988ab).
    • It parses the package and checks every type assertion and type-switch case. Any target that is not plain data must be listed with a reason: today AccessProbeCarrier, UserTokenLedger and *replayer.
    • A sample source pins each shape the old regex missed:
      • qualified: e.reader.(services.MetadataWriter);
      • pointer and chained: e.reader.(*readerWithAccessProbes).MetadataReader.(MetadataReader);
      • an alias and a type switch.
    • Method names must start with a read verb and carry no write word anywhere, so GetOrCreate, FindOrCreate and ListAndPurge fail.
  4. The one-command demo trusts Caddy's network (7b8217d).
    • docker-compose.yml fixes the network's subnet: 10.213.47.0/24 by default, NEXUS_SUBNET to change it.
    • The api gets TRUSTED_PROXY_CIDRS set to that subnet. Caddy writes X-Forwarded-For itself.
    • Evidence:
      • docker compose config renders TRUSTED_PROXY_CIDRS: 10.213.47.0/24 and subnet: 10.213.47.0/24, and both follow NEXUS_SUBNET=10.99.1.0/24.
      • A Caddy-only stack came up on 10.213.47.0/24 with Caddy at 10.213.47.2.
    • Tests:
      • Behind the proxy, a guesser no longer spends another client's budget (TestMCPRateLimit_BehindTheProxyEachClientHasItsOwnBudget).
      • TestComposeTrustsItsOwnNetwork keeps the two compose defaults equal and parseable.
    • Documented in .env.example, README.md and SECURITY.md.

Gates after the LOW fixes (7b8217d)

  • gofmt -l . → empty
  • go vet ./... → ok
  • go test ./... → exit 0
  • go build ./cmd/server/ → ok
  • run-integration.sh -race -run '(?i)(mcp|propose|ratelimit|tool)' -timeout 50m (ai, mcpserver, handlers, middleware) → run-integration: PASS=514 SKIP=0 go-test-exit=0
  • check-orphan-endpoints.py --strict → ✅ Không có endpoint mồ côi.
  • Web:
    • tsc → ok
    • vitest run --changed origin/main → Tests 1248 passed (1248)
    • eslint on the 9 touched files → ok

Not done

  • Item 6's English rewrite of the tool descriptions needs a live builder-bench run before it can land.
  • Behaviour change: in-app, propose_field on a table proposed in an earlier chat turn and not yet applied is now refused, as propose_layout already does. Within one turn, or within one MCP thread, it is accepted.

Closes #22

🤖 Generated with Claude Code

doxuta and others added 10 commits October 27, 2026 12:23
…the draft-caller sibling check (#22)

propose_field left a table that is neither live nor drafted to Apply, so an
in-app turn or an MCP token could file a card for a table of another tenant
or one that does not exist. It now answers ENTITY_NOT_FOUND, as
propose_layout and propose_records do; a table proposed earlier in the turn
or the MCP thread still takes a field.

The sibling check of a dependent picklist already reads with the caller's
context since #40, so on a delivered project it judges the builder's draft.
Nothing pinned it: a unit test with a reader that shows the draft only to a
ReadDraft Caller, in a turn and through RunTool, and an integration test over
a real /mcp on a delivered project with the builder's draft value.

The option-parity cases now name a table tenant-A has; two of them proposed
onto tenant-B's table and were buffered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MCP and the in-app builder run every tool through toolExecutor; the tool
names were pinned (read or propose_* only), but nothing stopped the executor
from gaining a dependency that writes. The pin walks what the executor is
built from, plus the probes it reaches by asserting its reader to
AccessProbeCarrier, and fails on any interface method that is not a read verb
and on any func or channel. A second test reads the package source so a new
assertion on the reader must join the walk. A third proves the pin reports a
writer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… card's size (#22)

/mcp sits outside /api/v1, so none of the API's limiters reached it: every
unauthenticated nxm_ guess cost an indexed SELECT with nothing slowing it,
and a key holder had no request budget and could grow its thread without
end, each proposal re-reading the whole thread.

middleware.MCPRateLimit sits on the /mcp route, built on the API's sliding
window. A token not yet seen working spends its client IP's lookup budget
(APIKEY_PROBE_MAX_PER_MIN, as the nxk_ brake); a token the handler answered
with a 2xx spends its own budget (DATA_RATE_LIMIT_PER_MIN, as an API key on
the data plane), so the real agents behind one address never wait on a
prober. A 401 forgets the token. Refusals are the canonical RATE_LIMITED 429.

The thread takes at most 200 turns (THREAD_FULL, reads still work) and one
proposal's row at most 256 KiB (PROPOSAL_TOO_LARGE); both refuse before
anything is written.

Tests: the brake in unit and against the real handler and token store on
MySQL; the caps in mcpserver; main.go's wiring pinned like the other brakes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every MCP propose tool, and every proposal's result, told the agent that a
human "applies it to drafts and publishes it". An access card is applied at
once, behind a confirm; relationships, approvals, work queues and records
take effect when applied too.

The result note now reads the class of the card it filed
(metaversion.ClassOf on its change envelope): a draft type goes to drafts
once the project is delivered and reaches users when published; any other
takes effect as soon as it is applied. The tool descriptions and the server
instructions say only what holds for every class: a human reviews and
applies the card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… agent (#22)

On next dev with a relative API base, mcpEndpoint() prints the dev origin
+ /mcp, and nothing served it: a contributor copied a claude mcp add line
that could not connect. The dev proxy behind app/api/v1/[...path] moves to
lib/devProxy.ts, taking the upstream path, and app/mcp uses it too (GET,
POST, DELETE: the streamable HTTP methods). Same rules as before: Origin
stripped, the answer mirrored, 404 outside development; the demo's Caddy
already routes /mcp to the API before Next.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The builder opens an MCP key's thread from Kết nối agent (MCP); when the
agent proposed again, the open thread did not change until it was reopened.

McpConnect now hands openThread the key's expiry. Until then the thread
re-reads itself on focus and every 5 s while the tab is visible, and stops
after 10 minutes with nothing new (a focus wakes it); an expired key stops
it. Read-back turns keep their m_<seq> ids, so what the builder already
applied stays applied across a re-read. A turn sent from this tab stops the
re-read, because the server's copy would rename that turn's cards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pin caught the method #23's fix added to the access probes. It is one
SELECT of the admins and operators holding the named roles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oes (#22)

Every TestMCP_ flow (scope matrix, parallel proposals, settled replay,
revocations) now runs behind the brake at its default budgets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
doxuta and others added 4 commits October 27, 2026 13:39
… and the note says so (#22)

Verifier LOW on #68: the note read only ClassOf's Kind, so a
propose_relationship card (DirectUntraced, NewHidden) was told it "takes
effect as soon as it is applied", while the customer sees a new N-N relation
only after a publish, as the Studio card's footer says. A new table or field
(Draft, NewHidden) was told it "goes to drafts", but it is created hidden.

The note now has three effects: applies at once (access, approvals, work
queues, records), created at apply and hidden from the customer until a
publish (a new document of a NewHidden type), or goes to drafts (an edit of
a draft type). Pinned per envelope kind the builder tools write.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eplaces the message (#22)

Verifier LOW on #68: the own-turn guard ran before the read. When a read was
out as the builder pressed Enter, the server copy (without the new message)
replaced the local turns and the message just sent vanished. The read now
lands through a state updater that judges the turns as they are then, and
drops itself if the builder sent a turn meanwhile.

Tests pin the race and the three guards: a hidden tab does not read and
showing it reads again, a turn of the builder's own stops the re-read, and a
late read never lands in another thread opened meanwhile. Each was seen red
with its guard removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tOrCreate (#22)

Verifier LOW on #68: the source check matched only reader.(Name), so a
package-qualified or pointer target (e.reader.(services.MetadataWriter),
e.reader.(*readerWithAccessProbes).MetadataReader.(X)), an alias or a type
switch slipped past; and Get*/Find* admitted GetOrCreate and FindOrCreate.

The check now parses the package: every type assertion and type-switch case
to anything but plain data must be listed with a reason (today
AccessProbeCarrier, UserTokenLedger, *replayer). A method name passes only
if it starts with a read verb and carries no write word anywhere in it. A
sample source pins each shape the scan must catch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rakes see clients (#22)

Verifier LOW on #68: behind Caddy every request reaches the API from Caddy's
address, and TRUSTED_PROXY_CIDRS was unset, so every per-IP brake (login,
SSO, failed nxk_ and nxm_ lookups) keyed one bucket for all clients: one
prober spent everyone's budget.

docker-compose.yml fixes the default network's subnet (10.213.47.0/24,
NEXUS_SUBNET to change it) and the api trusts X-Forwarded-For from it.
Caddy writes that header itself. Checked: docker compose config renders both,
and a Caddy-only stack came up on 10.213.47.0/24 with Caddy at 10.213.47.2.

Tests: behind the proxy a guesser no longer spends another client's budget,
and a wiring test keeps the two compose defaults equal and parseable.
Documented in .env.example, README and SECURITY.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@doxuta
doxuta merged commit 400cd5f into main Oct 27, 2026
7 checks passed
@doxuta
doxuta deleted the slice/mcp-followups branch October 27, 2026 07:27
doxuta added a commit that referenced this pull request Oct 27, 2026
…ps at the logger

#70 gave toolExecutor a *zap.Logger and AccessProbes two probes (PacksOf, AggregateScalar)
on a base without #68's read-only pin, so main fails the pin since both landed. Both probes
are SELECTs and are named as reads; the logger is a listed sink the walk does not enter,
and the catch test proves a zapcore.Core reached another way is still reported.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
doxuta added a commit that referenced this pull request Oct 27, 2026
…#72)

* feat(ai): stream completions with usage and fold the stream into one answer (#30 item 8)

The gateway asks for stream + stream_options.include_usage and folds the
event stream back into the ChatResponse the agents, the recorder and replay
already read: text and refusal text joined, tool-call arguments joined by
index, finish/stop reasons and the last usage kept. A gateway that ignores
stream and answers one JSON body is read as before. An error event, a stream
cut before it finished or a non-JSON chunk is a 502; a stall is a 504.

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

* fix(ai): a streamed tool call without arguments reads as {} (#30 item 8)

Claude streams no argument piece for a call that takes none, so the fold gave
"" and 9router refused the next call that sent it back (400 tool_use.input:
Input should be an object). A whole answer carries "{}"; the fold now does too.
Found by the first live recorded turn.

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

* refactor(ai): foldStream errors carry their package prefix; doc reflowed

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

* docs(bench): the measured cost of one app with streamed usage (#30 item 8)

One recorded app-helpdesk turn on Claude Opus 5.5 through 9router: 107,305
input tokens (179 uncached, 103,158 cache read, 3,968 cache write) and 1,779
output, about $0.08 warm and $0.34 cold at list prices. The streamed prompt
total is the whole input plus 9router's 2,000 per call; the cache split comes
from 9router's own log because its OpenAI-shape usage drops it. The env
example says calls are streamed.

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

* fix(ai): size the default daily token budget in whole-input tokens (#30 item 8)

Streamed usage moves sys_ai_runs.prompt_tokens from the uncached remainder to the
whole input, about 17x on a builder turn (measured 115,084 tokens a turn, was ~8,000).
The 200,000 default then admitted 2 builder turns a tenant a day instead of 26.
3,000,000 admits 27, pinned by a test against the measured turn. The budget is
documented in .env.example and passed through docker compose.

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

* fix(ai): a stream without its finish or its usage is a gateway error; an index-less tool call opens on a new id

[DONE] alone no longer finishes an answer (partial tool arguments were accepted), and a
stream that closes after the finish with neither its usage nor [DONE] is a 502 instead of
an answer that escapes the budget. A proxy that streams parallel tool calls without an
index gets one call per id instead of one merged call. .env.example says what happens
with a gateway that rejects stream_options.

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

* test(ai): the read-only pin names PacksOf and AggregateScalar and stops at the logger

#70 gave toolExecutor a *zap.Logger and AccessProbes two probes (PacksOf, AggregateScalar)
on a base without #68's read-only pin, so main fails the pin since both landed. Both probes
are SELECTs and are named as reads; the logger is a listed sink the walk does not enter,
and the catch test proves a zapcore.Core reached another way is still reported.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

MCP follow-ups (LOW)

1 participant