@systemdox/mcp-server 0.1.11

package/README.md

@@ -0,0 +1,138 @@
+# @systemdox/mcp-server
+
+MCP server that exposes your SystemDox context — checks, specs, docs, tech
+stack, project rules, and prompt templates — to AI coding tools (Claude Code,
+Cursor, and any MCP-compatible client).
+
+There are two ways to run it. Both authenticate with a SystemDox API key
+(generate one on your SystemDox settings page) and act strictly as the caller —
+every tool call is scoped to that key's tenant.
+
+## Option A — Hosted endpoint (no install)
+
+SystemDox hosts the server at a per-tenant subdomain, speaking MCP Streamable
+HTTP. Point any HTTP-capable MCP client at it — nothing to install or update.
+
+```jsonc
+{
+  "mcpServers": {
+    "systemdox": {
+      "type": "http",
+      "url": "https://<your-workspace>.mcp.systemdox.com/mcp",
+      "headers": {
+        "Authorization": "Bearer pweb_prod_key_..."
+      }
+    }
+  }
+}
+```
+
+- **URL** — `https://<your-workspace>.mcp.systemdox.com/mcp`. `<your-workspace>`
+  is your tenant's **slug**; it must match the tenant that owns the API key, or
+  the request is rejected `403`. Set a slug on the workspace first (owner/admin →
+  workspace settings) if you don't have one.
+- **Auth** — the key must be sent as `Authorization: Bearer <key>`. (An
+  `X-API-Key`-only request is rejected at the gateway.)
+- **Transport** — stateless request/response (JSON); each call is independent,
+  which suits serverless hosting. There is no long-lived SSE stream.
+
+## Option B — Local (stdio) via npx
+
+Run the server locally as a stdio subprocess of your MCP client. Useful offline,
+or when you'd rather not depend on the hosted endpoint.
+
+```bash
+npx @systemdox/mcp-server setup
+```
+
+…or configure it directly:
+
+```jsonc
+{
+  "mcpServers": {
+    "systemdox": {
+      "command": "npx",
+      "args": ["@systemdox/mcp-server"],
+      "env": {
+        "SYSTEMDOX_API_KEY": "pweb_prod_key_..."
+      }
+    }
+  }
+}
+```
+
+> The package is published to the public npm registry — `npx` resolves it with no
+> registry configuration and no credentials.
+
+## Environment variables (stdio mode)
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `SYSTEMDOX_API_KEY` | yes | — | Your SystemDox API key |
+| `SYSTEMDOX_API_URL` | no | `https://api.puglieseweb.com/systemdox` | REST API base URL |
+| `SYSTEMDOX_CACHE_TTL` | no | `300` | Response cache TTL (seconds) |
+
+## Tools
+
+Read: `get_checks`, `get_specs`, `get_docs`, `get_tech_stack`,
+`get_planning_context`, `get_context`, `get_project_rules`,
+`get_prompt_templates`. Write: `create_check`, `update_spec`,
+`report_decision`, `create_project_rule`, `create_prompt_template`. Write tools
+require an API key with `editor`+ role.
+
+### `get_context`
+
+The aggregator. It ranks checks, specs and docs against the task, then
+spends the token budget **fetching the bodies** of the highest-ranked specs and
+docs (`/v1/specs/{id}`, `/v1/docs/{id}/content`) — concurrently, clipped to a
+fair share of what's left. Every item carries the `spec_id` / `doc_id` needed to
+fetch it in full, so nothing is a dead end: items whose body did not fit, or
+whose fetch failed, still appear as a title + ID. Tech stack and project rules
+are always included; the budget is spent on bodies, never on truncating the
+list. Retrieval quality is measured by `eval/` — see [eval/README.md](./eval/README.md).
+
+### Deprecated tool names
+
+`get_guardrails` and `create_guardrail` were renamed to `get_checks` and
+`create_check`. **The old names still work.** They are registered as aliases of
+the same handlers and accept the same arguments, so an `.mcp.json` or agent
+permission allowlist that pins them keeps working unchanged.
+
+| Old name | New name | Removed no earlier than |
+|----------|----------|-------------------------|
+| `get_guardrails` | `get_checks` | 2027-01-31 |
+| `create_guardrail` | `create_check` | 2027-01-31 |
+
+Removal also requires usage telemetry showing no calls against the old name.
+The `/guardrails/*` REST routes are **not** deprecated and are not changing.
+
+## Development
+
+```bash
+pnpm install         # from the monorepo root (pnpm workspace)
+pnpm --filter @systemdox/mcp-server build       # tsup + tsc
+pnpm --filter @systemdox/mcp-server test        # unit tests (node:test)
+pnpm --filter @systemdox/mcp-server test:http   # offline handler smoke test
+pnpm --filter @systemdox/mcp-server eval        # get_context retrieval eval
+node scripts/mcp-release-gate.mjs               # from the monorepo root
+```
+
+Entry points: `src/index.ts` (stdio), `src/http.ts` (hosted HTTP handler),
+`src/cli.ts` (`setup` command). Tool registration is shared via
+`src/server.ts` (`createServer`). The hosted handler is deployed as a Lambda by
+the product-systemdox backend stack (`systemdox-backend-prod`), reached through
+the `*.mcp.systemdox.com` custom domain.
+
+## Publishing
+
+`.github/workflows/mcp-server-publish.yml` publishes to **registry.npmjs.org**
+under the public `@systemdox` scope, authenticating with the `NPM_TOKEN` repo
+secret. The publish step uses a throwaway npmrc containing only the public
+registry: the repo-root `.npmrc` maps `@puglieseweb` to GitHub Packages (needed
+for *installing* the org's private packages) and must never leak into a publish
+of this package — that is how it previously landed in a private registry that
+`npx` 404s for every customer.
+
+`scripts/mcp-release-gate.mjs` is the standing guard: it reads the install
+command out of the product source and runs it against the public registry with
+no org credentials.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};