Content
# WebCenter Content MCP Server
[](LICENSE)
[](https://modelcontextprotocol.io)
Model Context Protocol server for Oracle WebCenter Content. Built for **agent teams**: deterministic, scope-gated, auditable, and shaped around the consolidated tool surface that MCP best practices call for.
> **v2.0** is a complete rewrite of the year-old v1 code. See [`docs/MIGRATING-FROM-V1.md`](docs/MIGRATING-FROM-V1.md) for the upgrade walkthrough.
## What you get
- **16 consolidated tools** + a workflow-tool framework (replacing the 59 endpoint-shaped tools of v1). See the generated [`docs/api/ENDPOINTS.md`](docs/api/ENDPOINTS.md).
- **Three role-pack prompts** — curator, auditor, migrator — pre-shape agents for the common workflows.
- **OAuth 2.1 everywhere**: MCP-RS inbound (RFC 9728 + RFC 8707 audience binding), WCC OAuth outbound (PKCE + rotated refresh), Basic Auth fallback for on-prem WCC.
- **Streamable HTTP transport** per the MCP 2025-06-18 spec, plus stdio for desktop clients.
- **Four distribution channels** wired in the release pipeline — npm, Claude Desktop Extension (DXT), Electron app, signed multi-arch Docker image (published when a release is cut).
- **Audit log** (stderr JSON-lines) on every tool call, token validation, consent decision, and transport rejection.
- **531 tests** across unit / integration / architecture / security / eval projects. Architecture guards forbid duplicate-dispatch growth and forbid bundling any LLM SDK.
## Quick start
> **Pre-release.** `v2.0.1` is tagged but **not yet published** to npm, the GitHub
> Container Registry, or the Releases page. Run it **from source** today; the
> npm / DXT / Electron / Docker channels light up once a release is published.
### Run from source
```sh
git clone https://github.com/JohnRSim/webcenter-content-mcp-server.git
cd webcenter-content-mcp-server
pnpm install
pnpm build
```
Point Claude Desktop at the built entrypoint:
```jsonc
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"webcenter": {
"command": "node",
"args": ["/absolute/path/to/webcenter-content-mcp-server/dist/bin/wcc-mcp.js"],
"env": {
"WCC_BASE_URL": "https://wcc.example.com/documents/wcc/api/v1.1",
"WCC_USER": "svc",
"WCC_PASSWORD": "...",
},
},
},
}
```
Or run the Streamable HTTP transport directly — `node dist/bin/wcc-mcp.js --http`
(listens on `127.0.0.1:3999`).
### Once `v2.0.1` is published
The release pipeline (`.github/workflows/release.yml`) produces four channels:
- **npm** — `npx -y webcenter-content-mcp-server` as the Claude Desktop `command`.
- **DXT** — install the `wcc-mcp.dxt` bundle (a GitHub Release asset) into Claude Desktop.
- **Electron app** — signed desktop installers (Windows / macOS / Linux) on the Releases page.
- **Docker** — `ghcr.io/johnrsim/wcc-mcp-server` for hosted deployments.
Full step-by-step for every path — configuration, auth, troubleshooting — is in
**[`docs/USAGE.md`](docs/USAGE.md)**. Reference deployment manifests and operator
runbooks: [`deploy/`](deploy/), [`docs/operators/`](docs/operators/).
## Tool surface (summary)
| Tool | Purpose |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `wcc_doc_search` | Full-text + metadata search (auto-wraps plain text in `<qsch>`). |
| `wcc_doc_get` | Fetch metadata by `dDocName` or `dID`; concise or detailed. |
| `wcc_doc_download` | Stream a document by revision; respects `PathPolicy`. |
| `wcc_doc_write` | Create, replace, or update metadata (discriminated `action`). |
| `wcc_doc_lifecycle` | Delete, check-out, reverse check-out, expire. |
| `wcc_doc_storage` | Storage-tier updates + restore-from-archive. |
| `wcc_doc_capabilities` | Test allowed operations for the current credentials. |
| `wcc_folder_browse` | List children, list files, get capabilities. |
| `wcc_folder_write` | Create / move / delete folders. |
| `wcc_public_links` | Public-link CRUD. |
| `wcc_application_links` | Application-link CRUD. |
| `wcc_workflow` | Workflow CRUD + approve/reject. |
| `wcc_taxonomy` | Taxonomy + category management. |
| `wcc_attachment` | Attachment list / add / get / delete. |
| `wcc_bulk_job` | Start / status / cancel bulk jobs. |
| `wcc_system` | Doc types, config info, meta info, data-source queries. |
| `wcc_workflow_bulk_reclassify` | **Workflow tool** — apply a metadata patch across many docs with partial-failure + resumeToken. |
See [`docs/api/ENDPOINTS.md`](docs/api/ENDPOINTS.md) for every input/output schema, scope, annotation, and example.
## Architecture
```
src/
bin/wcc-mcp.ts CLI entry (bundled to dist/bin/wcc-mcp.js)
transports/ stdio + Streamable HTTP — single dispatch path
server/ build-server, dispatcher, context factory
registry/ tool + resource + prompt registry
tools/<domain>/ 16 consolidated tool definitions
prompts/ role-pack prompts (curator / auditor / migrator)
wcc/ WCC HTTP client + per-resource modules
auth/
basic/ Basic Auth strategy
mcp-rs/ OAuth Resource Server (Phase 4a)
wcc-oauth/ OAuth client against IDCS/Keycloak (Phase 4b)
lib/
workflow/ workflow framework (engine + resume token)
sampling/ MCP sampling primitive + budget
elicitation/ MCP elicitation primitive + validation
errors/ 20-code stable error taxonomy
logger/ stderr-only logger + redaction
audit/ structured audit log + sinks
path-policy/ stdio / electron / hosted
profiles/ multi-tenant profile manager
ssrf-guard/ private-IP + DNS-rebinding defenses
ratelimit/ token-bucket + Express middleware
config/ Zod config schema
electron/ GUI host (rewritten in Phase 6)
deploy/hosted/ Dockerfile + compose + Caddyfile + nginx.conf
```
Detailed architecture write-up: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Decision records: [`docs/adr/`](docs/adr/).
## Critical rules
These three rules are enforced by code + architecture guards. They are not negotiable.
1. **Never write to stdout in stdio mode.** stdio is the MCP transport channel. Diagnostics go to stderr only. ADR 0001.
2. **No server-side LLM dependency.** The server never bundles `@anthropic-ai/sdk`, `openai`, etc. Multi-step reasoning lives on the MCP client via `sampling/createMessage`. ADR 0003 + `tests/architecture/no-server-llm.test.ts`.
3. **Single dispatch path.** The v1 stdio/HTTP duplication trap is structurally impossible — both transports route through `src/server/dispatcher.ts:dispatchToolCall`. AST guard at `tests/architecture/no-duplicate-dispatch.test.ts`.
## Commands
```sh
pnpm install # use pnpm 9; npm is supported but lockfile is pnpm
pnpm typecheck # tsc --noEmit
pnpm lint # eslint with typescript-eslint
pnpm test # full vitest suite (unit / integration / architecture / security / eval)
pnpm test -- --project unit # one project at a time
pnpm test:electron # Playwright renderer-IPC regression (needs xvfb on Linux CI)
pnpm bench # tinybench micro-bench (cold start, dispatcher, audit throughput)
pnpm build # tsup bundle → dist/
pnpm sbom # CycloneDX SBOM → dist/sbom.json
pnpm dxt:pack # DXT bundle → dist/wcc-mcp.dxt
pnpm docs:generate # regenerate docs/api/ from the registry
pnpm docs:check # CI gate: fail if docs/api/ is stale
```
## Configuration
Environment variables consumed by the CLI:
| Var | Required | Purpose |
| ------------------------------------------------------- | ----------- | --------------------------------------------------------------------- |
| `WCC_BASE_URL` | yes | WCC REST API base URL. |
| `WCC_USER` / `WCC_PASSWORD` | yes (basic) | Basic Auth credentials. |
| `WCC_MCP_PROFILE` | no | Profile ID (default `default`). |
| `MCP_PORT` | no | HTTP port (default `3999`). |
| `MCP_BIND_HOST` | no | HTTP bind (default `127.0.0.1`). |
| `MCP_RS_ENABLED` | no | `1` enables OAuth Resource Server gating on `/mcp`. |
| `MCP_RS_ISSUER` / `MCP_RS_AUDIENCE` / `MCP_RS_JWKS_URI` | when MCP-RS | See [`docs/operators/oauth-setup.md`](docs/operators/oauth-setup.md). |
| `MCP_PATH_POLICY` | no | `stdio` (default), `electron`, or `hosted`. |
| `WCC_MCP_LEGACY_TOOL_NAMES` | no | `1` activates the v1-name shim (removed in v2.1.0). |
| `WCC_MCP_RESUME_SECRET` | recommended | 32-byte secret used to HMAC workflow resume tokens. |
## License
Dual-licensed:
- **GPL-3.0-or-later** for open use. See [`LICENSE`](LICENSE).
- **Commercial license** available from Fishbowl Solutions. See [`LICENSING.md`](LICENSING.md).
## Security
See [`SECURITY.md`](SECURITY.md) for the coordinated-disclosure runbook and the in-scope threat surface. Verification commands for every signed artefact are listed there too.
## Acknowledgements
Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic. Tool design follows the public MCP best-practices guide; auth follows OAuth 2.1 + RFC 7636 (PKCE) + RFC 8707 (resource indicators) + RFC 9728 (protected-resource metadata).
Connection Info
You Might Also Like
No recommendations available