drupal-mcp-connector 0.6.1

package/src/tools/entities.js

@@ -0,0 +1,262 @@
+/**
+ * Tool group: Generic entities.
+ *
+ * Type-agnostic CRUD plus schema/type discovery and a security summary. These
+ * tools work with ANY Drupal entity type + bundle, so each handler asserts the
+ * appropriate read/write/delete permission in-handler (the name-prefix gating
+ * in index.js cannot know the entity type from the generic tool names). Reads
+ * are redacted per the site policy.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { resolveBackend } from "../lib/backends/index.js";
+import {
+  resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, assertDeleteAllowed,
+  redactCanonicalEntity, getSecuritySummary,
+} from "../lib/security.js";
+
+/**
+ * List entities of any type/bundle with filters, sort, includes and paging.
+ *
+ * @param {object} args - { site?, entityType, bundle, filters?, sort?, limit?, offset?, include? }.
+ * @returns {Promise<{total: number, approximate: boolean, offset: number,
+ *   nextOffset: number, entities: object[]}>} Paged, redacted entity list.
+ * @throws {SecurityError} If reading the type/bundle is not permitted.
+ */
+async function listEntities({ site: siteName, entityType, bundle, filters = [], sort = [], limit = 20, offset = 0, include = [] }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, entityType, bundle);
+  const backend = await resolveBackend(site);
+  const res = await backend.listEntities({ entityType, bundle, filters, sort, include, page: { limit, offset } });
+  const entities = res.entities.map((e) => redactCanonicalEntity(e, sec, entityType));
+  return { total: res.page?.total ?? entities.length, approximate: res.approximate ?? false, offset, nextOffset: offset + entities.length, entities };
+}
+
+/**
+ * Fetch a single entity of any type by UUID, redacted per policy.
+ *
+ * @param {object} args - { site?, entityType, bundle, id, include? }.
+ * @returns {Promise<object|null>} The redacted entity, or null if not found.
+ * @throws {SecurityError} If reading the type/bundle is not permitted.
+ */
+async function getEntity({ site: siteName, entityType, bundle, id, include = [] }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, entityType, bundle);
+  const backend = await resolveBackend(site);
+  const entity = await backend.getEntity({ entityType, bundle, id, include });
+  return entity ? redactCanonicalEntity(entity, sec, entityType) : null;
+}
+
+/**
+ * Create an entity of any type/bundle.
+ *
+ * @param {object} args - { site?, entityType, bundle, attributes?, relationships? }.
+ * @returns {Promise<object>} The created entity descriptor.
+ * @throws {SecurityError} If creating the type/bundle is not permitted.
+ */
+async function createEntity({ site: siteName, entityType, bundle, attributes = {}, relationships = {} }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "create", entityType, bundle);
+  const backend = await resolveBackend(site);
+  return backend.createEntity({ entityType, bundle, attributes, relationships });
+}
+
+/**
+ * Update an entity of any type/bundle (partial — only supplied fields are sent).
+ *
+ * @param {object} args - { site?, entityType, bundle, id, attributes?, relationships? }.
+ * @returns {Promise<object>} The updated entity descriptor.
+ * @throws {SecurityError} If updating the type/bundle is not permitted.
+ */
+async function updateEntity({ site: siteName, entityType, bundle, id, attributes = {}, relationships = {} }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertWriteAllowed(sec, "update", entityType, bundle);
+  const backend = await resolveBackend(site);
+  return backend.updateEntity({ entityType, bundle, id, attributes, relationships });
+}
+
+/**
+ * Delete an entity of any type/bundle. Requires allowDestructive in policy.
+ *
+ * @param {object} args - { site?, entityType, bundle, id }.
+ * @returns {Promise<{success: boolean, deletedId: string, entityType: string, bundle: string}>}
+ * @throws {SecurityError} If deleting the type/bundle is not permitted.
+ */
+async function deleteEntity({ site: siteName, entityType, bundle, id }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertDeleteAllowed(sec, entityType, bundle, id);
+  const backend = await resolveBackend(site);
+  await backend.deleteEntity({ entityType, bundle, id });
+  return { success: true, deletedId: id, entityType, bundle };
+}
+
+/**
+ * Discover all resource types the backend exposes, filtered to those the policy
+ * permits reading. Accessibility is probed per type by catching the assertion
+ * (rather than indexing a policy table), which keeps the lookup injection-safe.
+ *
+ * @param {object} args - { site? }.
+ * @returns {Promise<{total: number, accessible: number, blocked: number,
+ *   resourceTypes: object[]}>} Counts plus the list of readable types.
+ */
+async function listEntityTypes({ site: siteName }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  const backend = await resolveBackend(site);
+  const all = await backend.listResourceTypes();
+  const accessible = all.filter(({ entityType, bundle }) => {
+    try { assertReadAllowed(sec, entityType, bundle); return true; } catch { return false; }
+  });
+  return { total: all.length, accessible: accessible.length, blocked: all.length - accessible.length, resourceTypes: accessible };
+}
+
+/**
+ * Return the field/relationship schema for a type + bundle.
+ *
+ * @param {object} args - { site?, entityType, bundle }.
+ * @returns {Promise<object>} The backend's schema descriptor.
+ * @throws {SecurityError} If reading the type/bundle is not permitted.
+ */
+async function getEntitySchema({ site: siteName, entityType, bundle }) {
+  const site = getSiteConfig(siteName);
+  const sec = resolveSecurityConfig(site);
+  assertReadAllowed(sec, entityType, bundle);
+  const backend = await resolveBackend(site);
+  return backend.getEntitySchema(entityType, bundle);
+}
+
+/**
+ * Summarize the active security policy for a site (allowed/blocked/redacted).
+ * No backend call — reads policy only.
+ *
+ * @param {object} args - { site? }.
+ * @returns {Promise<object>} The security summary.
+ */
+async function securityInfo({ site: siteName }) {
+  const site = getSiteConfig(siteName);
+  return getSecuritySummary(site);
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_list_entity_types",
+    description: "Discover all JSON:API resource types (entity types + bundles) exposed by this Drupal site, filtered to only those your security config allows. Run this before working with an unfamiliar entity type.",
+    inputSchema: {
+      type: "object",
+      properties: { site: { type: "string" } },
+    },
+  },
+  {
+    name: "drupal_get_entity_schema",
+    description: "Inspect the fields and relationships available on any Drupal entity type + bundle. Run this before creating or updating entities to know what fields are available.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string", description: "e.g. 'node', 'paragraph', 'commerce_product', 'block_content'" },
+        bundle:     { type: "string", description: "e.g. 'article', 'text', 'default'" },
+      },
+    },
+  },
+  {
+    name: "drupal_entity_list",
+    description: "List entities of any Drupal entity type and bundle. Supports structured filters, sorting, pagination, and relationship includes. Use drupal_list_entity_types first to discover available types.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string", description: "Entity type machine name, e.g. 'paragraph', 'block_content', 'commerce_product'" },
+        bundle:     { type: "string", description: "Bundle machine name" },
+        filters:    { type: "array", description: "Structured filters: [{ field, op, value }]", items: { type: "object" } },
+        sort:       { type: "array", description: "Sort specs: [{ field, dir }]", items: { type: "object" } },
+        include:    { type: "array", description: "Relationship field names to sideload", items: { type: "string" } },
+        limit:      { type: "number", default: 20 },
+        offset:     { type: "number", default: 0 },
+      },
+    },
+  },
+  {
+    name: "drupal_entity_get",
+    description: "Fetch a single entity of any Drupal entity type by UUID.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle", "id"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string" },
+        bundle:     { type: "string" },
+        id:         { type: "string", description: "Entity UUID" },
+        include:    { type: "array", description: "Relationship field names to sideload", items: { type: "string" } },
+      },
+    },
+  },
+  {
+    name: "drupal_entity_create",
+    description: "Create an entity of any Drupal entity type and bundle. Use drupal_get_entity_schema first to know what fields are available. All operations checked against security config.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle"],
+      properties: {
+        site:          { type: "string" },
+        entityType:    { type: "string" },
+        bundle:        { type: "string" },
+        attributes:    { type: "object", description: "Field values keyed by Drupal machine name" },
+        relationships: { type: "object", description: "Relationship data keyed by field name" },
+      },
+    },
+  },
+  {
+    name: "drupal_entity_update",
+    description: "Update an existing entity of any Drupal entity type. Only include attributes/relationships you want to change.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle", "id"],
+      properties: {
+        site:          { type: "string" },
+        entityType:    { type: "string" },
+        bundle:        { type: "string" },
+        id:            { type: "string" },
+        attributes:    { type: "object" },
+        relationships: { type: "object" },
+      },
+    },
+  },
+  {
+    name: "drupal_entity_delete",
+    description: "Delete an entity of any Drupal entity type. Requires allowDestructive = true in security config. Confirm with the user before calling.",
+    inputSchema: {
+      type: "object", required: ["entityType", "bundle", "id"],
+      properties: {
+        site:       { type: "string" },
+        entityType: { type: "string" },
+        bundle:     { type: "string" },
+        id:         { type: "string" },
+      },
+    },
+  },
+  {
+    name: "drupal_security_info",
+    description: "Show the active security configuration for a site — what's allowed, what's blocked, what fields are redacted. Run this to understand the current access policy.",
+    inputSchema: {
+      type: "object",
+      properties: { site: { type: "string" } },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_list_entity_types:  listEntityTypes,
+  drupal_get_entity_schema:  getEntitySchema,
+  drupal_entity_list:        listEntities,
+  drupal_entity_get:         getEntity,
+  drupal_entity_create:      createEntity,
+  drupal_entity_update:      updateEntity,
+  drupal_entity_delete:      deleteEntity,
+  drupal_security_info:      securityInfo,
+};

package/src/tools/graphql.js

@@ -0,0 +1,175 @@
+/**
+ * Tool group: GraphQL.
+ *
+ * Raw GraphQL execution and schema introspection against a Drupal site. Require
+ * the GraphQL Compose module (drupal.org/project/graphql_compose), which
+ * exposes a read-only schema (no mutations); any mutation in a query is
+ * additionally gated by the per-site "allowGraphqlMutations" security flag,
+ * enforced by the middleware in index.js before the handler runs.
+ *
+ * Per-site config: set "graphqlEndpoint" to override "/graphql".
+ * Auth reuses the same credentials as the JSON:API tools.
+ */
+
+import { getSiteConfig } from "../lib/config.js";
+import { drupalGraphqlFetch } from "../lib/drupal-fetch.js";
+
+// ---------------------------------------------------------------------------
+// Implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a GraphQL query or mutation and normalize the response envelope.
+ *
+ * @param {object} args - { site?, query, variables?, operationName? }.
+ * @returns {Promise<{data: object, warnings?: string[]}>} On a clean response,
+ *   just `data`. When the server returns errors alongside partial `data`, the
+ *   error messages are surfaced as `warnings` rather than thrown.
+ * @throws {Error} If the response carries errors and no data at all.
+ */
+async function runGraphql({ site: siteName, query, variables = {}, operationName }) {
+  const site = getSiteConfig(siteName);
+  const json = await drupalGraphqlFetch(site, { query, variables, operationName });
+
+  if (json.errors?.length) {
+    const messages = json.errors.map((e) => e.message).join("; ");
+    if (!json.data) throw new Error(`GraphQL errors: ${messages}`);
+    // Partial result — return data AND surface errors as a warning
+    return { data: json.data, warnings: json.errors.map((e) => e.message) };
+  }
+
+  return { data: json.data };
+}
+
+/**
+ * Introspect the GraphQL schema, either in detail for one type or as an
+ * overview. When `typeName` is given, returns that type's fields, args, and
+ * input fields. Otherwise returns the root operation types plus all non
+ * built-in, non-scalar types for readability.
+ *
+ * @param {object} args - { site?, typeName? }.
+ * @returns {Promise<object>} A single __type descriptor, or a schema overview.
+ * @throws {Error} If a requested typeName is not present in the schema, or the
+ *   overview query returns errors.
+ */
+async function introspectGraphql({ site: siteName, typeName }) {
+  const site = getSiteConfig(siteName);
+
+  // If a specific type is requested, get detailed field info for it.
+  if (typeName) {
+    const query = `
+      query IntrospectType($name: String!) {
+        __type(name: $name) {
+          name
+          kind
+          description
+          fields(includeDeprecated: true) {
+            name
+            description
+            isDeprecated
+            deprecationReason
+            type { name kind ofType { name kind ofType { name kind } } }
+            args { name description type { name kind ofType { name kind } } }
+          }
+          inputFields {
+            name
+            description
+            type { name kind ofType { name kind } }
+          }
+        }
+      }
+    `;
+    const json = await drupalGraphqlFetch(site, { query, variables: { name: typeName } });
+    if (!json.data?.__type) throw new Error(`Type '${typeName}' not found in schema.`);
+    return json.data.__type;
+  }
+
+  // Otherwise return a high-level schema overview.
+  const query = `
+    {
+      __schema {
+        queryType  { name }
+        mutationType { name }
+        subscriptionType { name }
+        types {
+          name
+          kind
+          description
+          fields { name type { name kind ofType { name kind } } }
+        }
+      }
+    }
+  `;
+  const json = await drupalGraphqlFetch(site, { query });
+  if (json.errors?.length) {
+    throw new Error(json.errors.map((e) => e.message).join("; "));
+  }
+
+  const schema = json.data.__schema;
+  // Filter out built-in introspection types (__*) and scalars for readability
+  const types = schema.types.filter(
+    (t) => !t.name.startsWith("__") && t.kind !== "SCALAR"
+  );
+
+  return {
+    queryType:        schema.queryType?.name ?? null,
+    mutationType:     schema.mutationType?.name ?? null,
+    subscriptionType: schema.subscriptionType?.name ?? null,
+    types,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+
+export const definitions = [
+  {
+    name: "drupal_graphql",
+    description: `Execute a GraphQL query against a Drupal site.
+Requires the GraphQL Compose module (drupal.org/project/graphql_compose), which
+exposes a read-only schema; mutations are gated by "allowGraphqlMutations".
+Use drupal_graphql_introspect first to discover available types and fields.
+
+Example query:
+  query GetArticle($id: String!) {
+    nodeById(id: $id) {
+      title
+      ... on NodeArticle { body { value } }
+    }
+  }
+
+Example mutation (only if your GraphQL Compose schema enables mutations):
+  mutation CreateArticle($title: String!, $body: String!) {
+    createNodeArticle(data: { title: $title, body: { value: $body, format: "full_html" } }) {
+      entity { title uuid }
+      errors { message }
+    }
+  }`,
+    inputSchema: {
+      type: "object", required: ["query"],
+      properties: {
+        site:          { type: "string", description: "Named site (omit for default)" },
+        query:         { type: "string", description: "GraphQL query or mutation string" },
+        variables:     { type: "object", description: "Variables to pass with the query" },
+        operationName: { type: "string", description: "Operation name (for multi-operation documents)" },
+      },
+    },
+  },
+  {
+    name: "drupal_graphql_introspect",
+    description: "Introspect the Drupal GraphQL schema. Omit typeName for a full schema overview; provide typeName to get detailed fields and args for a specific type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        site:     { type: "string" },
+        typeName: { type: "string", description: "Name of a specific GraphQL type to inspect in detail (optional)" },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  drupal_graphql:           runGraphql,
+  drupal_graphql_introspect: introspectGraphql,
+};