@systemdox/mcp-server 0.1.48 → 0.1.50

package/README.md

@@ -113,17 +113,19 @@ npx @systemdox/mcp-server setup
 
 | Variable | Required | Default | Purpose |
 |----------|----------|---------|---------|
-| `SYSTEMDOX_API_KEY` | yes | — | Your SystemDox API key |
+| `SYSTEMDOX_API_KEY` | no | the key in `~/.claude/systemdox/credentials.json` | Your SystemDox API key. `setup` stores it in `~/.claude/systemdox/credentials.json` and nowhere else, so the server reads it there when this is not set |
+| `SYSTEMDOX_WORKSPACE` | no | — | The workspace whose key to read when `credentials.json` holds several |
 | `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_plan_board`, `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_planning_context`, `get_plan_board`, `get_change`, `get_context`,
+`get_project_rules`, `get_prompt_templates`, `get_team_setup`, `get_document_links`,
+`trace_document_path`, `get_graph_stats`. Write: `create_check`,
+`update_spec`, `report_decision`, `create_project_rule`,
+`create_prompt_template`. Write tools require an API key with `editor`+ role.
 
 Skills (ADR-216): `publish_skill`, `list_skills`, `install_skill`. A Claude
 Code skill folder (`SKILL.md` plus its references and scripts) is published
@@ -140,6 +142,34 @@ npx -y @systemdox/mcp-server install-skill <name> [--version n] [--target dir] [
 Exit codes: `0` installed, `1` usage / no key / API error, `2` refused because
 files there were edited.
 
+### What every session is told (ADR-223)
+
+Installing this server is enough for a computer to know what its team uses. When
+a session connects, the server answers with `instructions`, which Claude Code puts
+in the session's system prompt with no tool call:
+
+- the workspace, and to call `get_context` before writing code;
+- each skill your team put in the team setup, with when to use it;
+- what this computer lacks. A missing or older skill is installed with
+  `install_skill`, which writes files and runs nothing. A file you edited is never
+  replaced, and a folder that did not come from SystemDox is left alone.
+
+Hooks, MCP servers, team instructions and memory run or load by themselves, so they
+still wait for you: `setup`, in your own terminal, below. An agent never answers its
+prompts. So does a team skill that is not plain (anything in its frontmatter beyond a
+name and a description, files outside its own folders, or a `!`-command) or that sits
+outside the default space: a session is told its name and not to install it. A skill may
+not hold `.claude-plugin/`, which would make it a plugin. The hosted server cannot see
+your disk, so it says how to check.
+
+**`get_team_setup`** (both servers, read-only) answers the same question in full:
+every skill, hook command and MCP server, and on your own computer what is missing
+and what to do. Use it with a client that does not surface `instructions`.
+
+If this computer has no key, or SystemDox refuses it, the server still connects and
+tells the session what to do. See the words a session gets in the console, under
+**Docs › Team setup › What every session is told**.
+
 ### Team setup (ADR-217)
 
 Your workspace's Claude Code setup (hooks, MCP servers, agents, commands, the
@@ -172,8 +202,10 @@ One command sets up your computer, and the same command updates it:
 npx -y @systemdox/mcp-server setup [--project <name>] [--dir <checkout>] [--yes] [--overwrite]
 ```
 
-- It first writes the SystemDox MCP server into your AI tool's config, as it
-  always has. Then, when your workspace has anything published, it checks that
+- It first writes the SystemDox MCP server into your AI tool's config, without
+  your key: the key is stored once, in `~/.claude/systemdox/credentials.json`
+  (readable by you alone), and a key an earlier `setup` wrote into that config
+  is removed from it. Then, when your workspace has anything published, it checks that
   Claude Code is 2.1.316 or later (`claude update` otherwise) and shows you
   everything it will add: the marketplace entry for `~/.claude/settings.json`,
   the plugin with every hook command and every MCP server's command or URL
@@ -181,9 +213,7 @@ npx -y @systemdox/mcp-server setup [--project <name>] [--dir <checkout>] [--yes]
   its file count and folder, and the `autoMemoryDirectory` it will set. On an
   update it shows only what changed, with a line diff for hooks and
   instructions. Nothing changes until you answer `y`.
-- Then, in this order: your key goes into
-  `~/.claude/systemdox/credentials.json` (readable by you alone, and nowhere
-  else); the team instructions into `~/.claude/systemdox/<workspace>/CLAUDE.md`
+- Then, in this order: the team instructions into `~/.claude/systemdox/<workspace>/CLAUDE.md`
   (if you edited that file, it stops unless `--overwrite`); one marked import
   block into `~/.claude/CLAUDE.md`; one `extraKnownMarketplaces` entry,
   `systemdox-<workspace>`, into `~/.claude/settings.json` (nothing else in
@@ -255,6 +285,18 @@ Both read your key from `SYSTEMDOX_API_KEY`, then from
 alone). A key is never written into a settings file, a plugin entry or a
 command line.
 
+### `get_change` (ADR-218)
+
+`get_change { repo, slug }` reads one change, a `specs/changes/<slug>/` folder
+of a connected repository, as SystemDox last synced it from GitHub: each part
+of its brief (decision, contract, behaviour, plan) and its release with its
+state and pull request, the contract files, every scenario as
+`id · state · title`, the plan and the release pull requests, then the change
+as JSON. The last line is `The brief is passed` or
+`The brief is not passed: <part> is <state>`: a build session calls it first
+and stops on the second. A change the key may not read answers
+`No such change <repo>/<slug>`, as one that does not exist.
+
 ### `get_context`
 
 The aggregator. It ranks checks, specs and docs against the task, then
@@ -293,7 +335,7 @@ 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/cli.ts` (`setup` command: `src/setup-mcp.ts`, then `src/setup-team.ts`). 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.