# Agent Instructions

## Documentation consistency (hard rule)

Documentation must never contradict the code:

- **Check before you write.** Before changing or adding any doc, verify every claim
  (commands, binaries, tool names, env vars, parameters, tool counts) against the
  actual state of `package.json`, `src/` and the build output. No stale instructions.
- **Code and docs change in the same commit.** Every change that alters the public
  surface — tools added/removed, env vars, CLI flags, binary names, npm scripts,
  dependency majors — must update `README.md`, `AGENTS.md` (tool list) and
  `env.example` in the same change.
- **No fragile line-number references.** Cite files and symbols, not line ranges
  (they go stale with every edit).
- **Commands must be copy-paste runnable.** Example commands in docs must work as
  written (correct binary names, required env vars shown). Prefer documenting the
  happy path plus the exact failure mode when a missing env var is required.
- **When in doubt, verify empirically.** Run the command in the docs before
  committing it (`--version` smoke, or a dry call), the same way code is verified.

## Project overview

Model Context Protocol (MCP) server bridging AI assistants with WikiJS v2.5
instances (GraphQL API). Three-layer architecture:

1. **MCP layer** (`src/mcp/`) — `WikiJSMcpServer` manages lifecycle and tool
   registration in `src/mcp/index.ts`; each tool is a module in `src/mcp/tools/`.
2. **WikiJS client layer** (`src/wikijs/`) — `WikiJSClient` wraps GraphQL
   operations via the codegen SDK; queries in `src/wikijs/queries/pages.graphql`;
   generated types in `src/wikijs/generated/` (`schema-types.ts` + `graphql.ts`).
3. **Entry point** (`src/index.ts`) — config from environment, transport selection
   (`stdio` default or Streamable HTTP via `WIKIJS_MCP_TRANSPORT=http` /
   `--transport http`, implemented in `src/transport/http.ts`), `--version`
   flag for smoke tests.

### Tool pattern

Every tool in `src/mcp/tools/` exports:
- `PARAMETERS` — Zod schema for runtime validation
- `createTool(wikiClient)` — returns the `ToolCallback` handler

Registration order and the `WIKIJS_ENABLE_EDIT` write-gate live in
`src/mcp/index.ts`. Write tools (`create_page`, `edit_page`, `move_page`,
`delete_page`, `restore_page_version`, `convert_page_editor`) are only
registered when edits are enabled.

## Commands

This repo is manageable with either pnpm or npm; **pnpm is primary**.
Both lockfiles are committed (`pnpm-lock.yaml` for pnpm, `package-lock.json`
for the npm-based GitHub CI workflows — they were not migrated).

| Task | pnpm | npm equivalent |
|---|---|---|
| install | `pnpm install` | `npm install` / `npm ci` (CI) |
| build | `pnpm build` | `npm run build` |
| lint | `pnpm lint` | `npm run lint` |
| test | `pnpm test` | `npm test` |
| codegen | `pnpm codegen` | `npm run codegen` |
| run local | `node build/index.js` | same |

Run the compiled server: `WIKIJS_URL=... WIKIJS_API_KEY=... node build/index.js`.
The built server also auto-loads a `.env` from the current working directory
(dotenv); environment variables take precedence over `.env` values.
Note: the package's own bin `wikijs-mcp-edit` is only installed for
*consumers* of the published package — package managers do not link the
root package's own bin into `node_modules/.bin`, so `pnpm exec wikijs-mcp-edit`
does not work from the repo itself.

### pnpm supply-chain policy (`pnpm-workspace.yaml`)

- `minimumReleaseAge: 7200` — dependencies (incl. transitive) must be at
  least 5 days old; resolution fails otherwise
  (`ERR_PNPM_NO_MATURE_MATCHING_VERSION`), it does not silently fall back.
- `allowBuilds` explicitly denies `@parcel/watcher` and `unrs-resolver`
  postinstall scripts (both optional; lint/build/test pass without them).
- npm has no equivalent of `minimumReleaseAge` — for manual version bumps
  the 5-day review rule still applies.

## Environment variables

- `WIKIJS_URL` — Wiki.js base URL without `/graphql` (required)
- `WIKIJS_API_KEY` — Bearer token from Admin → API Access (required)
- `WIKIJS_ENABLE_EDIT` — `true` enables the write tools (default off)
- `WIKIJS_DEFAULT_LOCALE` — only used for URL building; the `create_page`
  zod default for `locale` is hardcoded `'en'` (known asymmetry, see
  `src/mcp/tools/createPage.ts`)
- `WIKIJS_MCP_TRANSPORT` — `stdio` (default) or `http` (Streamable HTTP
  listener for containers/servers; `--transport` CLI flag overrides)
- `WIKIJS_MCP_HOST` — bind address; **required (no default) when transport is
  `http`** — startup fails otherwise
- `WIKIJS_MCP_PORT` — HTTP listener port (default `3001`)
- `WIKIJS_MCP_BEARER_TOKEN` — bearer auth for the HTTP listener; **required
  for non-loopback binds** (loopback = `127.0.0.1`, `localhost`, `::1`),
  startup fails otherwise. Optional only on loopback.

`.env` is loaded via dotenv; copy `env.example` as template.

## Type safety

- TypeScript strict, `NodeNext` module resolution — relative imports need
  `.js` extensions in source files.
- Generated types are committed; do not hand-edit `src/wikijs/generated/`
  (eslint ignores it).
- Zod schemas validate tool parameters at runtime (zod v4).