drupal-mcp-connector 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.6.1] - 2026-06-04
+
+First release published to npm.
+
+### Fixed
+- HTTPS transport: import `randomUUID` from `node:crypto` for session IDs instead of
+  relying on the bare `crypto` global, which is not available unflagged on Node 18
+  (the minimum supported version).
+
+### Changed
+- Comprehensive inline-documentation pass (JSDoc on all exported functions/classes,
+  canonical descriptor/entity typedefs) and a Node coding-standards audit across `src/`.
+
+## [0.6.0] - 2026-06-03
+
+### Changed
+- Renamed the package to `drupal-mcp-connector` — clearer that it is the MCP↔Drupal connector, and avoids confusion with the Drupal `mcp_server` module. The outbound identity header is now `X-MCP-Client: drupal-mcp-connector/<version>`.
+- Prepared for npm publication (`bin`, `files`, `keywords`).
+
+## [0.5.0] - 2026-06-03
+
+### Added
+- **OAuth2 write-plane authentication.** Per-site `oauth` block enabling the
+  `client_credentials` grant against Drupal `simple_oauth`: token acquisition,
+  in-memory per-site caching with silent re-acquire (60s expiry skew), refresh-token
+  grant with fallback to `client_credentials`, concurrent-acquire de-duplication, and
+  a one-shot token clear + retry on `401`. The client secret is sourced from an
+  environment variable (`oauth.clientSecretEnv`) and is never stored in config or
+  surfaced in errors.
+- **`write-plane` security preset** mirroring the recommended server-side governance
+  profile: writes enabled, no deletes, no GraphQL mutations, entity access limited to
+  `node`/`taxonomy_term`/`media`, `user` entities denied, `pass`/`mail` redacted.
+
+### Changed
+- The three fetch helpers resolve auth via an async path so OAuth sites attach a
+  freshly-managed Bearer token; static token / Basic-auth sites are unchanged.
+- `requireSecureAuth` now accepts a valid `oauth` block as satisfying the Bearer
+  requirement.
+
+## [0.4.0] - 2026-06-01
+
+The connector is now **dual-protocol**: every tool runs against an abstract backend
+(JSON:API or GraphQL), selectable per site, with one canonical entity shape across both.
+
+### Added
+- **Dual-protocol backend layer.** A per-site `api` selector (`"jsonapi"`, `"graphql"`,
+  or a priority array; omit to auto-detect) routes every tool through `resolveBackend`.
+  JSON:API and GraphQL backends are interchangeable.
+- **GraphQL backend** via [GraphQL Compose](https://www.drupal.org/project/graphql_compose):
+  introspection-driven, type-aware field selection (`DateTime`/`Language`/`TextSummary`
+  scalar wrappers, entity-reference unions), native sort for `created`/`changed`/`title`,
+  and client-side filtering over a bounded fetch (results flagged `approximate`/`truncated`).
+- **Canonical entity shape** (`{ id, entityType, bundle, title, status, langcode, created,
+  changed, url, fields, relationships, _backend }`) produced by both backends.
+- **Backend capability model** (`read`/`write`/`delete`/`count`/`filter`/`sort`/`revisions`).
+  Writes against a read-only backend raise a clear `BackendCapabilityError`.
+- **Security hardening (all optional, safe defaults):** `X-MCP-Client` identity header
+  (override/disable via `MCP_CLIENT_ID`), bearer-authenticated HTTPS transport
+  (`MCP_AUTH_TOKEN`), bind-address restriction (`MCP_BIND_HOST`), tokens-from-env per site
+  (`apiTokenEnv`), and strict per-site auth enforcement (`requireSecureAuth`).
+- **GraphQL mutation gate:** parser-based detection rejects any mutation when
+  `allowGraphqlMutations` is off, regardless of where it appears in the document.
+
+### Changed
+- All 66 tools and 10 reports migrated to the backend layer and canonical output.
+- HTTPS transport hardened: HTTPS mandatory, plain HTTP refused off-localhost unless
+  `MCP_ALLOW_HTTP=1`; loopback-only bind without TLS; security headers on every response.
+- Documentation rewritten for the dual-protocol model, canonical output, capability gating,
+  and the optional hardening controls.
+
+### Removed
+- Bundled `drupal-module/` reference scaffold. Server-side governance now lives in the
+  companion [MCP Sentinel](https://www.drupal.org/project/mcp_sentinel) module
+  (`drupal/mcp_sentinel`), which supersedes it.
+
+### Security
+- Field-level PII redaction applied to canonical entities and JSON:API resources alike.
+- User tools gained explicit PII-access assertions.
+- Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
+
+[0.6.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.6.0
+[0.5.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.5.0
+[0.4.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Michael Cerda and Wilkes & Liberty, LLC
+
+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,193 @@
+# drupal-mcp-connector
+
+> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed content tools, audit reports, and an SSH Drush bridge.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
+[![Drupal](https://img.shields.io/badge/drupal-10%20%7C%2011-blue)](https://drupal.org)
+[![MCP](https://img.shields.io/badge/MCP-2025--11--25-purple)](https://modelcontextprotocol.io)
+
+Created by **Jeremy Michael Cerda**. Built and maintained by [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty).
+
+---
+
+## What It Does
+
+`drupal-mcp-connector` connects any [Model Context Protocol](https://modelcontextprotocol.io) client to one or more Drupal sites. It exposes Drupal content and configuration as a set of MCP **tools**, **resources**, and **prompts**, so an MCP client can read, audit, and (where permitted) write content through structured, governed operations instead of the admin UI:
+
+```
+"Find all articles missing a meta description and list them."
+"Show me every user account that hasn't logged in for 90 days."
+"Create 10 draft product nodes from this structured data."
+"Run an SEO and accessibility audit on the article content type."
+"What content types exist on the site and which are barely used?"
+```
+
+The connector speaks **two Drupal backends interchangeably** — Drupal core's **JSON:API** and **GraphQL** (via [GraphQL Compose](https://www.drupal.org/project/graphql_compose)) — selectable per site. It normalizes both into one canonical entity shape, so the same tools work whether a site exposes JSON:API, GraphQL, or both. An optional SSH **Drush bridge** adds administrative operations the HTTP APIs can't reach.
+
+---
+
+## Dual-Protocol Backends
+
+Each site declares which backend(s) it exposes via the `api` key:
+
+```json
+"sites": {
+  "main":         { "baseUrl": "https://example.com", "api": "jsonapi" },
+  "graphql_only": { "baseUrl": "https://api.example.com", "api": "graphql" },
+  "either":       { "baseUrl": "https://example.com", "api": ["graphql", "jsonapi"] }
+}
+```
+
+- **`api` accepts** `"jsonapi"`, `"graphql"`, or a priority array like `["graphql","jsonapi"]`. Omit it to **auto-detect** (the connector probes both once and caches the result).
+- **One canonical shape.** Both backends return entities as
+  `{ id, entityType, bundle, title, status, langcode, created, changed, url, fields, relationships, _backend }`, so tool output is identical regardless of protocol.
+- **Capability-aware.** Each backend advertises what it supports (read, write, delete, server-side filter/sort, revisions). GraphQL via GraphQL Compose is **read-only** (no mutations) and has no server-side field filter, so filters are applied client-side over a bounded fetch and flagged `approximate`/`truncated`. Write tools against a read-only backend return a clear capability error rather than failing silently.
+- **Writes go through JSON:API.** Use a JSON:API-enabled site as the write plane; keep GraphQL as a read plane where that suits your architecture.
+
+See **[docs/architecture.md](docs/architecture.md)** for the backend abstraction and **[docs/graphql-local-setup.md](docs/graphql-local-setup.md)** for the GraphQL specifics.
+
+---
+
+## Features
+
+### 66 Tools Across 9 Modules
+
+| Module | Tools |
+|--------|-------|
+| **Nodes** | CRUD for any content type with arbitrary field support |
+| **Taxonomy** | Vocabulary listing + full term CRUD |
+| **Users** | List, get, create, update, block/unblock, role management (PII-gated) |
+| **Media** | List types, CRUD, file upload, orphaned-media detection |
+| **GraphQL** | Execute a query, schema introspection (mutation-gated) |
+| **Entities** | Generic CRUD for *any* Drupal entity type (paragraphs, commerce, webforms, …) |
+| **Site** | Site info, content-type discovery, configured-site listing |
+| **Reports** | Content summary, stale content, field completeness, SEO/accessibility audits, taxonomy usage, user activity, revision hotspots (10 read-only reports) |
+| **Drush** | Cache rebuild, cron, config sync, module management, DB updates via SSH |
+
+### MCP Resources
+Browsable, always-fresh context the client can read without calling a tool:
+- **`drupal://sites`** — configured site profiles (no credentials)
+- **`drupal://{site}/content-types`** — content types with field schemas
+- **`drupal://{site}/security-policy`** — the active security configuration
+
+### MCP Prompts
+Workflow templates usable as slash-commands from any MCP client:
+- `drupal-content-audit` — walk through a full site content audit
+- `drupal-create-article` — guided article creation with all fields
+- `drupal-seo-fix` — find and fix SEO gaps
+- `drupal-user-cleanup` — identify and handle inactive accounts
+
+### Security Model
+Defense-in-depth with four one-line presets, enforced connector-side and complemented by Drupal-side governance:
+
+```json
+"security": { "preset": "auditor" }
+```
+
+| Preset | What it does |
+|--------|-------------|
+| `development` | Everything allowed — local development only |
+| `content-editor` | Create/edit nodes, media, terms; no deletes; no user access |
+| `auditor` | Read-only, all entity types, PII fields redacted |
+| `production-strict` | Read-only, no user entities, broad PII redaction |
+
+Presets layer with entity allow/deny lists, per-bundle operation rules, and field-level redaction. Optional transport hardening (bearer-authenticated HTTPS, bind-address restriction, secrets-from-env) is covered in **[docs/security-hardening.md](docs/security-hardening.md)**.
+
+---
+
+## Requirements
+
+- **Node.js** 18+
+- **Drupal** 10 or 11 (JSON:API ships in core)
+- For the **GraphQL backend**: [GraphQL Compose](https://www.drupal.org/project/graphql_compose)
+- For **token auth** (recommended): [Simple OAuth](https://www.drupal.org/project/simple_oauth)
+- For the **Drush bridge**: SSH key access to the Drupal server
+
+---
+
+## Quick Start
+
+```bash
+# 1. Clone and install
+git clone https://github.com/Wilkes-Liberty/drupal-mcp-connector
+cd drupal-mcp-connector
+npm install
+
+# 2. Configure
+cp config/config.example.json config/config.json
+# Edit config/config.json — add your site's baseUrl, api backend, and auth
+
+# 3. Run (stdio transport)
+node src/index.js
+```
+
+### Register with an MCP client
+
+Most desktop and CLI MCP clients launch the connector over **stdio**. Add an entry to your client's MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "drupal": {
+      "command": "node",
+      "args": ["/absolute/path/to/drupal-mcp-connector/src/index.js"],
+      "env": {
+        "DRUPAL_BASE_URL": "https://mysite.com",
+        "DRUPAL_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+For multi-client or remote use, run the HTTPS transport and register the endpoint instead — see **[docs/getting-started.md](docs/getting-started.md)**.
+
+---
+
+## Companion Drupal Module — MCP Sentinel
+
+The connector works out of the box against Drupal core's JSON:API and a GraphQL Compose schema. For server-side governance, pair it with the **[MCP Sentinel](https://www.drupal.org/project/mcp_sentinel)** module (`drupal/mcp_sentinel`), which enforces policy *inside* Drupal — independent of any connector configuration:
+
+- Role-bound policy profiles (operation gates, entity allow/deny, field redaction)
+- Tamper-evident audit log of every governed MCP operation, attributed to the acting account
+- Content locks that prevent edits to content a human is actively editing
+- OAuth scope enforcement (`mcp:read` / `mcp:write`) per tool
+- HMAC-signed webhooks on MCP-driven entity changes
+
+```bash
+composer require drupal/mcp_sentinel drupal/mcp_server drupal/simple_oauth
+drush en mcp_sentinel mcp_sentinel_server mcp_server_tool_bridge -y
+drush mcp-sentinel:setup
+```
+
+Governance keys off the authenticated account's role and OAuth scopes — not request headers. The connector sends an `X-MCP-Client` identity header purely as a log label. See the [MCP Sentinel project page](https://www.drupal.org/project/mcp_sentinel) for the full contract.
+
+---
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [Getting Started](docs/getting-started.md) | Full setup: DDEV/Lando, Simple OAuth, multi-site, transports |
+| [Architecture](docs/architecture.md) | Backend abstraction, canonical model, and how to extend it |
+| [GraphQL Setup](docs/graphql-local-setup.md) | GraphQL Compose backend + local TLS notes |
+| [Tools Reference](docs/tools-reference.md) | Full reference for all 66 tools |
+| [Security Guide](docs/security.md) | Presets, entity access control, field redaction |
+| [Security Hardening](docs/security-hardening.md) | Optional transport, identity, and secrets controls |
+| [Integration Contract](docs/integration-contract.md) | The connector ↔ Drupal-governance contract (identity, OAuth scopes, compatibility) |
+| [Whitepaper](docs/whitepaper.md) | Vision, personas, and use cases |
+
+---
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Security
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md). Please do not open a public issue.
+
+## License
+
+[MIT](LICENSE) © 2026 Jeremy Michael Cerda and [Wilkes & Liberty, LLC](https://github.com/Wilkes-Liberty)

package/config/config.example.json

@@ -0,0 +1,122 @@
+{
+  "_comment": "Copy to config/config.json and fill in your values. This file is safe to commit. config.json is gitignored.",
+
+  "_api_modes": {
+    "_comment": "Per-site 'api' selects the backend: 'graphql' | 'jsonapi' | a priority array like ['graphql','jsonapi']. Omit to auto-detect (probes both once). GraphQL is read-only (no mutations); writes require a JSON:API site.",
+    "examples": ["jsonapi", "graphql", ["graphql", "jsonapi"]]
+  },
+
+  "_security_options": {
+    "_comment": "All optional. apiTokenEnv: read the Bearer token from this env var instead of apiToken (keeps secrets out of the config file). requireSecureAuth: reject anon/basic, require HTTPS+Bearer (recommended for production). Env overrides: MCP_CLIENT_ID overrides or disables the outbound identity header; MCP_AUTH_TOKEN requires bearer auth on the HTTPS /mcp endpoint; MCP_BIND_HOST restricts the listen interface (with TLS). See docs/security-hardening.md."
+  },
+
+  "defaultSite": "production",
+
+  "tls": {
+    "_comment": "TLS is required for the HTTPS transport (MCP_TRANSPORT=https). Ignored in stdio mode.",
+    "certPath": "/etc/ssl/certs/drupal-mcp.crt",
+    "keyPath":  "/etc/ssl/private/drupal-mcp.key",
+    "port":     3443
+  },
+
+  "sites": {
+    "production": {
+      "baseUrl":           "https://mysite.com",
+      "apiToken":          "eyJhbGciOiJSUzI1NiJ9...",
+      "apiTokenEnv":       "DRUPAL_TOKEN_PRODUCTION",
+      "requireSecureAuth": true,
+      "username":          "",
+      "password":          "",
+      "graphqlEndpoint":   "/graphql",
+      "api":               "jsonapi",
+
+      "drushSsh": {
+        "_comment": "Optional. Enables drupal_drush_* tools. SSH key auth only — no passwords.",
+        "host":       "ssh.mysite.com",
+        "user":       "deploy",
+        "keyPath":    "~/.ssh/id_ed25519",
+        "drupalRoot": "/var/www/html/web",
+        "port":       22
+      },
+
+      "security": {
+        "_comment": "Presets: development | content-editor | auditor | production-strict",
+        "preset":                "auditor",
+        "readOnly":              true,
+        "allowDestructive":      false,
+        "allowGraphqlMutations": false,
+        "allowedEntityTypes":    null,
+        "deniedEntityTypes":     ["user"],
+        "globalRedactedFields":  ["pass", "mail", "field_api_key", "field_private"],
+        "entityRules": {
+          "node": {
+            "allowedOperations": ["read"],
+            "deniedBundles":     ["private_document", "internal_memo"]
+          }
+        }
+      }
+    },
+
+    "staging": {
+      "baseUrl":  "https://staging.mysite.com",
+      "username": "api-user",
+      "password": "change-me-use-token-instead",
+      "api":      "jsonapi",
+      "security": { "preset": "content-editor" }
+    },
+
+    "local": {
+      "_comment": "Plain HTTP is allowed for localhost targets only. A warning is logged.",
+      "baseUrl":  "http://mysite.lndo.site",
+      "username": "admin",
+      "password": "admin",
+      "security": { "preset": "development" }
+    },
+
+    "graphql_only": {
+      "_comment": "A site that exposes GraphQL only (JSON:API disabled). GraphQL is read-only.",
+      "baseUrl":         "https://api.example.com",
+      "graphqlEndpoint": "/graphql",
+      "api":             "graphql",
+      "security":        { "preset": "auditor" }
+    },
+
+    "oauth_write_plane": {
+      "_comment": "OAuth2 client_credentials grant against simple_oauth. The client secret is read from the named env var and never stored here.",
+      "baseUrl":           "https://api.example.com",
+      "requireSecureAuth": true,
+      "api":               "jsonapi",
+      "oauth": {
+        "tokenUrl":        "/oauth/token",
+        "clientId":        "mcp-agent-prod",
+        "clientSecretEnv": "MCP_AGENT_CLIENT_SECRET",
+        "scopes":          ["mcp:read", "mcp:write"],
+        "grant":           "client_credentials"
+      },
+      "security": { "preset": "write-plane" }
+    }
+  },
+
+  "_security_presets": {
+    "development":       "All operations allowed. Local dev only.",
+    "content-editor":    "Create/edit nodes+media+terms. No deletes. No user entity access.",
+    "auditor":           "Read-only. All entity types. User PII fields redacted.",
+    "production-strict": "Read-only. No user entities. Broad PII redaction.",
+    "write-plane":       "Governed writes (no delete/mutations) on node, taxonomy_term, media. No user. Redacts pass/mail."
+  },
+
+  "_mcp_client_registration": {
+    "_comment": "Add under your MCP client's mcpServers config (stdio transport)",
+    "drupal": {
+      "command": "node",
+      "args":    ["/absolute/path/to/drupal-mcp-connector/src/index.js"]
+    }
+  },
+
+  "_https_transport_registration": {
+    "_comment": "For multi-client HTTP mode — register the HTTPS endpoint instead",
+    "drupal": {
+      "url": "https://your-server:3443/mcp"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "drupal-mcp-connector",
+  "version": "0.6.1",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "drupal-mcp-connector": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "drupal",
+    "mcp",
+    "model-context-protocol",
+    "jsonapi",
+    "json-api",
+    "graphql",
+    "connector",
+    "headless",
+    "decoupled",
+    "drush"
+  ],
+  "homepage": "https://github.com/Wilkes-Liberty/drupal-mcp-connector",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wilkes-Liberty/drupal-mcp-connector/issues"
+  },
+  "license": "MIT",
+  "author": "Jeremy Michael Cerda <jmcerda@wilkesliberty.com> (https://wilkesliberty.com)",
+  "contributors": [
+    "Wilkes & Liberty, LLC <opensource@wilkesliberty.com> (https://wilkesliberty.com)"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start":        "node src/index.js",
+    "start:https":  "MCP_TRANSPORT=https node src/index.js",
+    "start:dev":    "MCP_TRANSPORT=https MCP_ALLOW_HTTP=1 MCP_PORT=3443 node src/index.js",
+    "lint":         "eslint src/",
+    "lint:fix":     "eslint src/ --fix",
+    "test":         "vitest run",
+    "test:watch":   "vitest",
+    "audit":        "npm audit --audit-level=high",
+    "check":        "npm run lint && npm run audit",
+    "syntax-check": "for f in src/lib/*.js src/tools/*.js src/index.js; do node --input-type=module --check < $f && echo \"$f ✓\"; done"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "graphql": "^16.9.0",
+    "node-fetch": "^3.3.2",
+    "ssh2": "^1.16.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "eslint-plugin-security": "^3.0.0",
+    "eslint-plugin-n": "^17.0.0",
+    "globals": "^15.0.0",
+    "vitest": "^2.1.0"
+  }
+}