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, stdio transport, --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

Command	Purpose
npm run build	tsc compile to build/
npm run lint / npm run lint:fix	eslint (flat config, eslint.config.js)
npm test	jest with ts-jest ESM preset (needs NODE_OPTIONS='--experimental-vm-modules', set by the script)
npm run codegen	regenerate GraphQL types; introspects ${WIKIJS_URL}/graphql (needs WIKIJS_URL reachable, runs via dotenv)
make build / make clean	build / remove build/
docker-compose up -d	local WikiJS + PostgreSQL on http://localhost:3000

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)

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