Skip to content

feat(mcp): add opt-in reference number tools - #510

Merged
alosec merged 2 commits into
mainfrom
alex/mcp-reference-number-tools
Nov 6, 2026
Merged

alosec merged 2 commits into
mainfrom
alex/mcp-reference-number-tools

Conversation

@alosec

@alosec alosec commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Why

Akshay's #452 added tools to add and remove reference numbers (PO and job numbers) on containers, shipments and tracking requests. Its write plumbing landed through the #506–#509 split, but the two reference-number tools never reached main. This PR carries just those tools onto the write kit that is now on main, so #452 can be closed. (DEV-14373)

What changes

  • New opt-in toolset, reference_numbers. It is not in the default toolsets, so the hosted server serves the same 30 tools until T49_MCP_TOOLSETS lists it.
  • add_reference_numbers (tier A) reads the list, sends the union and reads it back. A repeated call changes nothing.
  • remove_reference_numbers (tier C) needs the user's approval of a preview. The token covers the whole list, so any change after the preview returns stale_preview.
  • Both report concurrent_change_detected when the list read back differs from the one sent. Terminal49 replaces the whole list and has no conditional update, so the tool descriptions state that a number added by someone else between the read and the write is lost.
  • Server instructions: I dropped the set_party_role party_id hint. It repeats that tool's own description, and with every toolset on, the instructions otherwise run 71 bytes past Claude Code's 2 KB limit. This is the only change to default sessions besides reference_numbers appearing in whoami's toolset enum.
  • README, TOOLS_OVERVIEW and docs/mcp/home.mdx list the new toolset and count 35 tools.

The tool files and tests come from #452 unchanged. Wiring, docs and the instructions trim are new.

Testing

  • npx vp test run in packages/mcp: 70 files, 1038 tests pass. This includes feat(mcp): add reference number tools #452's unit tests and its transport test, which adds and then removes a number over the MCP client.
  • tsc --noEmit, lint (0 errors) and the format check are clean.
  • Claude.ai on staging (api-git-staging, this branch merged into staging, reference_numbers enabled for Preview/staging only), against a demo shipment. A staging API read after each step checked the result:
    • After a tools refresh, the connector lists both tools. Claude offers "Always allow" for add, but only "Needs approval" or "Blocked" for remove.
    • Add: one native approval, then ["QA-REF-1106"] on the record. Claude reported it correctly.
    • Remove, declined in the confirmation form: the record was unchanged, and Claude said so without retrying.
    • Remove, confirmed: the form showed current and proposed lists, then the record was []. The test data is gone.
    • As with feat(mcp): write safety kit, tracking lifecycle tools, and confirmed batch record writes #451, the preview text in the form is raw JSON.

🤖 Generated with Claude Code


Get evidence
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge, with the new tools remaining opt-in.

Summary

Adds two tools in the opt-in reference_numbers toolset:

  • Reference numbers can be added to containers, shipments, and tracking requests.
  • Users can remove reference numbers after approving a preview.
  • Server instructions stop repeating the party lookup hint.

The default selection remains at 30 tools. The PR adds unit and transport tests, updates the docs and feature map, and trims a server instruction.

No actionable issues were found. alosec acknowledges the read/PATCH race and raw JSON approval form in the PR description. Tests were not run during this review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Reference number call] --> B[Read current list]
  B --> C{Add or remove?}
  C -->|Add| D[Build union]
  C -->|Remove| E[Show current and proposed lists]
  E --> F[User approves]
  F --> G[Read again and check approval]
  G -->|List changed| E
  G -->|Approval matches| H[Write proposed list]
  D --> H
  H --> I[Read back and report result]
Loading

Reviews (1) · Last reviewed commit: "chore(mcp): list the reference number to..." · Reviewed by Greptile

add_reference_numbers (tier A) and remove_reference_numbers (tier C) in a
new opt-in reference_numbers toolset, ported from #452 onto the write kit
that landed in #506-#509.

Drops the set_party_role party_id hint from the server instructions: it
repeats the tool's own description, and with every toolset served the
instructions otherwise exceed Claude Code's 2 KB limit.

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

mintlify Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
terminal49 🟢 Ready View Preview Nov 6, 2026, 10:03 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@vercel

vercel Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
api Ready Ready Preview Nov 6, 2026 10:13pm UTC

Request Review

@github-actions github-actions Bot added the risk-shadow:high Shadow-only risk signal: high label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Shadow risk calibration

Signal Result Authority
Path classifier risk:high Deterministic advisory policy
heuristic fallback risk-shadow:high Shadow only

Calibration result: agreement.

Shadow risk never blocks or enables merge. Keep it in observation mode until roughly 50 pull requests have human-reviewed labels, then calibrate before considering any policy use.

@github-actions github-actions Bot added the risk:unknown Advisory evidence unavailable or changed; no merge permission label Nov 6, 2026
@blacksmith-sh

This comment has been minimized.

@github-actions github-actions Bot added risk:high Advisory path risk; current-head human review needed and removed risk:unknown Advisory evidence unavailable or changed; no merge permission labels Nov 6, 2026
…e map

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added risk:unknown Advisory evidence unavailable or changed; no merge permission and removed risk:high Advisory path risk; current-head human review needed labels Nov 6, 2026
@github-actions github-actions Bot added risk:high Advisory path risk; current-head human review needed and removed risk:unknown Advisory evidence unavailable or changed; no merge permission labels Nov 6, 2026
@alosec
alosec marked this pull request as ready for review November 6, 2026 22:18
@alosec
alosec merged commit dcb10da into main Nov 6, 2026
30 checks passed
@alosec
alosec deleted the alex/mcp-reference-number-tools branch November 6, 2026 22:18
@github-actions github-actions Bot added risk:unknown Advisory evidence unavailable or changed; no merge permission and removed risk:high Advisory path risk; current-head human review needed labels Nov 6, 2026

This branch was successfully deployed

2 active (1 outdated) deployments
Preview — c1d82f65 Deployed Nov 6, 2026 by vercel[bot]
staging - docs — 53020de6 Deployed Nov 6, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:unknown Advisory evidence unavailable or changed; no merge permission risk-shadow:high Shadow-only risk signal: high

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant