@nexusm/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 10CG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# nexusm-mcp-server
+
+Nexusm MCP Server — generic MCP server exposing Nexusm core capabilities (memory, conversation, knowledge, feedback, context) to MCP clients via `@modelcontextprotocol/sdk` stdio + Streamable HTTP transports.
+
+Published to npm as **`@nexusm/mcp-server`**.
+
+> Tracked in Nexusm main repo: [`packages/nexusm-mcp-server`](https://forgejo.10cg.pub/10CG/nexus/src/branch/main/packages/nexusm-mcp-server) (US-037 v7.0).
+
+## Status
+
+**Wave 2 done (2026-05-22)**: 4 tools fully wired to `@nexusm/sdk` (context_retrieve / memory_search / memory_create / memory_feedback) + full §M-3 HTTP→MCP error mapping (`mapHttpStatusToMcpError` + 2 new error codes Unauthorized/RateLimited) + Prometheus metrics with cardinality guard + cross-substory + E2E + schema_sync integration tests. Wave 3 (nexus-claude-plugin Anthropic marketplace) pending — see [proposal](https://forgejo.10cg.pub/10CG/nexus/src/branch/main/openspec/changes/us-037-mcp-server-exposure/proposal.md).
+
+**Known Wave 2 limitations**: (1) CI red until Gate-1 — `@nexusm/sdk@1.3.0` npm publish pending (user action; SDK rename merged at `1fbdd69` in `nexus-sdk-js` main); (2) integration tests env-gated (require `NEXUS_TEST_API_URL/TOKEN/TENANT_ID` Forgejo secrets, currently dormant); (3) Python backend `mcp.py` metrics defined but emit-site wiring deferred to Wave 3 (FU-MCP-BACKEND-EMIT-WIRING); (4) HTTP transport per-request `server.connect()` is scaffold-only — Wave 3 entry condition (FU-MCP-HTTP-SESSION) before plugin TASK-019 E2E runs.

package/RUNBOOK.md

@@ -0,0 +1,190 @@
+# nexusm-mcp-server RUNBOOK
+
+> **Status**: in place at `packages/nexusm-mcp-server/RUNBOOK.md`; moved into this submodule at Wave 0 close (2026-05-21).
+> **Owner**: 10CG Backend / DevOps
+> **Created**: 2026-05-09 (US-037 Phase B Wave 0)
+> **Last revised**: 2026-05-22 (Wave 1 R1 audit amendments — removed `description-clean` row from §5 until Wave 2 CI matrix expansion)
+> **Related**: [proposal.md §C-5](https://forgejo.10cg.pub/10CG/nexus/src/branch/main/openspec/changes/us-037-mcp-server-exposure/proposal.md) + [detailed-tasks.yaml TASK-002 / TASK-008](https://forgejo.10cg.pub/10CG/nexus/src/branch/main/openspec/changes/us-037-mcp-server-exposure/detailed-tasks.yaml)
+
+---
+
+## 1. npm publish Failure Modes
+
+### 1.1 Rate Limited (HTTP 429)
+
+**Symptom**: `npm publish` fails with `429 Too Many Requests`.
+
+**Cause**: npm registry has anti-abuse rate limits per token.
+
+**Recovery**:
+1. Wait 5-10 min before retry.
+2. If persistent (> 30 min), check npm status page: https://status.npmjs.org/
+3. Workaround: use `--registry https://registry.npmjs.org/` (force public, sometimes mirrors lag).
+
+**Avoid**: Don't retry in tight loop — will trigger longer ban.
+
+---
+
+### 1.2 Token Expired / Unauthorized (HTTP 401)
+
+**Symptom**: `npm publish` fails with `401 Unauthorized` or `EAUTHIP`.
+
+**Cause**: `NPM_TOKEN` granular access token expired (max 90-day lifetime since 2025 npm policy) or revoked.
+
+**Recovery**:
+1. Login to npmjs.com with org account.
+2. Profile → Access Tokens → Granular Access Tokens → "Generate New Token". Configure:
+   - Bypass 2FA: ✅ (required for CI automation)
+   - Organizations → `nexusm` → Read and write
+   - Expiration: 90 days (max)
+3. Update Forgejo repo secret (note: `PUT` method + `/actions/secrets/` path):
+   ```bash
+   forgejo PUT /repos/10CG/nexusm-mcp-server/actions/secrets/NPM_TOKEN -d '{"data":"<new-token>"}'
+   ```
+4. Re-run failed CI workflow (Forgejo Actions → re-run).
+
+**Rotation cadence**: Quarterly (Jan / Apr / Jul / Oct, 1st Monday) — required because npm granular tokens cap at 90 days. Schedule in calendar.
+
+---
+
+### 1.3 Namespace Not Registered / Forbidden (HTTP 403)
+
+**Symptom**: `npm publish` fails with `403 Forbidden — You do not have permission to publish "@nexusm/mcp-server"`.
+
+**Cause**: `@nexusm` scoped namespace not registered to org account, or token doesn't have publish scope on this namespace.
+
+**Recovery**:
+1. Verify namespace ownership: `npm access ls-packages @nexusm`.
+2. If namespace not owned, register via npmjs.com → "Add Organization" → name: `nexusm`, type: Free Open Source.
+3. Re-link granular access token to org: Profile → Access Tokens → edit token → Organizations → `nexusm` → Read and write.
+4. Retry publish.
+
+**Long-term safeguard**: `@nexusm` scope is owned by 10CG since 2026-05-21 (Wave 0 closure). The original A2-D-1 unscoped fallback (`nexus-mcp-server`) is no longer available — that name is taken on npm by an unrelated party. If `@nexusm` is ever lost, immediately reclaim via npmjs.com support; do NOT fall back to unscoped.
+
+---
+
+### 1.4 Disaster Recovery: Bad Version Published
+
+**Symptom**: Critical bug shipped in `0.x.y`, users hitting it.
+
+**Recovery options** (in priority order):
+
+1. **Hotfix `0.x.(y+1)`** (preferred): bump patch, fix bug, publish. Existing users get update via npm update.
+2. **`npm deprecate @nexusm/mcp-server@0.x.y "reason"`**: marks version as deprecated; users see warning on install but version stays available.
+3. **`npm unpublish @nexusm/mcp-server@0.x.y --force`**: removes from registry. **DANGEROUS** — only allowed within 72h of publish per npm policy. Will break any user who has it pinned.
+
+**Decision matrix**:
+| Severity | Action |
+|----------|--------|
+| Cosmetic / non-functional bug | Hotfix `0.x.(y+1)` |
+| Security vuln (CVE level) | Hotfix + deprecate `0.x.y` |
+| Critical breakage (data loss / DoS) | Hotfix + deprecate; consider unpublish if < 24h |
+| Wrong file shipped (e.g., secret in tarball) | Unpublish IMMEDIATELY (within 72h window) + rotate any leaked credentials |
+
+**Reference**: https://docs.npmjs.com/policies/unpublish
+
+---
+
+## 2. NPM_TOKEN Rotation
+
+### Schedule
+
+- **Quarterly**: Jan / Apr / Jul / Oct (1st Monday) — required because npm granular tokens cap at 90 days
+- **Ad-hoc**: when leak suspected, when team member leaves, when 90-day expiration ≤ 2 weeks away
+
+### Procedure
+
+1. Generate new granular access token (npmjs.com → Profile → Access Tokens → Granular Access Tokens → "Generate New Token"). Settings:
+   - Bypass 2FA: ✅
+   - Organizations → `nexusm` → Read and write
+   - Expiration: 90 days
+2. Test new token locally:
+   ```bash
+   NPM_TOKEN=<new> npm whoami --registry https://registry.npmjs.org/
+   ```
+3. Update Forgejo repo secret (PUT + `/actions/secrets/`):
+   ```bash
+   forgejo PUT /repos/10CG/nexusm-mcp-server/actions/secrets/NPM_TOKEN -d '{"data":"<new>"}'
+   ```
+4. Trigger a no-op CI run (push empty commit) to verify CI auth works with new token.
+5. Revoke old token (npmjs.com → Access Tokens → Delete).
+6. Update calendar reminder for next rotation (+3 months).
+
+### Audit Trail
+
+Log each rotation in `nexusm-mcp-server/CHANGELOG.md` under `## Operations`:
+```
+- 2026-04-XX: NPM_TOKEN rotated (rotated_by=<name>, old_token_revoked=2026-04-XX)
+```
+
+---
+
+## 3. Disaster Recovery — Forgejo Repo Loss
+
+### Scenario: `10CG/nexusm-mcp-server` Forgejo repo deleted / corrupted
+
+**Recovery**:
+
+1. **Local clones still have full history** — any team member with a local clone can restore.
+2. Rebuild from local:
+   ```bash
+   # In team member's local clone:
+   git remote rename origin forgejo-old   # save old remote ref just in case
+   forgejo POST /orgs/10CG/repos -d '{"name":"nexusm-mcp-server",...}'
+   git remote add origin ssh://forgejo@forgejo.10cg.pub/10CG/nexusm-mcp-server.git
+   git push -u origin main --tags
+   ```
+3. Re-add Forgejo Actions secrets (NPM_TOKEN) per §2.
+4. Update main nexus repo `.gitmodules` if URL changed.
+5. Notify all submodule consumers to re-init: `git submodule update --init`.
+
+### Scenario: GitHub mirror (`simonfishgit/nexus-claude-plugin`) lost
+
+GitHub mirror is auto-synced from Forgejo via `.forgejo/workflows/mirror.yml` (TASK-024). If mirror disappears:
+
+1. Recreate GitHub repo (any team member with PAT).
+2. Re-add `GITHUB_PAT` secret in Forgejo `nexus-claude-plugin` repo.
+3. Push current Forgejo HEAD: `git push github main`.
+
+This is the Anthropic marketplace submission path (`plugin.json author=10CG`, mirror is just for discovery via simonfishgit).
+
+---
+
+## 4. Namespace Ownership
+
+- npm: `@nexusm/*` scoped namespace owned by 10CG organization account on npmjs.com.
+- Forgejo: `10CG/nexusm-mcp-server` repo, admin = 10CG org admins.
+- GitHub mirror: `simonfishgit/nexus-claude-plugin` (personal account, bus factor mitigation via Forgejo Actions auto-sync per A2-D-3).
+
+If 10CG npm org access lost (admin departure / account compromise):
+1. Contact npm support (support@npmjs.com) with org admin proof.
+2. Worst case: fallback to unscoped `nexusm-mcp-server` package, update all references (proposal A2-D-1 fallback).
+
+---
+
+## 5. CI Workflow Reference
+
+`.forgejo/workflows/ci.yml` (TASK-008 / TASK-017 / TASK-025):
+
+| Step | Trigger | Purpose | Failure → Action |
+|------|---------|---------|-----------------|
+| `lint` | push, PR | eslint + prettier | Fix code style; check `.eslintrc` |
+| `tsc` | push, PR | TypeScript type-check | Fix type errors; SDK Zod schema drift may indicate need to bump @nexusm/sdk |
+| `test:unit` | push, PR | vitest unit tests | Local repro: `npm test` |
+| `test:integration` | push, PR | mcp-cli E2E (3 platform matrix Linux × Node 18/20 + macOS × Node 20) | Check matrix log; Aether runner Windows OOS Phase 1 |
+| `schema_sync` | push, PR | MCP inputSchema vs @nexusm/sdk Zod schema | Update one or the other to match |
+| `publish` | tag `v*` | npm publish + Forgejo release | Per §1 failure modes |
+
+> **Wave 1 caveat (2026-05-22)**: Only `lint` + `tsc` (build) are currently implemented in `.forgejo/workflows/ci.yml`. `test:unit` / `test:integration` / `schema_sync` / `publish` are planned for Wave 2 TASK-014 (test matrix) and Wave 4 TASK-026 (publish). A `description-clean` step (grep `R[0-9]+|C-[0-9]+|M-[0-9]+` audit-marker leakage in `src/tools/*.ts` `description:` fields) was originally listed but deferred — for Wave 1 it is enforced via PR code review (R1 audit caught + fixed 2 leaks 2026-05-22).
+
+---
+
+## 6. Operations Log
+
+(to be appended chronologically)
+
+```
+2026-XX-XX  Initial repo created by <ops>; NPM_TOKEN automation token configured
+2026-XX-XX  Phase B Wave 1 first commit (TASK-003 MCP scaffold)
+...
+```

package/dist/auth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Auth / env config loader for Nexusm MCP server (US-037b).
+ *
+ * Loads required env vars on startup and fails fast if any is missing.
+ *
+ * Per R2 C-1 (proposal §283): `NEXUS_USER_ID` is intentionally NOT loaded
+ * here — `user_id` is supplied per-call via MCP tool input args.
+ *
+ * SECURITY:
+ *   - The Bearer token (NEXUS_API_TOKEN) MUST NEVER appear in stdout
+ *     (would pollute MCP stdio transport, breaking the client),
+ *     nor in stderr error messages, nor in any log line.
+ *   - All diagnostic output uses env var *names* only, never values.
+ */
+/**
+ * Loaded, validated auth configuration.
+ *
+ * Exported as a named interface so downstream modules (notably
+ * `errors.ts` per TASK-007 / TASK-013) can import the contract
+ * without re-declaring it.
+ */
+export interface AuthConfig {
+    /** Base URL of the Nexus HTTP API (no trailing slash enforced). */
+    readonly apiUrl: string;
+    /** Bearer token for Nexus API. NEVER log this value. */
+    readonly apiToken: string;
+    /** Tenant identifier for multi-tenant routing. */
+    readonly tenantId: string;
+}
+/**
+ * Stream sink for diagnostics. Injectable for testing only; defaults to
+ * `process.stderr` so that no diagnostic ever lands on stdout (which is
+ * reserved for the MCP stdio transport).
+ */
+export interface AuthIO {
+    stderr: NodeJS.WritableStream;
+    exit: (code: number) => never;
+}
+/**
+ * Load and validate auth config from `process.env`.
+ *
+ * On any missing required var, writes a clear, token-free error message to
+ * `stderr` and calls `process.exit(1)`. Empty string and whitespace-only
+ * values are treated as missing (env var inheritance from parent shells
+ * frequently produces empty values, which would otherwise produce a
+ * confusing "401 Unauthorized" downstream).
+ */
+export declare function loadAuthConfig(env?: NodeJS.ProcessEnv, io?: AuthIO): AuthConfig;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAC/B;AAQD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,EAAE,GAAE,MAAkB,GACrB,UAAU,CAiCZ"}

package/dist/auth.js

@@ -0,0 +1,62 @@
+/**
+ * Auth / env config loader for Nexusm MCP server (US-037b).
+ *
+ * Loads required env vars on startup and fails fast if any is missing.
+ *
+ * Per R2 C-1 (proposal §283): `NEXUS_USER_ID` is intentionally NOT loaded
+ * here — `user_id` is supplied per-call via MCP tool input args.
+ *
+ * SECURITY:
+ *   - The Bearer token (NEXUS_API_TOKEN) MUST NEVER appear in stdout
+ *     (would pollute MCP stdio transport, breaking the client),
+ *     nor in stderr error messages, nor in any log line.
+ *   - All diagnostic output uses env var *names* only, never values.
+ */
+/** Required env var keys. Order is preserved when reporting missing vars. */
+const REQUIRED_ENV_VARS = ['NEXUS_API_URL', 'NEXUS_API_TOKEN', 'NEXUS_TENANT_ID'];
+const defaultIO = {
+    stderr: process.stderr,
+    // Cast: process.exit is typed as `(code?) => never` but TS sometimes widens.
+    exit: ((code) => process.exit(code)),
+};
+/**
+ * Load and validate auth config from `process.env`.
+ *
+ * On any missing required var, writes a clear, token-free error message to
+ * `stderr` and calls `process.exit(1)`. Empty string and whitespace-only
+ * values are treated as missing (env var inheritance from parent shells
+ * frequently produces empty values, which would otherwise produce a
+ * confusing "401 Unauthorized" downstream).
+ */
+export function loadAuthConfig(env = process.env, io = defaultIO) {
+    const missing = [];
+    const values = {};
+    for (const key of REQUIRED_ENV_VARS) {
+        const raw = env[key];
+        if (raw === undefined || raw.trim() === '') {
+            missing.push(key);
+        }
+        else {
+            values[key] = raw.trim();
+        }
+    }
+    if (missing.length > 0) {
+        // Build message from var *names* only — never values. This guarantees
+        // a leaked token cannot reach stderr via this path even if a future
+        // refactor accidentally passes `env` into the message.
+        const list = missing.join(', ');
+        const noun = missing.length === 1 ? 'variable is' : 'variables are';
+        const msg = `[nexusm-mcp-server] Required environment ${noun} missing: ${list}. ` +
+            `Set them before starting the server. See RUNBOOK.md.\n`;
+        io.stderr.write(msg);
+        io.exit(1);
+        // `exit` is typed `never`; unreachable, but satisfies control-flow analysis.
+        throw new Error('unreachable');
+    }
+    return {
+        apiUrl: values.NEXUS_API_URL,
+        apiToken: values.NEXUS_API_TOKEN,
+        tenantId: values.NEXUS_TENANT_ID,
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6EAA6E;AAC7E,MAAM,iBAAiB,GAAG,CAAC,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,CAAU,CAAC;AA8B3F,MAAM,SAAS,GAAW;IACxB,MAAM,EAAE,OAAO,CAAC,MAAM;IACtB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAA4B;CACxE,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAyB,OAAO,CAAC,GAAG,EACpC,KAAa,SAAS;IAEtB,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,MAAM,MAAM,GAA4C,EAAE,CAAC;IAE3D,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3C,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,sEAAsE;QACtE,oEAAoE;QACpE,uDAAuD;QACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC;QACpE,MAAM,GAAG,GACP,4CAA4C,IAAI,aAAa,IAAI,IAAI;YACrE,wDAAwD,CAAC;QAC3D,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACX,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACjC,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,aAAuB;QACtC,QAAQ,EAAE,MAAM,CAAC,eAAyB;QAC1C,QAAQ,EAAE,MAAM,CAAC,eAAyB;KAC3C,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Error contract and HTTP→MCP mapping for the Nexusm MCP server.
+ *
+ * Wave 1 (TASK-007): declared the type surface — NexusError, McpErrorCode,
+ *   interface stubs for AuthError / NetworkError / CancelError.
+ * Wave 2B (TASK-013): implements the full HTTP-status → MCP-error-code
+ *   mapping (proposal §M-3) via `mapHttpStatusToMcpError` and
+ *   `isAxiosLikeError`.
+ *
+ * SECURITY (matches auth.ts discipline):
+ *   `toJSON()` deliberately omits `cause` and `stack`. An axios-style error
+ *   attached as `cause` typically carries the original request config
+ *   including the `Authorization: Bearer <token>` header. Leaking that via a
+ *   JSON.stringify of a NexusError would defeat the token-redaction guarantee
+ *   of auth.ts. If callers need to inspect the cause they must do so
+ *   explicitly, not via serialization.
+ */
+import type { AuthConfig } from './auth.js';
+/**
+ * MCP / JSON-RPC error codes surfaced by this server.
+ *
+ * Values mirror `@modelcontextprotocol/sdk` `ErrorCode` enum
+ * (`dist/esm/types.d.ts`). We re-declare locally rather than re-export
+ * the SDK enum so that:
+ *   1. errors.ts has zero runtime import from the SDK (keeps the
+ *      contract layer independent of SDK version churn)
+ *   2. TASK-013's mapping logic and tests have a single source of truth
+ *      for which codes this server is allowed to emit
+ *
+ * Scope decision (resolved ambiguity from spec):
+ *   We enumerate the four JSON-RPC standard codes required by §M-3
+ *   (`InvalidRequest`, `MethodNotFound`, `InvalidParams`, `InternalError`),
+ *   plus `ParseError` (-32700) for completeness of the JSON-RPC base
+ *   set, plus `ConnectionClosed` (-32000) and `RequestTimeout` (-32001)
+ *   which the SDK defines and which `NetworkError` / `CancelError`
+ *   downstream mappings will need. UrlElicitationRequired (-32042) is
+ *   intentionally omitted — not in scope for Wave 1 / Wave 2.
+ */
+export declare enum McpErrorCode {
+    ParseError = -32700,
+    InvalidRequest = -32600,
+    MethodNotFound = -32601,
+    InvalidParams = -32602,
+    InternalError = -32603,
+    ConnectionClosed = -32000,
+    RequestTimeout = -32001,
+    /**
+     * TASK-013 additions: custom codes in the application-defined range
+     * (-32099..-32000 is reserved for implementation; we use the next
+     * available slots above -32000 for semantic clarity).
+     *
+     * Unauthorized (-32011): 401 / 403 from Nexus REST — semantically distinct
+     *   from InvalidRequest (-32600) so clients can detect auth failures without
+     *   parsing the message string.
+     * RateLimited (-32012): 429 Retry-After. Clients should honor
+     *   `data.retry_after_seconds` before retrying.
+     */
+    Unauthorized = -32011,
+    RateLimited = -32012
+}
+/**
+ * Base error for all errors this MCP server emits.
+ *
+ * Carries enough structured context to translate a thrown `NexusError` into a
+ * JSON-RPC error response without re-inspecting the underlying axios / SDK
+ * error.
+ */
+export declare class NexusError extends Error {
+    /**
+     * Upstream HTTP status (Nexus REST), or `null` when the error did not
+     * originate from an HTTP response (e.g. DNS failure, abort, internal
+     * invariant violation).
+     */
+    readonly httpStatus: number | null;
+    /** MCP/JSON-RPC error code that this error will surface as. */
+    readonly mcpErrorCode: McpErrorCode;
+    /**
+     * Whether the MCP client may safely retry this request.
+     * Populated by `mapHttpStatusToMcpError` and the NLI/network helpers.
+     */
+    readonly retryable: boolean;
+    /**
+     * Additional structured data surfaced in the JSON-RPC `error.data` field.
+     * Safe to serialize — must never contain auth tokens or raw SDK internals.
+     * Populated by the mapping layer (e.g. `retry_after_seconds`, `network`,
+     * `timeout`).
+     */
+    readonly data?: Record<string, unknown>;
+    /**
+     * Underlying cause. Per ES2022 `Error.cause`. **Not serialized** by
+     * `toJSON()` — see file header SECURITY note.
+     */
+    readonly cause?: unknown;
+    constructor(message: string, mcpErrorCode: McpErrorCode, httpStatus?: number | null, cause?: unknown, options?: {
+        retryable?: boolean;
+        data?: Record<string, unknown>;
+    });
+    /**
+     * Safe serialization. Deliberately omits `cause` and `stack` to
+     * prevent accidental token leakage if a caller logs the JSON form.
+     *
+     * `data` IS included — it is caller-controlled structured metadata that
+     * must never contain raw SDK objects (that would be caught during review
+     * of `mapHttpStatusToMcpError` callers).
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        httpStatus: number | null;
+        mcpErrorCode: McpErrorCode;
+        data?: Record<string, unknown>;
+    };
+}
+/**
+ * Canonical type for a function that maps an HTTP status + response body to
+ * a `McpErrorCode`. `headers` is optional — only needed for 429 Retry-After
+ * extraction. This type is the public contract; the concrete implementation
+ * is `mapHttpStatusToMcpError`.
+ */
+export type ErrorMapping = (httpStatus: number | null, body: unknown, headers?: Record<string, string | string[] | undefined>) => NexusError;
+/**
+ * Shape of an axios-like error thrown by `@nexusm/sdk`.
+ * We cannot import axios types here (would add a hard dep); instead we use
+ * structural duck-typing checked by `isAxiosLikeError`.
+ */
+interface AxiosLikeError {
+    isAxiosError: true;
+    message: string;
+    response?: {
+        status: number;
+        data?: unknown;
+        headers?: Record<string, string | string[] | undefined>;
+    };
+    code?: string;
+}
+/**
+ * Type guard for axios-compatible errors thrown by `@nexusm/sdk`.
+ *
+ * Matches any object with `isAxiosError === true`, which is the canonical
+ * axios duck-type flag. This guard intentionally does NOT import axios — it
+ * keeps `errors.ts` free of SDK runtime dependencies.
+ */
+export declare function isAxiosLikeError(err: unknown): err is AxiosLikeError;
+/**
+ * Canonical entrypoint for converting an upstream HTTP response (or SDK
+ * network/timeout error) into a typed `NexusError` with the correct
+ * `McpErrorCode`, `retryable` flag, and `data` extras.
+ *
+ * Proposal §M-3 mapping table:
+ *
+ * | httpStatus              | McpErrorCode      | retryable | data extras              |
+ * |-------------------------|-------------------|-----------|--------------------------|
+ * | 401, 403                | Unauthorized      | false     | —                        |
+ * | 404                     | MethodNotFound    | false     | —                        |
+ * | 422                     | InvalidParams     | false     | —                        |
+ * | 429                     | RateLimited       | true*     | retry_after_seconds?: n  |
+ * | 503                     | ConnectionClosed  | true      | —                        |
+ * | 5xx (else)              | InternalError     | true      | —                        |
+ * | null + network=true     | InternalError     | true      | network: true            |
+ * | null + timeout=true     | RequestTimeout    | true      | timeout: true            |
+ *
+ * *429: retryable "after Retry-After header elapses" — we set retryable=true
+ *  and populate `data.retry_after_seconds` so clients can honour the window.
+ *
+ * Note: HTTP 200 + body.errors != null is NOT an error; that is the
+ * partial-degradation path handled in tool handlers (see context.ts). This
+ * function is only invoked on non-2xx responses or SDK error throws.
+ *
+ * @param httpStatus  HTTP status code, or `null` for non-HTTP errors.
+ * @param body        Raw response body (typed `unknown`; we do not parse it).
+ * @param headers     Response headers, used only to extract Retry-After on 429.
+ */
+export declare function mapHttpStatusToMcpError(httpStatus: number | null, body: unknown, headers?: Record<string, string | string[] | undefined>): NexusError;
+/**
+ * Auth-origin error (401 / 403 from Nexus REST, or local auth-config
+ * issues surfaced after `loadAuthConfig`).
+ *
+ * `authConfigKey` is optional because not every auth failure points at
+ * a specific config field (e.g. a token that was valid at load but
+ * since revoked has no `AuthConfig` key to blame).
+ */
+export interface AuthError extends NexusError {
+    readonly authConfigKey?: keyof AuthConfig;
+}
+/**
+ * Network-origin error (DNS failure, connection refused, TLS error,
+ * read timeout). Per proposal §M-3, these map to `InternalError` with
+ * `error.data.network = true`, and the MCP client may retry.
+ *
+ * `retryable` is a hint to the client; the server itself does not
+ * retry (avoids double-counting under quota / Retry-After).
+ */
+export interface NetworkError extends NexusError {
+    readonly retryable: boolean;
+}
+/**
+ * Cancellation error — fired when an in-flight tool call is aborted.
+ *
+ *   - `client_cancel`: MCP cancel notification from the client
+ *   - `timeout`: server-side deadline elapsed
+ *   - `signal`: AbortSignal propagated from a higher layer
+ *
+ * Per proposal §M-3, the server does **not** return a result when a
+ * cancel arrives; this error type exists so handlers can distinguish
+ * cancel from other failures in logs / metrics.
+ */
+export interface CancelError extends NexusError {
+    readonly reason: 'client_cancel' | 'timeout' | 'signal';
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}