DynamicWeb管理API工具集

degree-dynamicweb-mcp

MCP (Model Context Protocol) server for DynamicWeb 10 Admin API. Gives Claude Code full access to manage DynamicWeb item types, fields, pages, paragraphs, and API discovery - without touching the DW Admin UI.

Tools

Item Types

Schema maintenance

Deploying item type XML does not touch the database. Until the schema is synced, a field whose column is missing saves without error and keeps nothing.

After deploying new XML: dw_itemtype_sync_schema, then dw_itemtype_health. The sync endpoint answers "ok" even when it aborted partway, so the health check is what tells you whether it worked - and /Files/System/Log/items/ActivationWorkflow holds the real errors. An item type whose table is missing entirely does not appear in the health report at all.

Fields

Pages

Paragraphs

dw_page_set_fields and dw_paragraph_set_fields verify their own write. A field name the item type does not declare is an error that lists the names it does have, and after saving they read the item back and return what it now holds. DW answers "ok" whether or not a value was stored, so a typo in a SystemName used to be indistinguishable from a successful write.

Products

dw_product_update accepts three input maps:

• fields - top-level product fields (Name, DefaultPrice, Stock, etc.)
• customFields - global product custom field values, keyed by SystemName
• categoryFields - product category field values, keyed by SystemName

Product Schema

Manage the PIM data model: product categories (groups of attributes) and product fields (the attributes themselves).

Files

Delivery API (read-only)

API Discovery

Setup

1. Get a DW API token

In DynamicWeb Admin, go to Settings > Developer > API Keys and create a new key with full access.

2. Configure your AI client

{
  "mcpServers": {
    "dynamicweb": {
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dynamicweb": {
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dynamicweb": {
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "servers": {
    "dynamicweb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dynamicweb": {
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dynamicweb": {
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

{
  "context_servers": {
    "dynamicweb": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@degree-as/dynamicweb-mcp"],
      "env": {
        "DW_BASE_URL": "https://your-dw-instance",
        "DW_API_TOKEN": "your-token"
      }
    }
  }
}

mcpServers:
  - name: dynamicweb
    command: npx
    args:
      - -y
      - "@degree-as/dynamicweb-mcp"
    env:
      DW_BASE_URL: https://your-dw-instance
      DW_API_TOKEN: your-token

3. Restart your client

The MCP server starts automatically when your AI client loads.

Local development

If you want to run from source instead of the published package:

git clone https://github.com/Degree-AS/degree-dynamicweb-mcp.git
cd degree-dynamicweb-mcp
npm install
npm run build

Then use "command": "node", "args": ["/path/to/degree-dynamicweb-mcp/dist/index.js"] in .mcp.json.

Field Type Aliases

Item type fields (dw_field_save, dw_itemtype_create)

When creating fields, you can use short aliases instead of full .NET class names:

Any full .NET editor class name is also accepted. Use dw_field_types to discover all available editors from your DW instance.

Repeatable lists (itemrelation)

itemrelation (ItemRelationListEditor) creates a repeatable list of child items — the generic way to model FAQ items, rows, persons, etc. (instead of fixed numbered slots like Question1..5). It needs two extra params:

Create the child item type first, then the parent:

// 1) child row
dw_itemtype_create { systemName: "OpeningHoursRow", fields: [
  { name: "Label", systemName: "Label", type: "text" },
  { name: "Value", systemName: "Value", type: "text" },
]}
// 2) parent with the repeatable list
dw_itemtype_create { systemName: "OpeningHours", fields: [
  { name: "Title", systemName: "Title", type: "text" },
  { name: "Rows",  systemName: "Rows",  type: "itemrelation", itemRelationType: "OpeningHoursRow" },
]}

The tool emits the required EditorConfiguration + EditorFields (Item type / Item source) and the Int32 underlying type automatically.

Product fields (dw_product_field_save)

Product fields use a different system - integer TypeId from FieldTypeAll, not editor class names:

Numeric TypeId is also accepted directly. Use dw_product_field_type_list to fetch the live list from your DW instance.

Architecture

src/
  index.ts          Entry point - reads config from env, registers tools
  client.ts         DwClient - HTTP client for Admin API, Update API, Delivery API
  utils.ts          Shared Zod helpers (jsonParam, numParam) and response helpers (prop, pascal)
  tools/
    itemTypes.ts    Item type CRUD, fields, restrictions, settings, editor discovery, schema health and sync
    pages.ts        Page and area management
    paragraphs.ts   Paragraph management (uses ParagraphNew + ParagraphSave)
    products.ts     Product CRUD, bulk discount, custom/category field value updates
    productSchema.ts Product categories and product field schema management
    files.ts        File and directory browsing
    delivery.ts     Read-only Delivery API
    discovery.ts    Swagger search, endpoint schema, raw API calls

DW API surfaces

The DynamicWeb Admin API has three calling conventions:

1. Admin API (GET /admin/api/{Endpoint}) - queries with URL params
2. Command API (POST /admin/api/{Endpoint}) - mutations with { Model: {...} } body. Delete commands use flat body (no Model wrapper).
3. Update API (POST /Admin/Api/{Endpoint}?Query.Type={Type}) - updates existing records with { QueryData: {...}, model: {...} } body

DwClient has dedicated methods for each: get(), post(), command(), update(), delivery().

Development

npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm run start    # Run compiled version

After changes, run npm run build and restart Claude Code to pick up the new version.