ojs-mcp 0.2.0__tar.gz

ojs_mcp-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# venv / uv
+.venv/
+venv/
+.python-version
+
+# documentation (MkDocs build)
+site/
+
+# tests / tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local credentials (the repository is public; the project is configured
+# exclusively through environment variables — see docs/installation.md).
+# `.env*` (not a bare `.env`), to also catch `.env.local`/`.env.production`.
+.env*
+
+# MCPB bundle built locally (see docs/installation.md, option 2).
+*.mcpb

ojs_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+versioning follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-09-10
+
+### Added
+
+- `demo/` — a throwaway OJS 3.5 stack (Docker: OJS 3.5.0-5 + MariaDB)
+  with fictional seed content, plus two MCP clients that launch the
+  server over stdio and drive it: `demo/check_api.py` for the sixteen
+  read tools and the `ojs_request` escape hatch, `demo/check_writes.py`
+  for the five write tools. Every tool has now been exercised against a
+  live OJS instance, the write tools by reading back the resulting state
+  (announcement created, metadata edited, a submission moved to
+  production by two editorial decisions, published, unpublished).
+- A regression test for `python -m ojs_mcp.server`.
+
+### Fixed
+
+- `python -m ojs_mcp.server` silently did nothing: the module had no
+  `__main__` block, so it defined `main()` and exited. An MCP client
+  launched that way saw only the stdio pipe close, and reported a bare
+  connection error.
+
+### Documentation
+
+- Authentication: a web server that does not forward the `Authorization`
+  header to PHP (Apache's default, including in the official
+  `pkpofficial/ojs` Docker images) makes OJS refuse every token with a
+  401 that is byte-for-byte identical to an anonymous refusal. Documented
+  the symptom, how to tell it apart from a missing journal role, and the
+  one-line fix.
+- Status: the README no longer describes the project as unverified
+  against a live instance, because every tool now has been. What remains
+  unverified is named instead: login/password authentication, network
+  mode (`OJS_MCP_TRANSPORT=http`), and OJS 3.6.
+
+## [0.1.0] — 2026-09-09
+
+First release.
+
+### Added
+
+- An MCP server for the authenticated Open Journal Systems REST API
+  (OJS 3.5/3.6) — sixteen read tools (submissions, publications, issues,
+  sections, users, reviewers, statistics, DOI, identity, and journal
+  catalog) plus the `ojs_request` escape hatch below (seventeen always
+  registered in total), and five write tools (editorial decisions,
+  publication metadata editing, publish/unpublish, announcements)
+  registered only when `OJS_ALLOW_WRITES=1` is explicitly set.
+- The `ojs_request` escape hatch for calling any OJS REST API endpoint
+  outside the curated tool list, with path validation and (without
+  writes enabled) restriction to read requests.
+- Two authentication strategies: an API token (`OJS_API_TOKEN`) and
+  login/password form authentication (`OJS_USERNAME`/`OJS_PASSWORD`)
+  with CAPTCHA/ALTCHA and forced-password-change detection, session CSRF
+  token management, and automatic retry after session expiry.
+- Multi-instance support: a single binary serves any OJS deployment via
+  `OJS_BASE_URL`, with support for multiple journals on one instance
+  (the `journal` parameter, the `list_journals` tool).
+- Network mode `OJS_MCP_TRANSPORT=http` (streamable HTTP) to host a
+  single process for many users at once, each with their own OJS token
+  passed in the request header — the server stores no client
+  credentials at all; with `Origin` validation
+  (`OJS_MCP_ALLOWED_ORIGINS`) protecting against DNS rebinding.
+- An MCPB bundle (`.mcpb`) for one-click installation in desktop MCP
+  clients, and a PyPI release via OIDC.
+- Full documentation (installation, configuration, authentication, tool
+  list, multi-tenant hosting) published with MkDocs Material.
+
+[0.1.0]: https://github.com/mpasternak/ojs-mcp/releases/tag/v0.1.0

ojs_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Pasternak <michal.dtz@gmail.com>
+
+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.

ojs_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: ojs-mcp
+Version: 0.2.0
+Summary: MCP server for the authenticated Open Journal Systems REST API (OJS 3.5/3.6)
+Project-URL: Homepage, https://github.com/mpasternak/ojs-mcp
+Project-URL: Repository, https://github.com/mpasternak/ojs-mcp
+Project-URL: Documentation, https://mpasternak.github.io/ojs-mcp/
+Project-URL: Issues, https://github.com/mpasternak/ojs-mcp/issues
+Project-URL: Changelog, https://github.com/mpasternak/ojs-mcp/blob/main/CHANGELOG.md
+Author-email: Michał Pasternak <michal.dtz@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,llm,mcp,ojs,open-journal-systems,pkp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: starlette>=0.27
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# ojs-mcp
+
+[![tests](https://github.com/mpasternak/ojs-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/mpasternak/ojs-mcp/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/ojs-mcp.svg)](https://pypi.org/project/ojs-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mpasternak/ojs-mcp/blob/main/LICENSE)
+
+An [MCP](https://modelcontextprotocol.io/) server for the authenticated
+REST API of [Open Journal Systems](https://pkp.sfu.ca/ojs/) (OJS
+3.5/3.6). Connected to an MCP client (Claude Desktop, Claude Code, and
+others), it gives the model access to a journal's submissions, reviews,
+issues, and editorial statistics — and, with writes explicitly enabled,
+also to making editorial decisions, publishing, and editing metadata.
+
+## Verified against a live OJS 3.5
+
+Every tool has been exercised end-to-end against a real OJS 3.5.0-5
+instance — the sixteen read tools, the `ojs_request` escape hatch, and all
+five write tools. The write tools were checked by reading back the state
+OJS actually ended up in, not by trusting the status code: an announcement
+created, publication metadata edited, a submission carried from the
+submission stage to production by two editorial decisions, then published
+and unpublished again.
+
+That instance is reproducible. [`demo/`](https://github.com/mpasternak/ojs-mcp/tree/main/demo)
+holds the Docker stack, the fictional seed content, and the two scripts that
+drive this server against it as a real MCP client — `check_api.py` for the
+read tools, `check_writes.py` for the write tools.
+
+Three things have **not** been exercised against a live server, and still
+rest on what the PKP source (`pkp-lib`, `pkp/ojs`) says rather than on
+observed behavior: login/password authentication
+(`OJS_USERNAME`/`OJS_PASSWORD`), network mode (`OJS_MCP_TRANSPORT=http`),
+and OJS 3.6 — only 3.5 has been tested. The unit test suite likewise runs
+entirely against stubbed HTTP responses (via `respx`).
+
+Writes change real journal data, which is why `OJS_ALLOW_WRITES=1` is off by
+default. Verify each tool's effect on a test journal before pointing it at
+production.
+
+## Quick start
+
+```bash
+OJS_BASE_URL=https://journals.your-university.edu OJS_API_TOKEN=your-token uvx ojs-mcp
+```
+
+No separate install step needed — [`uv`](https://docs.astral.sh/uv/)
+downloads and runs the package on first launch. In practice your MCP
+client calls this command for you, using the configuration format from
+the section below.
+
+## Before you start — this won't work without two things
+
+The OJS REST API has **no anonymous read access**. For the server to be
+able to connect at all, both of these must be true on the OJS instance
+side:
+
+1. **`api_key_secret` set in `config.inc.php`** — without it, API tokens
+   don't work at all (OJS responds with a 500 error to every request
+   that carries a token). This must be done by the OJS server
+   administrator; it can't be worked around from the outside.
+2. **An account with a role in the specific journal** — merely having an
+   OJS account is not enough. Almost every API endpoint requires some
+   role (manager, editor, reviewer...); an account with no role in the
+   given journal gets denied (401) on almost every call.
+
+A third condition applies to instances served by Apache — including the
+official `pkpofficial/ojs` Docker images: the web server must forward the
+`Authorization` header to PHP. Apache does not do that on its own, and when
+it doesn't, OJS answers 401 to every request carrying a token, with a
+response indistinguishable from an anonymous one. The one-line fix, and how
+to tell this case apart from a genuine permission problem, are in the
+authentication documentation.
+
+Without these conditions the server will start, but every tool that
+reaches into OJS will return an authentication error. Details, including
+the login/password alternative and its limitations, are in
+[docs/authentication.md](https://mpasternak.github.io/ojs-mcp/authentication/).
+
+## Getting a token
+
+A logged-in user generates an API token in their own OJS profile: **User
+Profile → API Key** (only available once the instance administrator has
+set `api_key_secret` — see above). The token acts with that account's
+permissions, so its scope is whatever roles that account holds in the
+given journal.
+
+## Example MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "ojs": {
+      "command": "uvx",
+      "args": ["ojs-mcp"],
+      "env": {
+        "OJS_BASE_URL": "https://journals.your-university.edu",
+        "OJS_JOURNAL": "my-journal",
+        "OJS_API_TOKEN": "paste-your-ojs-profile-token-here"
+      }
+    }
+  }
+}
+```
+
+`OJS_JOURNAL` is optional — leave it out if the instance serves several
+journals and you'd rather pick one with the `journal` parameter on each
+call.
+
+### Where to actually paste this configuration
+
+In Claude Desktop: **Settings → Developer → Edit Config** opens (and, on
+first use, creates) the `claude_desktop_config.json` file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Paste the snippet above under the `mcpServers` key — if the file already
+has other servers configured, add the `"ojs"` key alongside them, don't
+overwrite the whole file — save and restart Claude Desktop. Other
+desktop MCP clients have their own place for this configuration (e.g.
+Claude Code reads it via `claude mcp add` or from an `.mcp.json` file) —
+check their documentation; the shape of the `env` section above is the
+same across all of them.
+
+This step **disappears entirely** when installing from the MCPB bundle
+(see below) — there, the instance address, journal, and token are filled
+in through a form in the client's UI, with no manual JSON editing at
+all. That's a good reason to reach for the bundle instead of `uvx` if
+editing a configuration file by hand isn't your thing.
+
+## Environment variables (summary)
+
+| Variable | Required | Description |
+|---|---|---|
+| `OJS_BASE_URL` | yes | The OJS instance address, exactly as it works in the browser. |
+| `OJS_JOURNAL` | no | The journal shortcut — skips the `journal` parameter on every call. |
+| `OJS_API_TOKEN` | no* | The token from a user's profile. Takes precedence over login/password. |
+| `OJS_USERNAME` / `OJS_PASSWORD` | no* | Form-based login — won't work with reCAPTCHA/ALTCHA. |
+| `OJS_ALLOW_WRITES` | no | `1` exposes the tools that modify journal data (hidden by default). |
+
+`*` — either `OJS_API_TOKEN` **or** the `OJS_USERNAME`/`OJS_PASSWORD`
+pair is required (in `stdio` mode). The full list, including the
+network-mode variables (`OJS_MCP_TRANSPORT` and others), is in
+[docs/configuration.md](https://mpasternak.github.io/ojs-mcp/configuration/).
+
+## Alternative to `uvx`: the MCPB bundle
+
+For desktop MCP clients that support the
+[MCP Bundle (`.mcpb`)](https://github.com/modelcontextprotocol/mcpb)
+format — the installer file is attached to every release under
+[Releases](https://github.com/mpasternak/ojs-mcp/releases). Installation
+happens through the client's UI, configuration through a form instead of
+manual JSON editing; no Python or `uv` installation required — the
+bundle pulls its own dependencies on first run.
+
+## Documentation
+
+Full documentation (installation, configuration, authentication, tool
+list, multi-tenant hosting): **https://mpasternak.github.io/ojs-mcp/**
+
+## License
+
+MIT. See [LICENSE](https://github.com/mpasternak/ojs-mcp/blob/main/LICENSE).

ojs_mcp-0.2.0/README.md

@@ -0,0 +1,163 @@
+# ojs-mcp
+
+[![tests](https://github.com/mpasternak/ojs-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/mpasternak/ojs-mcp/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/ojs-mcp.svg)](https://pypi.org/project/ojs-mcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mpasternak/ojs-mcp/blob/main/LICENSE)
+
+An [MCP](https://modelcontextprotocol.io/) server for the authenticated
+REST API of [Open Journal Systems](https://pkp.sfu.ca/ojs/) (OJS
+3.5/3.6). Connected to an MCP client (Claude Desktop, Claude Code, and
+others), it gives the model access to a journal's submissions, reviews,
+issues, and editorial statistics — and, with writes explicitly enabled,
+also to making editorial decisions, publishing, and editing metadata.
+
+## Verified against a live OJS 3.5
+
+Every tool has been exercised end-to-end against a real OJS 3.5.0-5
+instance — the sixteen read tools, the `ojs_request` escape hatch, and all
+five write tools. The write tools were checked by reading back the state
+OJS actually ended up in, not by trusting the status code: an announcement
+created, publication metadata edited, a submission carried from the
+submission stage to production by two editorial decisions, then published
+and unpublished again.
+
+That instance is reproducible. [`demo/`](https://github.com/mpasternak/ojs-mcp/tree/main/demo)
+holds the Docker stack, the fictional seed content, and the two scripts that
+drive this server against it as a real MCP client — `check_api.py` for the
+read tools, `check_writes.py` for the write tools.
+
+Three things have **not** been exercised against a live server, and still
+rest on what the PKP source (`pkp-lib`, `pkp/ojs`) says rather than on
+observed behavior: login/password authentication
+(`OJS_USERNAME`/`OJS_PASSWORD`), network mode (`OJS_MCP_TRANSPORT=http`),
+and OJS 3.6 — only 3.5 has been tested. The unit test suite likewise runs
+entirely against stubbed HTTP responses (via `respx`).
+
+Writes change real journal data, which is why `OJS_ALLOW_WRITES=1` is off by
+default. Verify each tool's effect on a test journal before pointing it at
+production.
+
+## Quick start
+
+```bash
+OJS_BASE_URL=https://journals.your-university.edu OJS_API_TOKEN=your-token uvx ojs-mcp
+```
+
+No separate install step needed — [`uv`](https://docs.astral.sh/uv/)
+downloads and runs the package on first launch. In practice your MCP
+client calls this command for you, using the configuration format from
+the section below.
+
+## Before you start — this won't work without two things
+
+The OJS REST API has **no anonymous read access**. For the server to be
+able to connect at all, both of these must be true on the OJS instance
+side:
+
+1. **`api_key_secret` set in `config.inc.php`** — without it, API tokens
+   don't work at all (OJS responds with a 500 error to every request
+   that carries a token). This must be done by the OJS server
+   administrator; it can't be worked around from the outside.
+2. **An account with a role in the specific journal** — merely having an
+   OJS account is not enough. Almost every API endpoint requires some
+   role (manager, editor, reviewer...); an account with no role in the
+   given journal gets denied (401) on almost every call.
+
+A third condition applies to instances served by Apache — including the
+official `pkpofficial/ojs` Docker images: the web server must forward the
+`Authorization` header to PHP. Apache does not do that on its own, and when
+it doesn't, OJS answers 401 to every request carrying a token, with a
+response indistinguishable from an anonymous one. The one-line fix, and how
+to tell this case apart from a genuine permission problem, are in the
+authentication documentation.
+
+Without these conditions the server will start, but every tool that
+reaches into OJS will return an authentication error. Details, including
+the login/password alternative and its limitations, are in
+[docs/authentication.md](https://mpasternak.github.io/ojs-mcp/authentication/).
+
+## Getting a token
+
+A logged-in user generates an API token in their own OJS profile: **User
+Profile → API Key** (only available once the instance administrator has
+set `api_key_secret` — see above). The token acts with that account's
+permissions, so its scope is whatever roles that account holds in the
+given journal.
+
+## Example MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "ojs": {
+      "command": "uvx",
+      "args": ["ojs-mcp"],
+      "env": {
+        "OJS_BASE_URL": "https://journals.your-university.edu",
+        "OJS_JOURNAL": "my-journal",
+        "OJS_API_TOKEN": "paste-your-ojs-profile-token-here"
+      }
+    }
+  }
+}
+```
+
+`OJS_JOURNAL` is optional — leave it out if the instance serves several
+journals and you'd rather pick one with the `journal` parameter on each
+call.
+
+### Where to actually paste this configuration
+
+In Claude Desktop: **Settings → Developer → Edit Config** opens (and, on
+first use, creates) the `claude_desktop_config.json` file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Paste the snippet above under the `mcpServers` key — if the file already
+has other servers configured, add the `"ojs"` key alongside them, don't
+overwrite the whole file — save and restart Claude Desktop. Other
+desktop MCP clients have their own place for this configuration (e.g.
+Claude Code reads it via `claude mcp add` or from an `.mcp.json` file) —
+check their documentation; the shape of the `env` section above is the
+same across all of them.
+
+This step **disappears entirely** when installing from the MCPB bundle
+(see below) — there, the instance address, journal, and token are filled
+in through a form in the client's UI, with no manual JSON editing at
+all. That's a good reason to reach for the bundle instead of `uvx` if
+editing a configuration file by hand isn't your thing.
+
+## Environment variables (summary)
+
+| Variable | Required | Description |
+|---|---|---|
+| `OJS_BASE_URL` | yes | The OJS instance address, exactly as it works in the browser. |
+| `OJS_JOURNAL` | no | The journal shortcut — skips the `journal` parameter on every call. |
+| `OJS_API_TOKEN` | no* | The token from a user's profile. Takes precedence over login/password. |
+| `OJS_USERNAME` / `OJS_PASSWORD` | no* | Form-based login — won't work with reCAPTCHA/ALTCHA. |
+| `OJS_ALLOW_WRITES` | no | `1` exposes the tools that modify journal data (hidden by default). |
+
+`*` — either `OJS_API_TOKEN` **or** the `OJS_USERNAME`/`OJS_PASSWORD`
+pair is required (in `stdio` mode). The full list, including the
+network-mode variables (`OJS_MCP_TRANSPORT` and others), is in
+[docs/configuration.md](https://mpasternak.github.io/ojs-mcp/configuration/).
+
+## Alternative to `uvx`: the MCPB bundle
+
+For desktop MCP clients that support the
+[MCP Bundle (`.mcpb`)](https://github.com/modelcontextprotocol/mcpb)
+format — the installer file is attached to every release under
+[Releases](https://github.com/mpasternak/ojs-mcp/releases). Installation
+happens through the client's UI, configuration through a form instead of
+manual JSON editing; no Python or `uv` installation required — the
+bundle pulls its own dependencies on first run.
+
+## Documentation
+
+Full documentation (installation, configuration, authentication, tool
+list, multi-tenant hosting): **https://mpasternak.github.io/ojs-mcp/**
+
+## License
+
+MIT. See [LICENSE](https://github.com/mpasternak/ojs-mcp/blob/main/LICENSE).

ojs_mcp-0.2.0/demo/README.md

@@ -0,0 +1,124 @@
+# Demo OJS instance
+
+A throwaway OJS 3.5 instance with fictional content, so `ojs-mcp` can be
+exercised against a real server instead of stubbed HTTP responses.
+
+Everything in here is disposable: the passwords are in plain sight on
+purpose, all articles and people are invented, and the whole stack is meant
+to be destroyed with `docker compose down -v`.
+
+## Run it
+
+```bash
+cd demo
+./setup.sh                 # ~5 minutes on first run, most of it OJS's installer
+```
+
+`setup.sh` is re-runnable — each step checks whether it already happened —
+and prints the connection details and a ready-to-use API token at the end.
+
+Then drive the MCP server against it:
+
+```bash
+uv sync --extra dev
+OJS_API_TOKEN=<token from setup.sh> .venv/bin/python demo/check_api.py
+```
+
+`check_api.py` is a real MCP client: it launches `ojs-mcp` over stdio the way
+Claude Desktop would, then calls every read tool and prints one line per call.
+
+The write tools have their own script, kept separate because it *changes* the
+journal — it creates an announcement, edits metadata, walks a submission
+through two editorial decisions, publishes it and unpublishes it again,
+reading the state back after each step:
+
+```bash
+OJS_API_TOKEN=<token from setup.sh> .venv/bin/python demo/check_writes.py
+```
+
+It refuses to run against anything but `localhost:8081`. These tools exist to
+modify production journals, and a script that fires all five must not be one
+typo away from doing so.
+
+To wipe it all, including the database:
+
+```bash
+docker compose down -v
+```
+
+`setup.sh` copes with that: the database lives in a Docker volume but
+`config.inc.php` lives on the host, so after `down -v` the config still says
+`installed = On` while the schema is gone. The script notices the mismatch
+and regenerates the config instead of handing you an OJS that answers 500 to
+everything.
+
+## What you get
+
+| | |
+|---|---|
+| Site | <http://localhost:8081> |
+| Journal | <http://localhost:8081/demojournal> |
+| Admin | `admin` / `ojsdemo1234` |
+| Editor | `editor` / `ojsdemo1234` |
+| Reviewers | `reviewer1`, `reviewer2` / `ojsdemo1234` |
+
+Content: one journal, one section, two published issues, six published
+articles with authors, abstracts, keywords and page ranges, two submissions
+still in the editorial workflow (one in external review, one in the
+submission stage), and two review assignments on the one under review — one
+answered with a recommendation, one still pending.
+
+## Files
+
+| File | What it is |
+|---|---|
+| `docker-compose.yml` | OJS 3.5.0-5 + MariaDB 11.4, on port 8081 |
+| `config/ojs.config.inc.php` | OJS config; written to by the installer |
+| `config/pkp.conf` | The image's Apache vhost, plus one added line (see below) |
+| `seed/demo-content.xml` | Two issues and six published articles (native XML) |
+| `seed/demo-submissions.xml` | Two unpublished submissions (native XML) |
+| `seed/demo-users.xml` | Editor and two reviewers (users XML) |
+| `seed/assign-reviewers.php` | Review assignments, via OJS's own repositories |
+| `check_api.py` | MCP client that calls every read tool |
+| `check_writes.py` | MCP client that exercises the five write tools |
+
+## Three things that are not obvious
+
+**Apache does not pass the `Authorization` header to PHP.** Out of the box,
+the official `pkpofficial/ojs` image answers `401` to every request carrying
+a perfectly valid `Authorization: Bearer <token>` — while the same token
+works when passed as `?apiToken=…`. The response body is byte-for-byte
+identical to the anonymous one, so nothing points at the header. The fix is
+one line in the vhost, which is why `config/pkp.conf` exists:
+
+```apache
+SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
+```
+
+`ojs-mcp` only ever sends the header, so without this it cannot talk to this
+image at all. Anyone deploying OJS behind Apache with mod_php needs the same
+line before the REST API will accept tokens.
+
+**OJS has no CLI installer.** PKP's own automation (`pkp-cli-install` in the
+image) is literally `curl` posting the web installer's form back to the same
+container. `setup.sh` does the same thing from the host, so each field is
+visible and the step can be re-run.
+
+**`config.inc.php` is bind-mounted, so `sed -i` inside the container fails.**
+`sed -i` works by renaming, and a bind-mounted file cannot be renamed
+(`Device or resource busy`). The image's entrypoint tries exactly that to set
+`restful_urls`, and silently fails. `setup.sh` therefore edits the file on
+the host before the container ever sees it.
+
+## The API token
+
+OJS signs API tokens as a JWT whose payload is a one-element array holding
+the user's `apiKey`, signed with `api_key_secret` from `config.inc.php`
+(`PKP\user\form\APIProfileForm`). `setup.sh` writes the `apiKey` /
+`apiKeyEnabled` settings for the admin account and encodes the JWT with OJS's
+own vendored library — the same thing the **User Profile → API Key** tab does
+in the browser, minus the clicking.
+
+Without `api_key_secret`, OJS answers `500` to every request that carries a
+token, which looks like an outage rather than a configuration problem. The
+config here has it set before installation.