@sondt2709/wikijs-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sondt2709
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# wikijs-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for managing [Wiki.js](https://js.wiki) 2.x
+pages: search, read, create, update, move, delete, browse version history, and list assets —
+all through the Wiki.js GraphQL API.
+
+## Tools
+
+| Tool                   | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `search_pages`         | Full-text search across pages.                           |
+| `list_pages`           | List pages with ordering, tag, and locale filters.       |
+| `get_page`             | Fetch a page by id or path, including its content.       |
+| `get_page_tree`        | Browse the page hierarchy.                               |
+| `list_tags`            | List all tags, or search tags matching a query.          |
+| `create_page`          | Create a new page.                                       |
+| `update_page`          | Partially update a page by id.                           |
+| `move_page`            | Move/rename a page (requires `manage:pages` permission). |
+| `delete_page`          | Delete a page (destructive).                             |
+| `get_page_history`     | Fetch a page's version history trail.                    |
+| `get_page_version`     | Fetch the content of a specific historical version.      |
+| `restore_page_version` | Restore a page to a prior version.                       |
+| `list_assets`          | List asset folders and files (read-only).                |
+
+## Quick start (stdio)
+
+Add the server to Claude Code with `claude mcp add`:
+
+```bash
+claude mcp add wikijs -e WIKIJS_URL=https://wiki.example.com -e WIKIJS_TOKEN=your-api-key-here -- npx @sondt2709/wikijs-mcp
+```
+
+For Claude Desktop, Cursor, or any other MCP client that reads a JSON config, add:
+
+```json
+{
+  "mcpServers": {
+    "wikijs": {
+      "command": "npx",
+      "args": ["@sondt2709/wikijs-mcp"],
+      "env": {
+        "WIKIJS_URL": "https://wiki.example.com",
+        "WIKIJS_TOKEN": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Getting an API key
+
+1. Log in to your Wiki.js instance as an administrator.
+2. Go to **Administration → API Access**.
+3. Toggle **Enable API** on.
+4. Click **New API Key**, give it a name and expiration, and grant it the permissions
+   your workflow needs (`read:pages` at minimum; `write:pages`, `manage:pages`, and
+   `manage:system` for creating/updating/moving/deleting pages).
+5. Copy the generated token — it's shown only once — and use it as `WIKIJS_TOKEN`.
+
+## Configuration
+
+| Variable / flag             | Default | Description                                                         |
+| --------------------------- | ------- | ------------------------------------------------------------------- |
+| `WIKIJS_URL` / `--url`      | —       | Base URL of your Wiki.js instance (required).                       |
+| `WIKIJS_TOKEN` / `--token`  | —       | API key from Administration → API Access (required).                |
+| `TRANSPORT` / `--transport` | `stdio` | `stdio` or `http`.                                                  |
+| `PORT` / `--port`           | `3000`  | Port to listen on when `TRANSPORT=http`.                            |
+| `LOG_LEVEL` / `--log-level` | `info`  | pino log level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`. |
+
+CLI flags take precedence over environment variables. See `.env.example` for a template.
+
+## HTTP / Docker mode
+
+Run the server as a long-lived streamable-HTTP service instead of stdio — useful for
+sharing one instance across multiple clients, or running behind a reverse proxy.
+
+```bash
+cp .env.example .env   # set WIKIJS_URL and WIKIJS_TOKEN
+docker compose up
+```
+
+This builds the image from the included `Dockerfile` and starts the server with
+`TRANSPORT=http` on port 3000:
+
+- MCP endpoint: `http://localhost:3000/mcp`
+- Health check: `http://localhost:3000/healthz`
+
+Point your MCP client at the `/mcp` endpoint instead of spawning the process directly.
+
+## MCP Inspector
+
+To poke at the server interactively:
+
+```bash
+pnpm inspect
+```
+
+This builds the project and launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+against the stdio transport.
+
+To inspect an HTTP deployment instead, start the server with `docker compose up` (or
+`TRANSPORT=http pnpm dev`), then run `npx @modelcontextprotocol/inspector` on its own and
+connect the Inspector UI to `http://localhost:3000/mcp` using the "Streamable HTTP"
+transport option.
+
+## Development
+
+```bash
+pnpm install       # install dependencies
+pnpm dev           # run from source with --watch
+pnpm lint          # eslint
+pnpm typecheck     # tsc --noEmit
+pnpm format        # prettier --write
+pnpm build         # bundle to dist/
+```
+
+End-to-end tests run against a real, disposable Wiki.js instance in Docker:
+
+```bash
+pnpm e2e:wiki:up       # start local Wiki.js in Docker
+pnpm e2e:bootstrap     # headless setup: admin account + API key + e2e/.env
+pnpm test:e2e          # build + run the e2e suite
+pnpm e2e:wiki:down     # tear down the container and its data
+```
+
+See [`e2e/setup.md`](e2e/setup.md) for details, including a manual setup fallback if
+the bootstrap script fails.
+
+[Lefthook](https://github.com/evilmartians/lefthook) runs `eslint --fix` and `prettier`
+on staged files at `pre-commit`, and `typecheck` + `build` at `pre-push`. It's installed
+automatically via the `prepare` script after `pnpm install`.
+
+## Releasing
+
+Pushing a tag matching `v*` (e.g. `v0.2.0`) triggers `.github/workflows/release.yml`,
+which lints, typechecks, builds, and publishes the package to npm with provenance.
+
+The `NPM_TOKEN` repository secret must be set (an npm automation token with publish
+access to `@sondt2709/wikijs-mcp`) before pushing a release tag, or the workflow will fail at the
+publish step.
+
+## License
+
+[MIT](LICENSE)

package/dist/http-D7MoxUTD.js

@@ -0,0 +1,67 @@
+import { t as buildServer } from "./index.js";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+//#region src/http.ts
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+async function readJsonBody(req) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		total += chunk.length;
+		if (total > MAX_BODY_BYTES) throw new Error(`Request body exceeds ${MAX_BODY_BYTES} byte limit`);
+		chunks.push(chunk);
+	}
+	const raw = Buffer.concat(chunks).toString("utf8");
+	return raw.length === 0 ? void 0 : JSON.parse(raw);
+}
+function startHttpServer(config, logger) {
+	const httpServer = createServer((req, res) => {
+		handle(req, res);
+	});
+	async function handle(req, res) {
+		const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+		if (url.pathname === "/healthz") {
+			res.writeHead(200, { "content-type": "application/json" });
+			res.end(JSON.stringify({ status: "ok" }));
+			return;
+		}
+		if (url.pathname !== "/mcp") {
+			res.writeHead(404, { "content-type": "application/json" });
+			res.end(JSON.stringify({ error: "not found — MCP endpoint is /mcp" }));
+			return;
+		}
+		try {
+			const body = req.method === "POST" ? await readJsonBody(req) : void 0;
+			const server = buildServer(config, logger);
+			const transport = new StreamableHTTPServerTransport({
+				sessionIdGenerator: void 0,
+				enableJsonResponse: true
+			});
+			res.on("close", () => {
+				transport.close();
+				server.close();
+			});
+			await server.connect(transport);
+			await transport.handleRequest(req, res, body);
+		} catch (err) {
+			logger.error({ err: err.message }, "MCP request failed");
+			if (!res.headersSent) {
+				res.writeHead(500, { "content-type": "application/json" });
+				res.end(JSON.stringify({ error: "internal server error" }));
+			} else res.end();
+		}
+	}
+	httpServer.on("error", (err) => {
+		if (err.code === "EADDRINUSE") logger.error({ port: config.port }, `Port ${config.port} is already in use`);
+		else logger.error({ err: err.message }, "HTTP server error");
+		process.exit(1);
+	});
+	httpServer.listen(config.port, () => {
+		logger.info({ port: config.port }, "wikijs-mcp listening on http (streamable), endpoint /mcp");
+	});
+	return httpServer;
+}
+//#endregion
+export { startHttpServer };
+
+//# sourceMappingURL=http-D7MoxUTD.js.map

package/dist/http-D7MoxUTD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-D7MoxUTD.js","names":[],"sources":["../src/http.ts"],"sourcesContent":["import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';\nimport type { Config } from './config.ts';\nimport type { Logger } from './logger.ts';\nimport { buildServer } from './server.ts';\n\nconst MAX_BODY_BYTES = 4 * 1024 * 1024; // 4MB\n\nasync function readJsonBody(req: IncomingMessage): Promise<unknown> {\n  const chunks: Buffer[] = [];\n  let total = 0;\n  for await (const chunk of req) {\n    total += (chunk as Buffer).length;\n    if (total > MAX_BODY_BYTES) {\n      throw new Error(`Request body exceeds ${MAX_BODY_BYTES} byte limit`);\n    }\n    chunks.push(chunk as Buffer);\n  }\n  const raw = Buffer.concat(chunks).toString('utf8');\n  return raw.length === 0 ? undefined : (JSON.parse(raw) as unknown);\n}\n\nexport function startHttpServer(config: Config, logger: Logger): Server {\n  const httpServer = createServer((req, res) => {\n    void handle(req, res);\n  });\n\n  async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);\n\n    if (url.pathname === '/healthz') {\n      res.writeHead(200, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({ status: 'ok' }));\n      return;\n    }\n\n    if (url.pathname !== '/mcp') {\n      res.writeHead(404, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({ error: 'not found — MCP endpoint is /mcp' }));\n      return;\n    }\n\n    try {\n      // Stateless mode: fresh server + transport per request.\n      const body = req.method === 'POST' ? await readJsonBody(req) : undefined;\n      const server = buildServer(config, logger);\n      const transport = new StreamableHTTPServerTransport({\n        sessionIdGenerator: undefined,\n        enableJsonResponse: true,\n      });\n      res.on('close', () => {\n        void transport.close();\n        void server.close();\n      });\n      await server.connect(transport);\n      await transport.handleRequest(req, res, body);\n    } catch (err) {\n      logger.error({ err: (err as Error).message }, 'MCP request failed');\n      if (!res.headersSent) {\n        res.writeHead(500, { 'content-type': 'application/json' });\n        res.end(JSON.stringify({ error: 'internal server error' }));\n      } else {\n        res.end();\n      }\n    }\n  }\n\n  httpServer.on('error', (err: NodeJS.ErrnoException) => {\n    if (err.code === 'EADDRINUSE') {\n      logger.error({ port: config.port }, `Port ${config.port} is already in use`);\n    } else {\n      logger.error({ err: err.message }, 'HTTP server error');\n    }\n    process.exit(1);\n  });\n\n  httpServer.listen(config.port, () => {\n    logger.info({ port: config.port }, 'wikijs-mcp listening on http (streamable), endpoint /mcp');\n  });\n  return httpServer;\n}\n"],"mappings":";;;;AAMA,MAAM,iBAAiB,IAAI,OAAO;AAElC,eAAe,aAAa,KAAwC;CAClE,MAAM,SAAmB,CAAC;CAC1B,IAAI,QAAQ;CACZ,WAAW,MAAM,SAAS,KAAK;EAC7B,SAAU,MAAiB;EAC3B,IAAI,QAAQ,gBACV,MAAM,IAAI,MAAM,wBAAwB,eAAe,YAAY;EAErE,OAAO,KAAK,KAAe;CAC7B;CACA,MAAM,MAAM,OAAO,OAAO,MAAM,CAAC,CAAC,SAAS,MAAM;CACjD,OAAO,IAAI,WAAW,IAAI,KAAA,IAAa,KAAK,MAAM,GAAG;AACvD;AAEA,SAAgB,gBAAgB,QAAgB,QAAwB;CACtE,MAAM,aAAa,cAAc,KAAK,QAAQ;EAC5C,OAAY,KAAK,GAAG;CACtB,CAAC;CAED,eAAe,OAAO,KAAsB,KAAoC;EAC9E,MAAM,MAAM,IAAI,IAAI,IAAI,OAAO,KAAK,UAAU,IAAI,QAAQ,QAAQ,aAAa;EAE/E,IAAI,IAAI,aAAa,YAAY;GAC/B,IAAI,UAAU,KAAK,EAAE,gBAAgB,mBAAmB,CAAC;GACzD,IAAI,IAAI,KAAK,UAAU,EAAE,QAAQ,KAAK,CAAC,CAAC;GACxC;EACF;EAEA,IAAI,IAAI,aAAa,QAAQ;GAC3B,IAAI,UAAU,KAAK,EAAE,gBAAgB,mBAAmB,CAAC;GACzD,IAAI,IAAI,KAAK,UAAU,EAAE,OAAO,mCAAmC,CAAC,CAAC;GACrE;EACF;EAEA,IAAI;GAEF,MAAM,OAAO,IAAI,WAAW,SAAS,MAAM,aAAa,GAAG,IAAI,KAAA;GAC/D,MAAM,SAAS,YAAY,QAAQ,MAAM;GACzC,MAAM,YAAY,IAAI,8BAA8B;IAClD,oBAAoB,KAAA;IACpB,oBAAoB;GACtB,CAAC;GACD,IAAI,GAAG,eAAe;IACpB,UAAe,MAAM;IACrB,OAAY,MAAM;GACpB,CAAC;GACD,MAAM,OAAO,QAAQ,SAAS;GAC9B,MAAM,UAAU,cAAc,KAAK,KAAK,IAAI;EAC9C,SAAS,KAAK;GACZ,OAAO,MAAM,EAAE,KAAM,IAAc,QAAQ,GAAG,oBAAoB;GAClE,IAAI,CAAC,IAAI,aAAa;IACpB,IAAI,UAAU,KAAK,EAAE,gBAAgB,mBAAmB,CAAC;IACzD,IAAI,IAAI,KAAK,UAAU,EAAE,OAAO,wBAAwB,CAAC,CAAC;GAC5D,OACE,IAAI,IAAI;EAEZ;CACF;CAEA,WAAW,GAAG,UAAU,QAA+B;EACrD,IAAI,IAAI,SAAS,cACf,OAAO,MAAM,EAAE,MAAM,OAAO,KAAK,GAAG,QAAQ,OAAO,KAAK,mBAAmB;OAE3E,OAAO,MAAM,EAAE,KAAK,IAAI,QAAQ,GAAG,mBAAmB;EAExD,QAAQ,KAAK,CAAC;CAChB,CAAC;CAED,WAAW,OAAO,OAAO,YAAY;EACnC,OAAO,KAAK,EAAE,MAAM,OAAO,KAAK,GAAG,0DAA0D;CAC/F,CAAC;CACD,OAAO;AACT"}