fa-mcp-sdk 0.11.10 → 0.11.12

package/cli-template/.env.example

@@ -1,48 +1,48 @@
-# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
-SERVICE_NAME={{project.name}}
-# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
-# PRODUCT_NAME=
-
-NODE_ENV={{NODE_ENV}}
-# Used for PM2
-SERVICE_INSTANCE={{SERVICE_INSTANCE}}
-PM2_NAMESPACE={{PM2_NAMESPACE}}
-
-# Affects how the Consul service ID is formed - as a product or development ID
-NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
-
-DEBUG=config-info
-# Used for PM2 service configuration
-#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
-#│ id │ name                                                      │ namespace       │
-#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
-#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
-
-## DEBUG patterns ##
-# AP-UPDATER - consul/access-points-updater
-# fa-consul:reg | fa-consul:* - consul/cyclic-register
-# fa-consul:curl - consul/prepare-consul-api
-# token:auth         - authentication: which auth method matched, token parsing/validation outcome
-# mcp:tool           - tools/call: tool name + arguments in, response (text or JSON) out
-# mcp:resource       - resources/list and resources/read: URI in, body out
-# mcp:notification   - all incoming notifications/* (method + params)
-# mcp:prompt         - prompts/list and prompts/get: name/args in, messages out
-# mcp:*              - all four MCP channels above at once
-# mcp-handshake      - HTTP transport: per-request dump (method, id, session routing, protocol, auth, IP)
-# mcp-rpc            - HTTP transport: one-line summary of every successful JSON-RPC response
-#
-#(session-lifecycle events, the -32600 "no valid session" rejection and JSON-RPC errors log always)
-#
-# ========================================================================
-# AGENT TESTER - Built-in AI agent for testing MCP tools
-# ========================================================================
-# AGENT_TESTER_ENABLED=true
-# AGENT_TESTER_USE_AUTH=false
-# AGENT_TESTER_OPENAI_API_KEY=sk-...
-# AGENT_TESTER_OPENAI_BASE_URL=
-
-# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
-# TEST_MCP_SERVER_URL=
-
-# The directory to store test result logs
-TEST_RESULT_LOGS_DIR='_logs/mcp'
+# SERVICE_NAME - service name. If this variable is not specified, it is taken from package.json.name
+SERVICE_NAME={{project.name}}
+# PRODUCT_NAME - If this variable is not specified, it is taken from package.json.productName
+# PRODUCT_NAME=
+
+NODE_ENV={{NODE_ENV}}
+# Used for PM2
+SERVICE_INSTANCE={{SERVICE_INSTANCE}}
+PM2_NAMESPACE={{PM2_NAMESPACE}}
+
+# Affects how the Consul service ID is formed - as a product or development ID
+NODE_CONSUL_ENV={{NODE_CONSUL_ENV}}
+
+DEBUG=config-info
+# Used for PM2 service configuration
+#┌────┬───────────────────────────────────────────────────────────┬─────────────────┬
+#│ id │ name                                                      │ namespace       │
+#├────┼───────────────────────────────────────────────────────────┼─────────────────┼
+#│ 1  │ <SERVICE_NAME | package.json.name>[--<SERVICE_INSTANCE>]  │ <PM2_NAMESPACE> │
+
+## DEBUG patterns ##
+# AP-UPDATER - consul/access-points-updater
+# fa-consul:reg | fa-consul:* - consul/cyclic-register
+# fa-consul:curl - consul/prepare-consul-api
+# token:auth         - authentication: which auth method matched, token parsing/validation outcome
+# mcp:tool           - tools/call: tool name + arguments in, response (text or JSON) out
+# mcp:resource       - resources/list and resources/read: URI in, body out
+# mcp:notification   - all incoming notifications/* (method + params)
+# mcp:prompt         - prompts/list and prompts/get: name/args in, messages out
+# mcp:*              - all four MCP channels above at once
+# mcp-handshake      - HTTP transport: per-request dump (method, id, session routing, protocol, auth, IP)
+# mcp-rpc            - HTTP transport: one-line summary of every successful JSON-RPC response
+#
+#(session-lifecycle events, the -32600 "no valid session" rejection and JSON-RPC errors log always)
+#
+# ========================================================================
+# AGENT TESTER - Built-in AI agent for testing MCP tools
+# ========================================================================
+# AGENT_TESTER_ENABLED=true
+# AGENT_TESTER_USE_AUTH=false
+# AGENT_TESTER_OPENAI_API_KEY=sk-...
+# AGENT_TESTER_OPENAI_BASE_URL=
+
+# The address of the mcp server for testing. Default: http://localhost:<config.webServer.port>
+# TEST_MCP_SERVER_URL=
+
+# The directory to store test result logs
+TEST_RESULT_LOGS_DIR='_logs/mcp'

package/cli-template/FA-MCP-SDK-DOC/02-1-tools-and-api.md

@@ -172,6 +172,92 @@ asJsonError({ code: 'NOT_FOUND', key: 'X' });  // { structuredContent: {...},
 > for missing resources, convert those branches to `return formatToolError('Not found: ...')`. The
 > LLM will start surfacing "Such an issue does not exist" to the user instead of failing the call.
 
+### Normalizing upstream API errors
+
+The `isError` vs `throw` decision above is easy when the handler discovers the problem itself (a `null`
+issue). It is harder when the failure surfaces as a raw error thrown deep inside an HTTP client — a 404
+from the upstream API arrives as an Axios/`fetch` rejection, not as a clean `formatToolError`. Catching
+that in every handler is repetitive and easy to get wrong. The pattern below centralizes it in the single
+`catch` of `handleToolCall`, and implements standard
+[§13.4 "Mapping upstream errors"](./12-implementation-standard.md#134-mapping-upstream-downstream-api-errors).
+
+It has three pure steps — translate, classify, surface:
+
+```typescript
+import {
+  formatToolError, ToolExecutionError, ServerError, RateLimitedError,
+  UpstreamUnavailableError, ValidationError, ConflictError, ResourceNotFoundError, toStr,
+} from 'fa-mcp-sdk';
+
+// 1. TRANSLATE — convert a raw upstream HTTP error into a typed error class (no throw here).
+//    Map the upstream status onto the Appendix B error set instead of one opaque ServerError.
+function handleAxiosError(error: any, toolName: string): never {
+  const status = error?.response?.status;
+  const msg = extractUpstreamMessage(error?.response?.data) ?? error?.message ?? 'Unknown error';
+  const data = { toolName, status };                       // safe: no body, no headers, no stack
+
+  if (!status || status >= 502) throw new UpstreamUnavailableError(`Upstream unavailable: ${msg}`, data);
+  if (status === 400)           throw new ValidationError(`Invalid request: ${msg}`);
+  if (status === 404)           throw new ResourceNotFoundError(msg, data);
+  if (status === 409)           throw new ConflictError(`State conflict: ${msg}`, data);
+  if (status === 429) {
+    const retryAfter = parseInt(error?.response?.headers?.['retry-after'], 10) || 60;
+    throw new RateLimitedError(`Rate limited: ${msg}`, retryAfter);
+  }
+  // 401/403 and other 5xx — keep the upstream status in `data.status` so step 2 can recognize it.
+  throw new ServerError(`Upstream error (HTTP ${status}): ${msg}`, data);
+}
+
+// 2. NORMALIZE — turn ANY thrown value into a concrete Error, still WITHOUT throwing.
+//    A pure function lets the MCP path (may surface to the LLM) and a REST path (always throws)
+//    share one step.
+export function normalizeToolError(error: any, toolName: string): Error {
+  if (error instanceof ToolExecutionError || error instanceof ServerError ||
+      typeof error?.jsonRpcCode === 'number') {
+    return error;                                          // already a domain error
+  }
+  if (isAxiosError(error)) {
+    try { handleAxiosError(error, toolName); } catch (converted) { return converted as Error; }
+  }
+  return new ServerError(toStr(error), { toolName }, true); // catch-all, sanitized (no upstream status)
+}
+
+// 3. CLASSIFY — decide whether the model should SEE the message (isError) or get a thrown protocol error.
+export function isLlmVisibleError(error: any): boolean {
+  if (error instanceof RateLimitedError) return false;     // retry contract — keep -32003 thrown
+  if (error instanceof ToolExecutionError) return true;    // JQL/validation written for the model
+  if (typeof error?.jsonRpcCode === 'number') return true; // ValidationError/NotFound/Conflict/Upstream
+  if (error instanceof ServerError && error?.details?.status != null) return true; // upstream 401/403/5xx
+  return false;                                            // catch-all ServerError → "Internal error"
+}
+```
+
+Wire all three into the single `catch`, so every handler benefits without its own try/catch:
+
+```typescript
+} catch (error: any) {
+  const normalized = normalizeToolError(error, toolName);
+  if (isLlmVisibleError(normalized)) {
+    // The model reads the upstream reason ("Issue AITECH-123 does not exist") and self-corrects.
+    return formatToolError(normalized.message);
+  }
+  throw normalized;                                        // RateLimitedError / internal → protocol error
+}
+```
+
+Why this split matters:
+
+- A **404 raised by the upstream API** becomes `ResourceNotFoundError` (numeric `jsonRpcCode`), so
+  `isLlmVisibleError` returns `true` and the model gets `result.isError=true` — exactly like the manual
+  `formatToolError` branch in the previous section, but for an error it never saw directly.
+- **`RateLimitedError` stays thrown** as `-32003` with `retryAfter` — clients depend on that contract, so
+  it must not collapse into an `isError` text result.
+- A **catch-all `ServerError`** (no `details.status`) stays thrown and is sanitized by the SDK to
+  `Internal error` — its text may carry internal detail and MUST NOT reach the model (standard §13.3).
+
+> Keep `normalizeToolError` **pure** (never throws). A throwing normalizer forces every call site into its
+> own try/catch and defeats the point of centralizing the logic.
+
 ### Headers Access
 
 Headers are normalized to lowercase. Available in HTTP/SSE transports:

package/cli-template/FA-MCP-SDK-DOC/06-utilities.md

@@ -37,6 +37,26 @@ class MyError extends BaseMcpError {
 | `RateLimitedError` | `RATE_LIMITED` | `-32003` | 429 | Appendix B |
 | `TimeoutError` | `TIMEOUT` | `-32004` | 504 | Appendix B |
 | `PayloadTooLargeError` | `PAYLOAD_TOO_LARGE` | `-32005` | 413 | Appendix B |
+| `UpstreamUnavailableError` | `UPSTREAM_UNAVAILABLE` | `-32006` | 503 | Appendix B |
+| `ConflictError` | `CONFLICT` | `-32007` | 409 | Appendix B |
+
+### Mapping a Downstream API Status to a Typed Error
+
+When a tool proxies a downstream HTTP API, translate the upstream status into one of these classes instead
+of a single opaque `ServerError`. This gives the JSON-RPC layer a meaningful code and lets the surfacing
+logic (next) decide whether the model should see the message. This is standard §13.4; the end-to-end
+`normalizeToolError` / `isLlmVisibleError` / `formatToolError` pattern is in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+| Upstream HTTP                 | Throw                       | Surfaced to model as `isError`? |
+|-------------------------------|-----------------------------|---------------------------------|
+| 400                           | `ValidationError`           | yes                             |
+| 401 / 403                     | `ServerError` (status in data) | yes                          |
+| 404                           | `ResourceNotFoundError`     | yes                             |
+| 409                           | `ConflictError`             | yes                             |
+| 429                           | `RateLimitedError`          | no — thrown, keeps `retryAfter` |
+| 502 / 503 / 504 / no response | `UpstreamUnavailableError`  | yes                             |
+| other 5xx / unexpected        | `ServerError` (no status)   | no — thrown, sanitized          |
 
 ## Error Utilities
 

package/cli-template/FA-MCP-SDK-DOC/12-implementation-standard.md

@@ -2,9 +2,9 @@
 
 | Parameter                  | Value                              |
 |----------------------------|------------------------------------|
-| Version                    | 1.2                                |
+| Version                    | 1.3                                |
 | Status                     | Active                             |
-| Date                       | 2026-06-03                         |
+| Date                       | 2026-06-05                         |
 | Scope                      | All internal company MCP servers   |
 | Base MCP                   | MCP 2025-11-25                      |
 | Starter SDK (optional)     | `fa-mcp-sdk`                       |
@@ -13,7 +13,8 @@
 > This document is the English translation of the corporate implementation standard. It restates the
 > explicit MCP 2025-11-25 requirements plus the corporate Avatar / AI Platform profile in a single
 > self-contained document. Version 1.2 adds the side-effect tools and risk-level rules and fixes the
-> `-32007` error-code inconsistency.
+> `-32007` error-code inconsistency. Version 1.3 adds §13.4 on mapping upstream (downstream API) errors
+> to typed error classes and the rule for surfacing model-correctable errors via `result.isError=true`.
 
 ## Table of Contents
 
@@ -765,6 +766,50 @@ An error returned externally MUST NOT contain:
 - raw SQL/expression text with user data;
 - internal service names that are not part of the public contract.
 
+### 13.4. Mapping upstream (downstream API) errors
+
+This section is a corporate recommendation for servers that proxy a downstream HTTP API (Jira, GitLab, an
+internal microservice, etc.). It defines how a failed upstream call is translated into the two error types
+of §13.1 so that the model receives an actionable reason instead of one opaque `-32603 Internal error`.
+
+When a tool calls a downstream API, the server SHOULD translate the upstream HTTP status into the matching
+typed error class from [Appendix B](#appendix-b-error-codes) rather than collapsing every failure into a
+generic internal error. The recommended mapping is:
+
+| Upstream HTTP                     | Typed error class      | JSON-RPC | Returned to the model |
+| --------------------------------- | ---------------------- | -------- | --------------------- |
+| 400                               | `ValidationError`      | -32602   | `isError=true`        |
+| 401 / 403                         | `ServerError` (with upstream status in `data`) | -32000 | `isError=true` |
+| 404                               | `ResourceNotFoundError`| -32002   | `isError=true`        |
+| 409                               | `ConflictError`        | -32007   | `isError=true`        |
+| 429                               | `RateLimitedError`     | -32003   | thrown (see below)    |
+| 502 / 503 / 504 / no response     | `UpstreamUnavailableError` | -32006 | `isError=true`      |
+| other 5xx                         | `ServerError`          | -32000   | thrown                |
+
+The decision whether to surface an error to the model or to throw it follows three rules:
+
+- An error whose message is **safe to expose and actionable** — built from the structured upstream error
+  body, not from internal state — SHOULD be returned as a tool execution result with `result.isError=true`
+  (§9.4, §13.1). The model reads the upstream reason (for example `Issue AITECH-123 does not exist`) and
+  self-corrects instead of treating the call as a hard sandbox failure. A `404` raised by the downstream
+  API is the canonical case: it MUST reach the model as `result.isError=true`, not as a thrown protocol
+  error.
+- `-32003 Rate limited` MUST remain a **thrown** protocol error and MUST carry the `Retry-After` header /
+  `retryAfter` value (§14, Appendix B.3). It MUST NOT be flattened into an `isError` text result, because
+  clients rely on the numeric code and the retry hint to schedule a retry.
+- An internal failure with **no upstream status** (the catch-all wrapper around an unexpected exception)
+  MUST stay a thrown protocol error and MUST be sanitized per §13.3 — typically `-32603 Internal error`
+  with no stack trace and no secrets.
+
+A reference implementation of this pattern — a pure `normalizeToolError()` that converts any thrown value
+into a typed error without throwing, an `isLlmVisibleError()` predicate that applies the three rules above,
+and the `formatToolError()` call that surfaces the message — is documented in
+[02-1-tools-and-api.md → "Normalizing upstream API errors"](./02-1-tools-and-api.md).
+
+Whatever message is exposed (via `isError=true` or a thrown error) MUST still satisfy the §13.3
+prohibitions: the upstream error body is forwarded only after it has been reduced to its human-readable
+text, never as a raw payload that could carry internal paths, tokens, or stack traces.
+
 ## 14. Limits and protection
 
 Each server MUST document and enforce:

package/cli-template/package.json

@@ -58,7 +58,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.11.10"
+    "fa-mcp-sdk": "^0.11.12"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fa-mcp-sdk",
   "productName": "FA MCP SDK",
-  "version": "0.11.10",
+  "version": "0.11.12",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",