@nextfreelatech/xpec-mcp 1.0.1

package/dist/config.js

@@ -0,0 +1,159 @@
+// Config + binding resolution (per Xpec specs "mcp-server" §3+§6
+// and "mcp-workspace-tools" §4). Phase 4 of the Workspaces epic introduces
+// an aggregation layer above Products, so a project binding can name either
+// a Workspace, a Product, or both.
+//
+// Precedence per binding key (workspaceId, productId):
+//   1. `.xpec.json` at the project root
+//   2. `XPEC_WORKSPACE_ID` / `XPEC_PRODUCT_ID` env vars
+//   3. unset
+//
+// Effective binding mode is computed from the resolved pair:
+//   * both set         → "workspace+product"
+//   * workspaceId only → "workspace"
+//   * productId only   → "product"  (orphan / pre-aggregation Product)
+//   * neither          → "discovery" (only list_workspaces / list_products
+//                         orphan-only are usable until ids are passed)
+//
+// API URL precedence:
+//   1. `--api-url` command-line flag (parsed in cli.ts)
+//   2. `apiUrl` in `.xpec.json`
+//   3. `XPEC_API_URL` environment variable
+//   4. https://app.xpec.com (default)
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+export const DEFAULT_API_URL = "https://app.xpec.com";
+export const PROJECT_CONFIG_FILENAME = ".xpec.json";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+function parseProjectFile(cwd, fileReader) {
+    const path = resolvePath(cwd, PROJECT_CONFIG_FILENAME);
+    const raw = fileReader(path);
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`${PROJECT_CONFIG_FILENAME} is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new ConfigError(`${PROJECT_CONFIG_FILENAME} must contain a JSON object.`);
+    }
+    return parsed;
+}
+function defaultFileReader(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function normalizeApiUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+export function resolveConfig(overrides = {}) {
+    const cwd = overrides.cwd ?? process.cwd();
+    const env = overrides.env ?? process.env;
+    const fileReader = overrides.fileReader ?? defaultFileReader;
+    const file = parseProjectFile(cwd, fileReader);
+    // workspaceId
+    let workspaceId = null;
+    let workspaceSource = "none";
+    if (file &&
+        typeof file.workspaceId === "string" &&
+        file.workspaceId.length > 0) {
+        workspaceId = file.workspaceId;
+        workspaceSource = "config-file";
+    }
+    else if (typeof env.XPEC_WORKSPACE_ID === "string" &&
+        env.XPEC_WORKSPACE_ID.length > 0) {
+        workspaceId = env.XPEC_WORKSPACE_ID;
+        workspaceSource = "env";
+    }
+    // productId
+    let productId = null;
+    let productSource = "none";
+    if (file && typeof file.productId === "string" && file.productId.length > 0) {
+        productId = file.productId;
+        productSource = "config-file";
+    }
+    else if (typeof env.XPEC_PRODUCT_ID === "string" &&
+        env.XPEC_PRODUCT_ID.length > 0) {
+        productId = env.XPEC_PRODUCT_ID;
+        productSource = "env";
+    }
+    // Phase 4 of the Workspaces epic: both ids are optional and the
+    // server starts in discovery mode when both are absent. The previous
+    // "productId required when the file is present" rule is removed; an
+    // empty `{}` file just means "no binding".
+    // apiUrl
+    let apiUrl = DEFAULT_API_URL;
+    let apiUrlSource = "default";
+    if (overrides.apiUrl) {
+        apiUrl = overrides.apiUrl;
+        apiUrlSource = "argument";
+    }
+    else if (file && typeof file.apiUrl === "string" && file.apiUrl.length > 0) {
+        apiUrl = file.apiUrl;
+        apiUrlSource = "config-file";
+    }
+    else if (typeof env.XPEC_API_URL === "string" &&
+        env.XPEC_API_URL.length > 0) {
+        apiUrl = env.XPEC_API_URL;
+        apiUrlSource = "env";
+    }
+    apiUrl = normalizeApiUrl(apiUrl);
+    const allowInsecure = overrides.allowInsecure ?? false;
+    if (!allowInsecure && !apiUrl.startsWith("https://") && !isLocalUrl(apiUrl)) {
+        throw new ConfigError(`apiUrl "${apiUrl}" is not HTTPS. Pass --allow-insecure to opt in (intended for self-hosted dev only).`);
+    }
+    // token
+    const token = typeof env.XPEC_API_TOKEN === "string" &&
+        env.XPEC_API_TOKEN.length > 0
+        ? env.XPEC_API_TOKEN
+        : null;
+    // telemetry
+    const telemetryEnabled = env.XPEC_TELEMETRY !== "0";
+    const bindingMode = workspaceId && productId
+        ? "workspace+product"
+        : workspaceId
+            ? "workspace"
+            : productId
+                ? "product"
+                : "discovery";
+    return {
+        apiUrl,
+        apiUrlSource,
+        token,
+        workspaceId,
+        workspaceSource,
+        productId,
+        productSource,
+        bindingMode,
+        telemetryEnabled,
+        allowInsecure,
+    };
+}
+// Localhost / loopback URLs are commonly used during dev — let `http://localhost…`
+// through without `--allow-insecure`. Anything else over HTTP needs the flag.
+function isLocalUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return (parsed.hostname === "localhost" ||
+            parsed.hostname === "127.0.0.1" ||
+            parsed.hostname === "::1");
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,2EAA2E;AAC3E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,uDAAuD;AACvD,wCAAwC;AACxC,wDAAwD;AACxD,aAAa;AACb,EAAE;AACF,6DAA6D;AAC7D,6CAA6C;AAC7C,qCAAqC;AACrC,uEAAuE;AACvE,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,sBAAsB;AACtB,wDAAwD;AACxD,gCAAgC;AAChC,2CAA2C;AAC3C,sCAAsC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,eAAe,GAAG,sBAAsB,CAAC;AACtD,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CAAC;AA+CpD,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,SAAS,gBAAgB,CACvB,GAAW,EACX,UAA2C;IAE3C,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,GAAG,uBAAuB,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAC1E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,WAAW,CACnB,GAAG,uBAAuB,8BAA8B,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,MAA0B,CAAC;AACpC,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,YAA6B,EAAE;IAC3D,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACzC,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAC7D,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAE/C,cAAc;IACd,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,eAAe,GAAsC,MAAM,CAAC;IAChE,IACE,IAAI;QACJ,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;QACpC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAC3B,CAAC;QACD,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QAC/B,eAAe,GAAG,aAAa,CAAC;IAClC,CAAC;SAAM,IACL,OAAO,GAAG,CAAC,iBAAiB,KAAK,QAAQ;QACzC,GAAG,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAChC,CAAC;QACD,WAAW,GAAG,GAAG,CAAC,iBAAiB,CAAC;QACpC,eAAe,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED,YAAY;IACZ,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,aAAa,GAAoC,MAAM,CAAC;IAC5D,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5E,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAC3B,aAAa,GAAG,aAAa,CAAC;IAChC,CAAC;SAAM,IACL,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ;QACvC,GAAG,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAC9B,CAAC;QACD,SAAS,GAAG,GAAG,CAAC,eAAe,CAAC;QAChC,aAAa,GAAG,KAAK,CAAC;IACxB,CAAC;IAED,gEAAgE;IAChE,qEAAqE;IACrE,oEAAoE;IACpE,2CAA2C;IAE3C,SAAS;IACT,IAAI,MAAM,GAAG,eAAe,CAAC;IAC7B,IAAI,YAAY,GAAmC,SAAS,CAAC;IAC7D,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QACrB,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;QAC1B,YAAY,GAAG,UAAU,CAAC;IAC5B,CAAC;SAAM,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACrB,YAAY,GAAG,aAAa,CAAC;IAC/B,CAAC;SAAM,IACL,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QACpC,GAAG,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAC3B,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC;QAC1B,YAAY,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,aAAa,GAAG,SAAS,CAAC,aAAa,IAAI,KAAK,CAAC;IACvD,IAAI,CAAC,aAAa,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,WAAW,CACnB,WAAW,MAAM,sFAAsF,CACxG,CAAC;IACJ,CAAC;IAED,QAAQ;IACR,MAAM,KAAK,GACT,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ;QACtC,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAC3B,CAAC,CAAC,GAAG,CAAC,cAAc;QACpB,CAAC,CAAC,IAAI,CAAC;IAEX,YAAY;IACZ,MAAM,gBAAgB,GAAG,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC;IAEpD,MAAM,WAAW,GACf,WAAW,IAAI,SAAS;QACtB,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,WAAW;YACX,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,SAAS;gBACT,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,WAAW,CAAC;IAEtB,OAAO;QACL,MAAM;QACN,YAAY;QACZ,KAAK;QACL,WAAW;QACX,eAAe;QACf,SAAS;QACT,aAAa;QACb,WAAW;QACX,gBAAgB;QAChB,aAAa;KACd,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,8EAA8E;AAC9E,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,CACL,MAAM,CAAC,QAAQ,KAAK,WAAW;YAC/B,MAAM,CAAC,QAAQ,KAAK,WAAW;YAC/B,MAAM,CAAC,QAAQ,KAAK,KAAK,CAC1B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/errors.js

@@ -0,0 +1,100 @@
+// MCP-side error mapping (per Xpec spec "mcp-server" §5 "Error mapping").
+// Translates Xpec API error envelopes into MCP error codes the
+// agent can reason about, each carrying a short remediation string.
+export class McpToolError extends Error {
+    code;
+    remediation;
+    constructor(code, message, remediation) {
+        super(message);
+        this.code = code;
+        this.remediation = remediation;
+        this.name = "McpToolError";
+    }
+    toFailure() {
+        return {
+            code: this.code,
+            message: this.message,
+            remediation: this.remediation,
+        };
+    }
+}
+const REMEDIATIONS = {
+    AUTH_FAILED: "Regenerate a Personal Access Token from /settings/developer and update XPEC_API_TOKEN.",
+    TOKEN_EXPIRED: "The token expired. Generate a new one from /settings/developer.",
+    TOKEN_REVOKED: "The token was revoked. Generate a new one from /settings/developer.",
+    TOKEN_SCOPE_MISMATCH: "The token isn't scoped to this product. Use a token whose allowlist includes it, or remove the allowlist.",
+    PRODUCT_NOT_BOUND: "Call list_products, pick one, then add it to .xpec.json or set XPEC_PRODUCT_ID.",
+    WORKSPACE_NOT_BOUND: "Call list_workspaces, pick one, then add it to .xpec.json as `workspaceId` or set XPEC_WORKSPACE_ID.",
+    PRODUCT_TYPE_MISMATCH: "The filter you passed isn't compatible with this product's type. Drop the filter or call against a matching product.",
+    NOT_IN_WORKSPACE: "This tool requires a Workspace binding. Set `workspaceId` in .xpec.json or pass it explicitly.",
+    LEGACY_BINDING_DETECTED: 'Edit .xpec.json: rename the "workspaceId" field to "productId" (the value points at a Product under the new model). To bind to a Workspace, create one and set both ids.',
+    SPEC_LOCKED: "The spec is in REVIEWED state. Call start_new_version first to enter Draft.",
+    OPEN_QUESTIONS_PRESENT: "Resolve or dismiss the open questions on this spec before proceeding.",
+    STALE_VERSION: "Re-read the spec to pick up the current OCC version, then retry with that version.",
+    RATE_LIMITED: "You hit the per-token rate limit. Wait until the Retry-After window passes and try again.",
+    NOT_FOUND: "The resource doesn't exist or isn't visible to this token.",
+    VALIDATION_ERROR: "Inspect the details — at least one argument failed schema validation.",
+    INTERNAL_ERROR: "The Xpec API hit an unexpected error. Retry once; if it persists, contact support.",
+};
+/**
+ * Map an HTTP response (status + parsed body) onto an `McpToolError`. The
+ * body's `error.code` takes precedence when present, falling back to the
+ * status code's standard meaning.
+ */
+export function mapApiError(status, body) {
+    const apiCode = body?.error?.code;
+    const apiMessage = body?.error?.message ?? `Request failed with status ${status}.`;
+    const code = pickStructuredCode(status, apiCode, body?.error?.details);
+    return new McpToolError(code, apiMessage, REMEDIATIONS[code]);
+}
+function pickStructuredCode(status, apiCode, details) {
+    // Prefer explicit codes on the API error envelope or in `details.code`.
+    const explicitCode = apiCode ?? extractDetailCode(details);
+    if (explicitCode) {
+        if (explicitCode === "TOKEN_SCOPE_MISMATCH")
+            return "TOKEN_SCOPE_MISMATCH";
+        if (explicitCode === "TOKEN_EXPIRED")
+            return "TOKEN_EXPIRED";
+        if (explicitCode === "TOKEN_REVOKED")
+            return "TOKEN_REVOKED";
+        if (explicitCode === "PRODUCT_TYPE_MISMATCH")
+            return "PRODUCT_TYPE_MISMATCH";
+        if (explicitCode === "NOT_IN_WORKSPACE")
+            return "NOT_IN_WORKSPACE";
+        if (explicitCode === "SPEC_LOCKED")
+            return "SPEC_LOCKED";
+        if (explicitCode === "OPEN_QUESTIONS_PRESENT")
+            return "OPEN_QUESTIONS_PRESENT";
+        if (explicitCode === "STALE_VERSION")
+            return "STALE_VERSION";
+        if (explicitCode === "AUTH_REQUIRED" || explicitCode === "AUTH_FAILED")
+            return "AUTH_FAILED";
+    }
+    // Fallback by status code.
+    if (status === 401)
+        return "AUTH_FAILED";
+    if (status === 403)
+        return "TOKEN_SCOPE_MISMATCH";
+    if (status === 404)
+        return "NOT_FOUND";
+    if (status === 409)
+        return "STALE_VERSION";
+    if (status === 422)
+        return "VALIDATION_ERROR";
+    if (status === 429)
+        return "RATE_LIMITED";
+    return "INTERNAL_ERROR";
+}
+function extractDetailCode(details) {
+    if (details &&
+        typeof details === "object" &&
+        "code" in details &&
+        typeof details.code === "string") {
+        return details.code;
+    }
+    return undefined;
+}
+export function buildClientFailure(code, message) {
+    return { code, message, remediation: REMEDIATIONS[code] };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/http.js

@@ -0,0 +1,147 @@
+// HTTP/SSE transport (per Xpec spec "mcp-server" §3 BDD
+// "HTTP+SSE transport for hosted agents" + §5 "HTTP/SSE transport").
+//
+// This is the hosted-agent path. The MCP SDK's StreamableHTTPServerTransport
+// auto-detects whether the caller wants SSE streaming or a direct JSON
+// response based on the Accept header, so a single `/mcp` endpoint covers
+// both shapes — that's intentional in the modern MCP wire format.
+//
+// CORS defaults to deny: only same-origin requests (no Origin header) and
+// origins explicitly listed via `--cors-origin` are allowed. This keeps an
+// agent that picks up the local server URL out of reach for a malicious
+// page that happens to be open in the user's browser.
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { logger } from "./logger.js";
+import { buildServer } from "./server.js";
+export const DEFAULT_HTTP_PORT = 7345;
+export const DEFAULT_HTTP_HOST = "127.0.0.1";
+const MCP_PATH = "/mcp";
+const HEALTH_PATH = "/healthz";
+/**
+ * Start the HTTP/SSE MCP server. Resolves once the listener is bound so the
+ * caller knows the actual port (useful when port=0 picks an ephemeral port
+ * during tests).
+ */
+export async function startHttpServer(options) {
+    const port = options.port ?? DEFAULT_HTTP_PORT;
+    const host = options.host ?? DEFAULT_HTTP_HOST;
+    const allowedOrigins = options.corsOrigins ?? [];
+    const mcpServer = buildServer({ config: options.config });
+    // Stateful mode — the transport keeps an MCP session alive across
+    // multiple requests so the agent's `initialize` handshake is honoured
+    // for every follow-up tool/resource call.
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    const server = createServer(async (req, res) => {
+        const url = req.url ?? "/";
+        const method = req.method ?? "GET";
+        // CORS preflight handling — applied to every request before dispatch.
+        if (!applyCors(req, res, allowedOrigins)) {
+            // applyCors already wrote the rejection response.
+            return;
+        }
+        if (method === "OPTIONS") {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        if (url === HEALTH_PATH && method === "GET") {
+            res.statusCode = 200;
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ ok: true }));
+            return;
+        }
+        if (url === MCP_PATH || url.startsWith(`${MCP_PATH}?`)) {
+            try {
+                await transport.handleRequest(req, res);
+            }
+            catch (err) {
+                logger.error("http transport handleRequest failed", {
+                    err: err.message,
+                });
+                if (!res.headersSent) {
+                    res.statusCode = 500;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ error: { code: "INTERNAL_ERROR" } }));
+                }
+            }
+            return;
+        }
+        res.statusCode = 404;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({ error: { code: "NOT_FOUND" } }));
+    });
+    await mcpServer.connect(transport);
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            const address = server.address();
+            const boundPort = address && typeof address === "object" ? address.port : port;
+            logger.info("mcp server connected", {
+                transport: "http",
+                host,
+                port: boundPort,
+                apiUrl: options.config.apiUrl,
+                apiUrlSource: options.config.apiUrlSource,
+                productId: options.config.productId ?? undefined,
+                corsOrigins: allowedOrigins,
+            });
+            if (allowedOrigins.includes("*")) {
+                logger.warn("CORS origin '*' is permissive — restrict for production");
+            }
+            resolve({
+                port: boundPort,
+                host,
+                close: () => new Promise((resolveClose, rejectClose) => {
+                    server.close((err) => (err ? rejectClose(err) : resolveClose()));
+                }),
+            });
+        });
+    });
+}
+// ──────────────────────────────────────────────────────────────────────────
+// CORS
+// ──────────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the request is permitted to proceed. Writes the 403
+ * response itself when the origin is rejected so the caller can early-exit.
+ *
+ * Exported for unit tests so the policy can be evaluated without standing
+ * up an actual HTTP server.
+ */
+export function applyCors(req, res, allowedOrigins) {
+    const origin = req.headers.origin;
+    // Same-origin / non-browser request: no Origin header at all. Always
+    // allowed — the browser only attaches Origin to cross-origin fetches.
+    if (!origin)
+        return true;
+    if (allowedOrigins.includes("*")) {
+        res.setHeader("access-control-allow-origin", "*");
+        setStandardCorsHeaders(res);
+        return true;
+    }
+    if (allowedOrigins.includes(origin)) {
+        res.setHeader("access-control-allow-origin", origin);
+        res.setHeader("vary", "Origin");
+        setStandardCorsHeaders(res);
+        return true;
+    }
+    res.statusCode = 403;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({
+        error: {
+            code: "CORS_ORIGIN_NOT_ALLOWED",
+            message: `Origin "${origin}" is not in the CORS allowlist.`,
+        },
+    }));
+    return false;
+}
+function setStandardCorsHeaders(res) {
+    res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+    res.setHeader("access-control-allow-headers", "authorization, content-type, mcp-session-id, mcp-protocol-version, last-event-id");
+    res.setHeader("access-control-expose-headers", "mcp-session-id, etag");
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public entry for the @nextfreelatech/xpec-mcp package. Most users invoke the
+// CLI via `npx -y @nextfreelatech/xpec-mcp`; this module exists so library
+// consumers (e.g. an integration test or an embedded MCP gateway) can
+// build the same server programmatically.
+export { buildServer, runStdio } from "./server.js";
+export { resolveConfig, ConfigError, DEFAULT_API_URL } from "./config.js";
+export { XpecClient, } from "./client.js";
+export { McpToolError, mapApiError, buildClientFailure, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,0CAA0C;AAE1C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,UAAU,GAGX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,kBAAkB,GAGnB,MAAM,aAAa,CAAC"}

package/dist/logger.js

@@ -0,0 +1,29 @@
+// Structured stderr logger for the MCP server. Stderr (not stdout) because
+// stdio transport reserves stdout for JSON-RPC frames — anything else there
+// breaks the agent's MCP client. One JSON object per line so the agent's
+// parent process can parse logs without a regex.
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const minLevel = process.env.XPEC_LOG_LEVEL ?? "info";
+function emit(level, message, context = {}) {
+    if (LEVEL_RANK[level] < LEVEL_RANK[minLevel])
+        return;
+    const line = JSON.stringify({
+        t: new Date().toISOString(),
+        level,
+        msg: message,
+        ...context,
+    });
+    process.stderr.write(`${line}\n`);
+}
+export const logger = {
+    debug: (message, ctx) => emit("debug", message, ctx),
+    info: (message, ctx) => emit("info", message, ctx),
+    warn: (message, ctx) => emit("warn", message, ctx),
+    error: (message, ctx) => emit("error", message, ctx),
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,iDAAiD;AAgBjD,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,MAAM,QAAQ,GACX,OAAO,CAAC,GAAG,CAAC,cAAuC,IAAI,MAAM,CAAC;AAEjE,SAAS,IAAI,CAAC,KAAe,EAAE,OAAe,EAAE,UAAsB,EAAE;IACtE,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC3B,KAAK;QACL,GAAG,EAAE,OAAO;QACZ,GAAG,OAAO;KACX,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC;IACzE,IAAI,EAAE,CAAC,OAAe,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC;IACvE,IAAI,EAAE,CAAC,OAAe,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC;IACvE,KAAK,EAAE,CAAC,OAAe,EAAE,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC;CAC1E,CAAC"}

package/dist/resources.js

@@ -0,0 +1,181 @@
+// Resource provider for the MCP server. Phase 4 doubles the surface so
+// agents can address either a Product or a Workspace via stable URIs:
+//
+//   xpec://product/{productId}                  — collection: lists Product specs
+//   xpec://product/{productId}/spec/{specId}    — Product spec Markdown body
+//   xpec://workspace/{workspaceId}              — collection: lists Workspace specs
+//   xpec://workspace/{workspaceId}/spec/{specId} — Workspace spec Markdown body
+//
+// Collection URIs are registered as fixed resources so the agent can
+// list-then-pin. Individual specs are exposed via ResourceTemplates so the
+// agent can read any spec in the bound scope by id. ETag/304 behavior is
+// unchanged (per mcp-workspace-tools.md §3).
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpToolError } from "./errors.js";
+import { logger } from "./logger.js";
+export function registerResources(server, deps) {
+    const { client, config } = deps;
+    if (!config.productId && !config.workspaceId) {
+        // Discovery mode — no bound scope means no resource surface. The agent
+        // can call list_products / list_workspaces to discover ids; resources
+        // become available after the user binds a scope and reconnects.
+        logger.debug("resources skipped — no binding (discovery mode)");
+        return;
+    }
+    if (config.workspaceId) {
+        registerWorkspaceResources(server, client, config.workspaceId);
+    }
+    if (config.productId) {
+        registerProductResources(server, client, config.productId);
+    }
+}
+function registerProductResources(server, client, productId) {
+    const wsId = productId;
+    const collectionUri = `xpec://product/${wsId}`;
+    server.registerResource("product-specs", collectionUri, {
+        title: "Product specifications",
+        description: `Specifications in product ${wsId}. Read this resource to enumerate the specs an agent can pin into context.`,
+        mimeType: "application/json",
+    }, async (uri) => {
+        try {
+            const res = await client.listSpecifications(wsId, { limit: 100 });
+            return {
+                contents: [
+                    {
+                        uri: uri.toString(),
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.body, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            throw mapResourceError(err);
+        }
+    });
+    // Per-spec template — the agent reads a Markdown body by spec id.
+    // The template's `{specId}` slot maps onto a string variable.
+    const template = new ResourceTemplate(`xpec://product/${wsId}/spec/{specId}`, {
+        list: undefined,
+    });
+    server.registerResource("specification-body", template, {
+        title: "Specification Markdown",
+        description: "Read the current Markdown body of a specification. The resource etag mirrors the spec's optimistic-concurrency version, so the client can re-read after change notifications without comparing content.",
+        mimeType: "text/markdown",
+    }, async (uri, variables) => {
+        const specId = String(variables.specId ?? "");
+        if (!specId) {
+            throw new McpToolError("VALIDATION_ERROR", "Resource URI is missing a specId.", "Use the URI shape xpec://product/{productId}/spec/{specId}.");
+        }
+        try {
+            const res = await client.readSpecification(specId, { format: "raw" });
+            if ("notModified" in res) {
+                // Tool reads don't carry If-None-Match, so 304 should not occur.
+                return {
+                    contents: [
+                        {
+                            uri: uri.toString(),
+                            mimeType: "text/markdown",
+                            text: "",
+                        },
+                    ],
+                };
+            }
+            const body = res.body;
+            const text = typeof body?.content === "string" ? body.content : "";
+            return {
+                contents: [
+                    {
+                        uri: uri.toString(),
+                        mimeType: "text/markdown",
+                        text,
+                    },
+                ],
+                // SDK passes through `_meta` on the resource result; the etag is
+                // surfaced for clients that want to short-circuit re-reads.
+                _meta: {
+                    etag: res.etag ?? body?.etag ?? null,
+                },
+            };
+        }
+        catch (err) {
+            throw mapResourceError(err);
+        }
+    });
+}
+function registerWorkspaceResources(server, client, workspaceId) {
+    const collectionUri = `xpec://workspace/${workspaceId}`;
+    server.registerResource("workspace-specs", collectionUri, {
+        title: "Workspace specifications",
+        description: `Specifications in workspace ${workspaceId}. Read this resource to enumerate the cross-product specs an agent can pin into context.`,
+        mimeType: "application/json",
+    }, async (uri) => {
+        try {
+            const res = await client.listSpecificationsForWorkspace(workspaceId, {
+                limit: 100,
+            });
+            return {
+                contents: [
+                    {
+                        uri: uri.toString(),
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.body, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            throw mapResourceError(err);
+        }
+    });
+    const template = new ResourceTemplate(`xpec://workspace/${workspaceId}/spec/{specId}`, {
+        list: undefined,
+    });
+    server.registerResource("workspace-specification-body", template, {
+        title: "Workspace specification Markdown",
+        description: "Read the current Markdown body of a workspace-scoped specification. Etag mirrors the spec's OCC version (Phase 4 mcp-workspace-tools.md §3).",
+        mimeType: "text/markdown",
+    }, async (uri, variables) => {
+        const specId = String(variables.specId ?? "");
+        if (!specId) {
+            throw new McpToolError("VALIDATION_ERROR", "Resource URI is missing a specId.", "Use the URI shape xpec://workspace/{workspaceId}/spec/{specId}.");
+        }
+        try {
+            const res = await client.readSpecification(specId, { format: "raw" });
+            if ("notModified" in res) {
+                return {
+                    contents: [
+                        {
+                            uri: uri.toString(),
+                            mimeType: "text/markdown",
+                            text: "",
+                        },
+                    ],
+                };
+            }
+            const body = res.body;
+            const text = typeof body?.content === "string" ? body.content : "";
+            return {
+                contents: [
+                    {
+                        uri: uri.toString(),
+                        mimeType: "text/markdown",
+                        text,
+                    },
+                ],
+                _meta: {
+                    etag: res.etag ?? body?.etag ?? null,
+                },
+            };
+        }
+        catch (err) {
+            throw mapResourceError(err);
+        }
+    });
+}
+function mapResourceError(err) {
+    if (err instanceof McpToolError)
+        return err;
+    return new McpToolError("INTERNAL_ERROR", err?.message ?? "Resource read failed.", "Retry once; if the failure persists, check the MCP server logs.");
+}
+//# sourceMappingURL=resources.js.map