wikijs-mcp-server-cahaseler/AGENTS.md

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).