sage-graphql-mcp/.sisyphus/notepads/sage-x3-graphql-mcp/learnings.md

Learnings

Session Start

• Greenfield project — no existing code, only opencode.json + planner_instructions.md
• No git repo initialized yet
• No git worktrees — per planner instructions
• Runtime: Bun (built-in TypeScript, fetch, test runner)
• Dependencies: @modelcontextprotocol/sdk, zod, jose
• Demo endpoint: https://api-devna.dev-sagex3.com/demo/service/X3CLOUDV2_SEED/api (unauthenticated, max 20 results)

Task 1: Project Initialization

MCP SDK Package

• npm package is @modelcontextprotocol/sdk (NOT @modelcontextprotocol/server)
• Import path uses subpath export: import { McpServer, StdioServerTransport } from '@modelcontextprotocol/sdk/server'
• Zod import: import * as z from 'zod/v4' (v4 subpath)
• Installed versions: @modelcontextprotocol/sdk@1.27.1, jose@6.2.1, zod@4.3.6

Bun Runtime

• bun not installed on this system; using npx bun as workaround
• bun init -y creates index.ts, tsconfig.json, README.md, .gitignore
• bun init tsconfig defaults to bundler mode — replaced with NodeNext for MCP compatibility

Config Module Pattern

• import.meta.main works in Bun to detect direct execution
• process.env works in Bun (Node compat)
• Auto-detect mode pattern: check presence of clientId + secret + user → "authenticated", else "sandbox"
• JSON.stringify omits undefined properties — clean output for debugging

Task 3: Auth Module

jose Library (v6.2.1)

• new SignJWT(payload).setProtectedHeader({ alg: 'HS256' }).sign(secret) — clean chaining API
• Secret must be Uint8Array via new TextEncoder().encode(secretString)
• Can pass all JWT claims directly in payload constructor — no need to use .setIssuedAt() etc. when custom values needed
• Do NOT use .setIssuedAt() for X3 — need custom iat with -30s offset

X3 JWT Claims

• iss = clientId, sub = user, aud = "" (empty string)
• iat = Math.floor(Date.now() / 1000) - 30 — 30-second clock skew offset is CRITICAL
• exp = iat + tokenLifetime
• Algorithm: HS256 only

Auth Headers Pattern

• Sandbox: only Content-Type: application/json (no auth at all)
• Authenticated: Authorization: Bearer <jwt>, x-xtrem-endpoint: <endpoint>, Content-Type: application/json
• JWT regenerated on each call (short-lived tokens, no caching)

Task 5: MCP Prompts Module

MCP SDK Prompt API (v2)

• Use server.registerPrompt() (not deprecated server.prompt())
• Signature: registerPrompt(name, { title?, description?, argsSchema? }, callback)
• argsSchema is a raw Zod shape object (NOT wrapped in z.object()) — the SDK wraps it internally
• Callback: (args, extra) => GetPromptResult for prompts with args, (extra) => GetPromptResult for no-args
• For no-args prompts, omit argsSchema from config — callback receives only extra param
• Return type: { messages: [{ role: 'user', content: { type: 'text', text: string } }] }
• Import: McpServer from @modelcontextprotocol/sdk/server/mcp.js

Task 4: GraphQL Client

Dynamic Import for Parallel Task Dependencies

• When module A depends on module B being created by a parallel task, use variable-path dynamic import
• const path = '../auth/index.js'; await import(path) — TypeScript types it as any, no static resolution error
• Allows compilation even when the target module doesn't exist yet

Demo Endpoint Status (2026-03-13)

• Demo endpoint https://api-devna.dev-sagex3.com/demo/service/X3CLOUDV2_SEED/api currently returns 401
• Response body: "Votre mot de passe a expiré. Vous devez le modifier" (French: password expired)
• This is a server-side issue, not a client bug — our error handling catches it correctly

Mutation Guard Pattern

• Regex /^mutation\b/i on query.trim() catches: mutation {, MUTATION {, mutation {
• Word boundary \b prevents false positives on field names containing "mutation"

TLS Override Pattern

• Save process.env.NODE_TLS_REJECT_UNAUTHORIZED before, restore in finally block
• If was undefined before, delete the env var rather than setting to undefined

Task 3b: MCP Resources Module

MCP SDK Resource API (v2)

• Use server.registerResource() (not deprecated server.resource())
• Signature: registerResource(name, uri, config, readCallback)
• config is ResourceMetadata = { description?, mimeType?, title?, annotations? }
• readCallback: (uri: URL, extra) => { contents: [{ uri: string, text: string, mimeType?: string }] }
• Import: McpServer from @modelcontextprotocol/sdk/server/mcp.js
• For static resources, pass URI as plain string (not ResourceTemplate)

F1: Plan Compliance Audit Results

Verification Evidence

• Typecheck: npx bun run typecheck → clean (0 errors)
• Tests: npx bun test → 51 pass, 0 fail, 167 expect() calls, 5 test files
• Mutation guard: Two-layer defense — tool-level in execute-graphql.ts + client-level in client.ts
• All 22 src files inspected: Simple structure, one file per tool, no over-abstraction
• MCP server protocol tested: mcp-server.test.ts covers initialize, tools/list (5), resources/list (5), prompts/list (4), error handling

Key Architecture Patterns

• Tools use server.registerTool() or server.tool() with Zod v4 schemas
• Resources registered in a loop from knowledge/ directory constants
• Config auto-detects sandbox vs authenticated from env var presence
• JWT uses jose SignJWT with 30-second clock skew offset per X3 docs