# OPL Docs MCP Server

Codex skills for searching and managing a Grounded Docs documentation index.

- `$docs-search` lists indexed libraries, searches documentation, and resolves versions.
- `$docs-manage` indexes documentation from URLs or local files, refreshes content, and removes indexed libraries or versions.

The skills call the upstream [`@arabold/docs-mcp-server`](https://github.com/arabold/docs-mcp-server) CLI through `npx`.

## Install

Clone this repository, then register and install its marketplace:

```sh
codex plugin marketplace add /absolute/path/to/opl-docs-mcp-server
codex plugin add opl-docs-mcp-server@opl-docs-mcp-server
```

Use the plugin in a new Codex thread. For example:

```text
Use $docs-search to find React useEffect cleanup documentation.
Use $docs-manage to index https://react.dev/reference/react as react version 19.0.0.
```

The skill commands require Node.js 22 or newer and `npx`. Follow the upstream project instructions to configure its documentation store and embedding provider.

## Development

Use Node.js 24 or newer for the repository driver.

```sh
npm run test:contract -- --plugin opl-docs-mcp-server
npm run test:unit -- --plugin opl-docs-mcp-server
npm run verify
npm run test:installed -- --plugin opl-docs-mcp-server
npm run eval:smoke -- --plugin opl-docs-mcp-server --skill docs-search
npm run eval:smoke -- --plugin opl-docs-mcp-server --skill docs-manage
```

`plugins/opl-docs-mcp-server/` contains shipping files. `tests/evals/cases/` contains six retained direct, indirect, and negative activation cases. `tools/` contains the validation driver and native Codex command resolver.

`verify` runs deterministic contract checks and reports the applicable checks. `test:installed` installs into a separate persistent Codex home and compares every installed file with source. `release:verify` also runs the installed checkpoint and all behavioral cases.

The Codex CLI is required for installed checks and behavioral evaluations. Set `CODEX_BIN` to select its executable. Set `OPL_PLUGIN_DEV_STATE` to select persistent test state; the default is `~/.local/state/opl-docs-mcp-server/codex`. Evaluations use a separate authoring home, read-only sandbox, `gpt-6-sol` with high reasoning effort, and save receipts under `.work/eval-results/`. Authentication or sandbox failures are reported as failures.

## License

MIT. The included skills derive from Andre Rabold's [Docs MCP Server](https://github.com/arabold/docs-mcp-server). The upstream copyright and license notice are preserved in [LICENSE](LICENSE).