feat(mcp): whoami tool and GET /me contract (SDK client.me())

[dodeja]

Summary

Adds an identity call across the three things this repo ships, backed by a new backend endpoint:

• OpenAPI: GET /me under a new Account tag, with credential, credential_account, credential_user, and feature_availability schemas plus an API reference page. The endpoint itself is implemented in Terminal49/t49#4322; this spec is the contract.
• SDK: client.me(). Mapped format returns a CurrentCredential: kind (api_key | user), channel, key label, the scoped account, the signed-in user or null, the accounts that user can switch to, and the feature map.
• MCP 1.2.0: whoami tool (no inputs, read-only). Reports the account (company name, business type, plan, location, tracking slots), the user, other accounts, and per-feature status: available, requires_paid_plan, requires_user_credential, not_enabled. Server instructions tell the agent to call it when the user asks which account is connected, when a lookup returns nothing or 401, or before a gated feature.

Commits are split docs / SDK / MCP / MCP docs / smoke-check fix for review. The Postman collection commit is the repo's auto-generation bot reacting to the OpenAPI change; it includes the new /me request.

Contract decisions (please review)

• One endpoint and one tool rather than separate user and account calls; every consumer wants both halves at once, and an API key has no user.
• Resource type is credential with kind taken from the backend's existing ApiAuth::Context#auth_type, and channel from #channel (api, dashboard, mcp, askt49). No new vocabulary was invented.
• Feature statuses are derived from the gates that already enforce each feature (ApiAuth rules, Account#permissions, account flags), not from a new permissions model.
• Scope is deliberately narrow: stored fields only. No phone, sign-in history, notification settings, onboarding state, billing detail, or shipment-history profiling. A computed account profile (lanes, carriers, commodities) is a separate future decision.

Dependencies and rollout

• Requires Terminal49/t49#4322 to be deployed before the whoami tool returns data in production. Until then the tool returns the standard Terminal49 error.
• Changing the tool list re-triggers directory review for the ChatGPT app and the Claude connector; both listing files are updated here.
• No merge, release, deploy, or customer activation is requested by this PR.

Verification

Head cd9c0396ad74df3fc95a5a9d057bae3a9de89ccc. The earlier head b134e004a1 ran CI and failed only the MCP protocol matrix, because the stdio and preview smoke scripts hard-code the tool count (13). That is fixed in the last commit; CI for this head is linked from the checks tab.

Local, on this head's tree:

• vp run check: 0 errors (lint, SDK build, API and workspace type checks)
• @terminal49/sdk tests: 251 passed, 1 skipped (pre-existing live smoke)
• @terminal49/mcp tests: 398 passed across 23 files
• npm run build: SDK, MCP, CLI build clean
• MCP_PROTOCOL_VERSION=2026-07-28 and 2024-10-07 protocol smokes against the built server: 14 tools listed
• generate:filters: no diff; generate:types and SDK reference docs regenerated and committed

Validation limitations (not covered by CI)

• CI does not run Spectral at all, and the repo's .spectral.mjs imports a Stoplight-hosted ruleset that now returns 404, so the documented spectral lint command fails before reading the spec. As a substitute I linted with Spectral's built-in spectral:oas ruleset: the finding set is identical for origin/main and this branch (68 problems, 29 of them pre-existing oas3-valid-media-example and path-params errors elsewhere in the spec; none on /me or the new schemas). Repointing .spectral.mjs is a separate tooling decision because it would surface those 29 pre-existing errors.
• The preview HTTP protocol smoke needs a deployed preview URL and token; it runs in CI only.

Reviewers

Needs a human review of the public contract (OpenAPI shape and field names) in addition to CI, since this adds a public endpoint and an MCP tool.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR appears safe to merge, with two non-blocking improvements to the new public contract.

Findings

1.  Account selector is missing ▶
2.  Contract permits incomplete identity ▶

Fix with agent prompt

### Issue 1
docs/openapi.json:13907
`GET /me` documents account selection through `x-account-id`, but `parameters: []` leaves that header out of the public contract. The generated `get-me` type consequently has `header?: never`. Callers cannot select another account through its generated header parameters and must add the header separately.

Declare the optional header and regenerate the types and Postman collection.

### Issue 2
docs/openapi.json:13915-13917
The response contract allows `included` and `relationships.account.data` to be absent, but `mapCurrentCredential` needs them to return complete identity data. If the server omits account linkage, the mapper throws at `resource.id`. If it returns linkage without the included account, the mapper returns `companyName: undefined`, although the SDK and `whoami` require a string.

Make the contract guarantee the referenced account and user resources. Add missing-resource tests so the mapper cannot silently return incomplete identity data.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds an identity call across the public API contract, SDK, and MCP server.

• GET /me describes the credential, account, user, and feature access.
• TypeScript callers can fetch the current credential with client.me().
• MCP callers can ask which account and features are connected.

Acknowledged by dodeja: the backend endpoint must deploy before production identity calls succeed. The broken Spectral ruleset is explicitly deferred as a separate tooling change.

Diagram

sequenceDiagram
  participant Caller
  participant MCP as MCP whoami
  participant SDK as SDK client.me
  participant API as Terminal49 API
  Caller->>MCP: whoami()
  MCP->>SDK: me(format mapped)
  SDK->>API: GET /me with credential and account headers
  API-->>SDK: Credential and included account/user resources
  SDK-->>MCP: CurrentCredential
  MCP-->>Caller: Account, user, other accounts, feature statuses

Loading

_{Reviews (1) · Last reviewed commit: "fix(mcp): expect 14 tools in the protoco..." · Reviewed by Greptile}

Current readiness verification keeps the original gates. Local checks and tests pass, but authenticated MCP preview evaluation is blocked by a backend HTTP 401 for the shared CI passthrough credential. The transport handshake alone does not prove tool access. Review fixes and rebases preserve this PR's base topology. No merge or deploy has been performed.

[mintlify]

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

Project	Status	Preview	Updated
terminal49	🟢 Ready	View Preview	Oct 14, 2026, 5:05 PM

[vercel]

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

Project	Deployment	Actions	Updated
api	Ready	Preview	Oct 14, 2026 5:06pm UTC

[dodeja]

CI status on head cd9c0396ad74df3fc95a5a9d057bae3a9de89ccc (run 38016243702):

• Passing: Vite+ monorepo check, sdk (20/22/24), cli (20/22/24), mcp, sdk-tooling, MCP protocol matrix (all six versions), MCP preview 2025-11-25, claude-review, Mintlify link-rot, Vercel.
• Failing: MCP preview 2026-07-28, at the "Eval MCP tools against Vercel preview" step only. The handshake and tools/list against this commit's Vercel preview passed (14 tools). The eval fails during fixture discovery: found no shipmentId, containerId, containerNumber on this account, so it cannot exercise the detail tools. The same error failed codex/coverage-feature-matrix earlier today (run 37982920011), so it is the eval account's data, not this change. Re-running the job reproduced it. Fixing it means giving the eval account tracked shipments or setting MCP_EVAL_ALLOW_SPARSE=1 in the workflow; both are outside this PR's scope and left for a maintainer decision.
• main has no required status checks configured, so nothing here is formally blocking; treat the list above as the evidence.

Not covered by CI: Spectral/OpenAPI lint (see the PR description for the local spectral:oas comparison, identical to origin/main). Reviewers maurycy and namitabhasin are requested; this stays a draft with no merge, release, or deploy requested.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-14T17:08:11.703222Z	2b92e62	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd9c0396ad

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e27934e44

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dodeja]

Rebased onto main (90b90c6), no conflicts. Head 539408d is the Postman bot's [skip ci] commit on top of 2b92e62, so the code CI for this head is run 38603562696 on 2b92e62:

• Passing: Vite+ monorepo check, sdk (20/22/24), cli (20/22/24), mcp, sdk-tooling, MCP protocol 2024-10-07 through 2026-07-28, MCP preview 2025-11-25, Claude Code Review.
• Failing, both pre-existing: Coverage generators and drift checks fails identically on main since test(coverage): verify deployed downloads and agent references #430; MCP preview 2026-07-28 fails on every open PR branch (eval fixture discovery against the preview deployment errors on list_shipments), unrelated to this change.

Local on 2b92e62: vp run check and vp lint exit 0; vp run test 678 tests passed across the SDK, MCP, and CLI packages.