@nextfreelatech/xpec-mcp 1.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for the acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Nextfreela Tech
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,450 @@
+# Xpec MCP — Specs as the Source of Truth for AI Coding Agents
+
+Xpec is the home for product, feature, and architectural specs. The Xpec MCP server gives local AI coding agents (Claude Code, Cursor, VS Code, Zed, Windsurf, …) **read and write access to those specs**, so agents can plan, implement, and update features against the spec — not against stale `docs/`, hallucinated APIs, or whatever the model remembers from training.
+
+## ❌ Without Xpec MCP
+
+Coding agents drift from your product's actual contracts. You get:
+
+- ❌ Code that ships ahead of the spec, then quietly diverges
+- ❌ Implementations that contradict ADRs nobody re-read
+- ❌ Duplicate "RFC-2025-…" markdown files in the repo, none authoritative
+- ❌ Specs updated only after the code lands, when nobody can challenge them
+
+## ✅ With Xpec MCP
+
+The agent reads the **current** spec before writing code, and proposes spec changes through the same workflow a human reviewer approves.
+
+```
+Implement the password-reset flow per the "auth/password-reset" spec.
+Use the contracts and error codes from §4. If the spec is incomplete,
+open a draft, fill it in, and request review before writing code.
+```
+
+```
+What ADRs apply to background jobs in this product? Read them, then
+critique my proposed worker change against them.
+```
+
+The agent calls `read_specification`, `list_open_questions`, `start_new_version`, `update_specification_section`, `request_review` — and you stay in control: **a human still marks the draft Reviewed in the Xpec UI**.
+
+## 📚 Concepts
+
+- **Workspace** — top-level container. Contains member Products plus its own Workspace-scoped specs (e.g., cross-product ADRs).
+- **Product** — a single product or service. Holds the feature, UX, and architecture specs that govern its codebase.
+- **Specification** — Markdown document with status (`Draft` → `Needs Review` → `Reviewed`), open questions, and a version history.
+- **Binding** — a `.xpec.json` at the repo root binds the local checkout to a Workspace and/or Product, so agents don't have to pass ids on every call.
+
+See `xpec.app` for the dashboard and to mint a token.
+
+## 🛠️ Installation
+
+### Requirements
+
+- **Node.js ≥ 20.11**
+- An MCP-compatible client (Claude Code, Cursor, VS Code, Windsurf, Zed, Claude Desktop, …)
+- An **Xpec Personal Access Token** — generate one at `https://xpec.app/settings/developer`
+- A repo with a `.xpec.json` file (or `XPEC_WORKSPACE_ID` / `XPEC_PRODUCT_ID` env vars). See [Binding the workspace](#binding-the-workspace) below.
+
+### **Install in Claude Code**
+
+Run this command. See the [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
+
+```bash
+claude mcp add --scope user \
+  -e XPEC_API_TOKEN=YOUR_TOKEN \
+  xpec -- npx -y @nextfreelatech/xpec-mcp
+```
+
+Drop `--scope user` to install only for the current project.
+
+To add a rule so the agent always reads the spec first, append the snippet from [Add a rule](#add-a-rule) below to your `CLAUDE.md`.
+
+### **Install in Cursor**
+
+Add this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). See the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol).
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "npx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": {
+        "XPEC_API_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### **Install in VS Code**
+
+See the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
+
+```json
+"mcp": {
+  "servers": {
+    "xpec": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": {
+        "XPEC_API_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### **Install in Windsurf**
+
+Add this to your Windsurf MCP config. See the [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp).
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "npx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": {
+        "XPEC_API_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### **Install in Zed**
+
+Add this to your Zed `settings.json`. See the [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers).
+
+```json
+{
+  "context_servers": {
+    "Xpec": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": {
+        "XPEC_API_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### **Install in Claude Desktop**
+
+Edit your `claude_desktop_config.json`. See the [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user).
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "npx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": {
+        "XPEC_API_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### **Install in OpenAI Codex**
+
+See the [OpenAI Codex repo](https://github.com/openai/codex) for more on the MCP configuration format. Codex reads `~/.codex/config.toml`.
+
+#### Codex Local Server Connection (stdio)
+
+```toml
+[mcp_servers.xpec]
+command = "npx"
+args = ["-y", "@nextfreelatech/xpec-mcp"]
+env = { XPEC_API_TOKEN = "YOUR_TOKEN" }
+startup_timeout_ms = 20_000
+```
+
+#### Codex Remote Server Connection (HTTP)
+
+First, run the server (see [Running over HTTP](#running-over-http-hosted-agents)). Then point Codex at it:
+
+```toml
+[mcp_servers.xpec]
+url = "http://127.0.0.1:3030/mcp"
+http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }
+```
+
+> Optional troubleshooting — only if Codex reports startup "request timed out" or "program not found". Most users can ignore this.
+>
+> - First try: bump `startup_timeout_ms` to `40_000`.
+> - **Windows** quick fix (absolute `npx` path + explicit env):
+>
+>   ```toml
+>   [mcp_servers.xpec]
+>   command = "C:\\Users\\yourname\\AppData\\Roaming\\npm\\npx.cmd"
+>   args = ["-y", "@nextfreelatech/xpec-mcp"]
+>   env = {
+>     XPEC_API_TOKEN = "YOUR_TOKEN",
+>     SystemRoot = "C:\\Windows",
+>     APPDATA = "C:\\Users\\yourname\\AppData\\Roaming"
+>   }
+>   startup_timeout_ms = 40_000
+>   ```
+>
+> - **macOS** quick fix (call Node directly with the installed package's entry point):
+>
+>   ```toml
+>   [mcp_servers.xpec]
+>   command = "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node"
+>   args = [
+>     "/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@nextfreelatech/xpec-mcp/dist/cli.js",
+>     "--stdio"
+>   ]
+>   env = { XPEC_API_TOKEN = "YOUR_TOKEN" }
+>   ```
+>
+> Replace `yourname` with your OS username. On Windows, setting `APPDATA` and `SystemRoot` is essential because `npx` requires them but some Codex builds don't pass them through.
+
+### **Using Bun or Deno**
+
+Any client that launches an MCP server via `command + args` can swap `npx` for an alternative runtime.
+
+#### Bun
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "bunx",
+      "args": ["-y", "@nextfreelatech/xpec-mcp"],
+      "env": { "XPEC_API_TOKEN": "YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+#### Deno
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "deno",
+      "args": [
+        "run",
+        "--allow-env",
+        "--allow-net",
+        "--allow-read",
+        "npm:@nextfreelatech/xpec-mcp"
+      ],
+      "env": { "XPEC_API_TOKEN": "YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+### **Install in Windows**
+
+`npx` on Windows usually needs to be invoked via `cmd /c`:
+
+```json
+{
+  "mcpServers": {
+    "xpec": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@nextfreelatech/xpec-mcp"],
+      "env": { "XPEC_API_TOKEN": "YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+### Running over HTTP (hosted agents)
+
+For agents that consume MCP over HTTP/SSE rather than stdio, run the server explicitly:
+
+```bash
+XPEC_API_TOKEN=YOUR_TOKEN \
+  npx -y @nextfreelatech/xpec-mcp --http --port 3030 --cors-origin https://your-agent.example.com
+```
+
+Then point your hosted agent at `http://<host>:3030/mcp`.
+
+## 🔗 Binding the workspace
+
+The MCP server is **bound** to a Workspace and/or a Product so tools like `list_specifications` work without passing ids every call.
+
+Drop a `.xpec.json` at your repo root:
+
+```json
+{
+  "workspaceId": "ws_…",
+  "productId": "prd_…"
+}
+```
+
+Either field is optional:
+
+| Configuration               | Effective mode      | What works                                                                |
+| --------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| `workspaceId` + `productId` | `workspace+product` | Everything; defaults to the Product's specs                               |
+| `workspaceId` only          | `workspace`         | Workspace-scoped specs + cross-Product search                             |
+| `productId` only            | `product`           | Product-scoped specs (orphan / pre-aggregation Products work this way)    |
+| Neither                     | `discovery`         | Only `list_workspaces` / `list_products` — bind first to do anything else |
+
+You can also use environment variables: `XPEC_WORKSPACE_ID`, `XPEC_PRODUCT_ID`. The file wins over env vars when both are present.
+
+## ✅ Verify the install
+
+```bash
+XPEC_API_TOKEN=YOUR_TOKEN npx -y @nextfreelatech/xpec-mcp --check
+```
+
+Prints `OK: https://xpec.app reachable, N product(s) visible.` on success, or a structured error code (`AUTH_REQUIRED`, `PRODUCT_NOT_BOUND`, …) and remediation when something is off. Add `--json` for machine-readable output.
+
+## 🔨 Available Tools
+
+All tools take ids as strings. Bound Workspace/Product ids are inferred from `.xpec.json` unless overridden in the call.
+
+### Read tools
+
+| Tool                          | Purpose                                                                                                                                                                                |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_workspaces`             | List Workspaces visible to the token. Use when you don't yet know which Workspace to bind.                                                                                             |
+| `list_products`               | List Products. With a Workspace binding, returns its member Products; without, returns orphan Products.                                                                                |
+| `read_workspace`              | Workspace metadata: name, description, type, archived state.                                                                                                                           |
+| `read_product`                | Product metadata: name, description, `specificationManagementType`, member-of Workspace.                                                                                               |
+| `list_specifications`         | List specs in scope. Filters: `type` (BUSINESS / UX / DESIGN_SYSTEM / DOCUMENT), `status` (DRAFT / GENERATING / NEEDS_REVIEW / REVIEWED), `folder`, `tags`, `query`. Cursor-paginated. |
+| `search_specifications`       | Lexical full-text search across spec titles and content. Workspace bindings search the Workspace plus every member Product; results carry a `scope` discriminator.                     |
+| `read_specification`          | Current Markdown body of a spec, plus status and OCC `version`. Use `format="rendered"` to strip open-question and assumption markers.                                                 |
+| `list_specification_versions` | Reviewed snapshots of a spec, newest first.                                                                                                                                            |
+| `read_specification_version`  | Full Markdown of a specific approved revision. Pair with `list_specification_versions` to diff history against current.                                                                |
+| `list_open_questions`         | Questions and assumptions attached to a spec. Resolved/dismissed items are excluded unless `includeResolved=true`.                                                                     |
+
+### Write tools
+
+| Tool                           | Purpose                                                                                                                                                                                                  |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start_new_version`            | Open a new Draft of a Reviewed spec. Required before any write tool on a published spec. No-op when the spec is already a Draft (returns `hint="already_draft"`).                                        |
+| `update_specification_content` | Replace the full Markdown body of a Draft. OCC-guarded — pass the `version` from your most recent `read_specification`. Returns `STALE_VERSION` (409) if another writer landed first; re-read and retry. |
+| `update_specification_section` | Replace one heading-bound section (`sectionPath="## Pricing"`). OCC-guarded. Records a before-image revision.                                                                                            |
+| `request_review`               | Move a Draft to `Needs Review` for a human to approve. Rejected with `OPEN_QUESTIONS_PRESENT` if questions remain — surface them to the user first.                                                      |
+| `discard_draft`                | Roll a Draft (or Needs Review) back to its last approved version. Rejected on specs that have never been approved.                                                                                       |
+| `create_free_specification`    | Create a new Markdown spec in the bound Free product. Path uniqueness is enforced. Rejected with `PRODUCT_TYPE_MISMATCH` on Web Application Products — use `start_new_version` on a structured spec.     |
+
+> **Note** — the agent never calls "mark reviewed". Approval stays a human action in the Xpec UI. The MCP can only nudge a draft to `Needs Review`.
+
+## 🛟 Tips
+
+### Add a rule
+
+Once installed, tell your agent to consult Xpec before writing code. Drop this into `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, or your client's equivalent:
+
+```
+Before writing or updating code, planning a feature, or making an architectural
+choice, search and read the relevant Xpec specs via the xpec
+MCP. Treat them as the source of truth. If a spec is wrong or incomplete, open
+a draft (start_new_version), update it (update_specification_section), and
+request review (request_review) before implementing. Never duplicate spec
+content into the repo.
+```
+
+The repo's `CLAUDE.md` is a good place for project-specific guidance.
+
+### Use ids when you have them
+
+If you already know the spec id, pass it directly to skip the search:
+
+```
+Read the "auth/password-reset" spec and reconcile §4 with the current
+src/server/auth/reset.ts implementation. specId=spec_01H…
+```
+
+### Self-hosted / dev API
+
+Override the API base URL at the binding:
+
+```json
+{
+  "apiUrl": "http://localhost:3000",
+  "workspaceId": "ws_local_dev",
+  "productId": "prd_local_dev"
+}
+```
+
+`http://localhost` is allowed without `--allow-insecure`. For any other non-HTTPS host, pass `--allow-insecure` (intended for self-hosted dev only).
+
+### HTTPS proxy
+
+Standard `https_proxy` / `HTTPS_PROXY` env vars are honoured.
+
+## 💻 Development
+
+```bash
+# From the monorepo root
+npm install
+npm run build
+```
+
+Run the built server:
+
+```bash
+XPEC_API_TOKEN=YOUR_TOKEN node dist/cli.js
+```
+
+### CLI Arguments
+
+`xpec-mcp` accepts:
+
+- `serve` _(default)_ — run the MCP server. Stdio unless `--http` is set.
+- `--check` — verify token + API URL and exit `0`/`1`. Pair with `--json` for scripting.
+- `--help`, `-h` — usage.
+- `--stdio` — run over stdio (default; for desktop agents).
+- `--http` — run as an HTTP/SSE server (for hosted agents).
+- `--port <n>` — port for `--http` (default `3030`).
+- `--host <addr>` — host for `--http` (default `127.0.0.1`).
+- `--cors-origin <o>` — origin to allow (repeatable). Without this, cross-origin browser requests are rejected.
+- `--api-url <url>` — override the Xpec API base URL.
+- `--allow-insecure` — permit a non-HTTPS `apiUrl` (self-hosted dev only).
+
+### Environment Variables
+
+| Variable            | Purpose                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| `XPEC_API_TOKEN`    | **Required.** Personal Access Token from `/settings/developer`. |
+| `XPEC_API_URL`      | Override the API base URL. Default `https://xpec.app`.          |
+| `XPEC_WORKSPACE_ID` | Default Workspace binding when no `.xpec.json` is present.      |
+| `XPEC_PRODUCT_ID`   | Default Product binding when no `.xpec.json` is present.        |
+| `XPEC_TELEMETRY`    | Set to `0` to disable anonymous telemetry.                      |
+| `XPEC_LOG_LEVEL`    | `debug` \| `info` \| `warn` \| `error` (default `info`).        |
+
+The `--api-url` CLI flag takes precedence over `XPEC_API_URL`. The `.xpec.json` `apiUrl` field falls between the two.
+
+### Testing with MCP Inspector
+
+```bash
+XPEC_API_TOKEN=YOUR_TOKEN \
+  npx -y @modelcontextprotocol/inspector npx @nextfreelatech/xpec-mcp
+```
+
+## 🚨 Troubleshooting
+
+**`AUTH_REQUIRED` / 401 from every tool** — token is missing, expired, or revoked. Mint a new one at `/settings/developer` and update your client's `env`.
+
+**`PRODUCT_NOT_BOUND` / `WORKSPACE_NOT_BOUND`** — the tool needs a binding the session doesn't have. Either pass `productId` / `workspaceId` explicitly, or add it to `.xpec.json` (see [Binding the workspace](#binding-the-workspace)).
+
+**`STALE_VERSION` from `update_specification_*`** — another writer landed between your read and your write. Re-call `read_specification` to get the current `version`, then retry.
+
+**`OPEN_QUESTIONS_PRESENT` from `request_review`** — call `list_open_questions` first, resolve them in the spec, then retry.
+
+**Legacy `.xpec.json` shape rejected at startup** — the binding format changed; the CLI prints a remediation pointing to the new shape. Update the file.
+
+**`ERR_MODULE_NOT_FOUND` under `npx`** — try `bunx` instead. It often resolves stale npm caches.
+
+**Plain-HTTP `apiUrl`** — only `localhost` / `127.0.0.1` / `::1` are allowed by default. For any other host, pass `--allow-insecure` (self-hosted dev only).
+
+## 📄 License
+
+[Apache License 2.0](./LICENSE) © Nextfreela Tech.