BeikeShop Docs | Open Source Laravel eCommerce Documentation

# Plugin Management MCP

Use the remote website MCP to query, create, and edit plugins, upload packages, change prices, and list or unlist plugins.

Submission is not publication

Plugin creation, information edits, and package updates take effect after administrator approval. Price and listing changes take effect immediately. Only an approved, published plugin can be listed.

# Getting started

  1. Sign in to the BeikeShop website (opens new window) with an account that has developer access.
  2. Open User Center → My Plugins (opens new window) and click MCP Access (MCP 接入).
  3. In the credentials tab, enter a name, select an expiry period, and create a credential. The full Token is shown only once; save it in your AI client's secure configuration.
  4. Add the remote MCP URL and authorization header below to your AI client. Connect and confirm that the plugin management tools are available.

Credentials authorize all tools for plugins owned by the current developer. Calls fail if the credential expires, is revoked, or developer access is lost.

# Connection settings

  • MCP URL: https://beikeshop.cn/api/mcp/developer
  • Transport: Streamable HTTP with POST / JSON responses.
  • Authorization header: Authorization: Bearer <your MCP Token>.

Configuration example (field names depend on the AI client):

{
  "mcpServers": {
    "beikeshop": {
      "url": "https://beikeshop.cn/api/mcp/developer",
      "headers": {
        "Authorization": "Bearer <your MCP Token>"
      }
    }
  }
}

Use the dedicated MCP credential created on the website, rather than a store Token, administrator credential, or browser login Cookie. OAuth login, SSE, and server push are not currently available. The client must support a Bearer authorization header.

Package uploads require local file processing and HTTPS upload capabilities. Remote MCP cannot read local files.

# Available tools

All tools are discovered and called through the same MCP endpoint.

Tool Main arguments Function and result
get_plugin_form_schema None Retrieve field rules, required fields, languages, plugin types, and compatible version options; call this before creating a plugin
list_my_plugins Optional keyword, page Retrieve a paginated list of your plugins; keyword searches plugin codes, and results include published and pending information
get_my_plugin plugin_code Retrieve a plugin's published information, pending changes, and latest review result
prepare_plugin_update operation, plugin_code, expected_version, file_size, sha256 Prepare a package upload session; operation is create or update; returns an update ID, upload URL, temporary credential, and expiry time
get_plugin_update_status update_id Check validation, submission, and review status, including errors or rejection reasons
create_plugin plugin_code, update_id, idempotency_key, fields Create a plugin from a validated package and submit it for review; the plugin is not automatically listed
update_plugin plugin_code, idempotency_key, fields; optional update_id Submit specified information changes or a replacement package for review; omitted fields retain their existing values
update_plugin_price plugin_code, price; optional origin_price Change the selling price and original price immediately; selling price must be at least CNY 5
set_plugin_active plugin_code, boolean active Use true to list or false to unlist a plugin immediately; this does not change its review status

fields supports localized names, summaries, Markdown descriptions, cover images, compatible versions, service prices, tags, and subscription settings. Use get_plugin_form_schema for the current requirements. Compatible versions must use the returned version IDs, rather than version strings.

For a new plugin, the package can supply the default name, type, and icon. You still need to provide the selling price, descriptions in every required language, compatible versions, and any other required information. update_plugin does not accept selling price, original price, or listing status; use the separate tools instead.

There are no tools for deleting plugins, approving reviews, publishing new versions directly, or automatically syncing a README. You cannot manage another developer's plugins.

# How AI discovers and calls tools

The MCP client automatically runs initialize → tools/list and provides the tool definitions to the AI. The AI selects a tool and generates arguments; the client executes it through tools/call.

tools/list returns result.tools, filtered by credential permissions. Each entry includes:

Field Purpose
name Tool name used in calls
description Purpose, when to call, and business limits
inputSchema Argument types, required fields, and limits
annotations Behavior hints; these do not replace server permission checks

# Inspecting the tool list manually

For a connection check, replace the Token and send this POST request. Opening the endpoint in a browser sends GET, which is unsupported:

curl 'https://beikeshop.cn/api/mcp/developer' \
  --header 'Authorization: Bearer <your MCP Token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

If tools cannot be discovered, check the MCP URL, transport, and authorization header. For 401 responses, see States and troubleshooting.

# Uploading a package and submitting it

# 1. Prepare a ZIP

The ZIP must contain config.json and an icon under Static/ at the package root or inside a single top-level plugin directory.

  • config.json.code must match the target plugin_code, and the package version must match expected_version.
  • A replacement package must have a different version from the current published version. Information-only edits do not require a version change.
  • config.json.icon specifies an icon path relative to Static/. The default is Static/image/logo.png when no path is specified.
  • Icons may be PNG, JPEG, GIF, or WebP, up to 5 MiB and 4096 × 4096 pixels.
  • Default limits are 100 MiB per ZIP, 500 MiB of uncompressed data, and 10000 entries. The website's actual limits take precedence.
  • Encrypted archives, symbolic links, and paths outside the package are rejected. The website validates the package without executing plugin code.

See Plugin Development for package structure and configuration.

# 2. Prepare an upload session

Calculate the ZIP's actual size in bytes and SHA-256, then call prepare_plugin_update:

{
  "operation": "update",
  "plugin_code": "example",
  "expected_version": "2.0.0",
  "file_size": 12345,
  "sha256": "<the ZIP's 64-character lowercase SHA-256>"
}

Use operation: "create" for a new plugin. Replace the example file size and checksum with the actual values.

# 3. Upload the file and wait for validation

The response includes update_id, upload_url, method, headers, and expires_at. Send a multipart upload to the returned URL with the returned authorization header. The file field is named file:

curl --request POST "$UPLOAD_URL" \
  --header "Authorization: $UPLOAD_AUTHORIZATION" \
  --form "file=@$PLUGIN_ZIP"

UPLOAD_URL = returned upload_url; UPLOAD_AUTHORIZATION = complete returned headers.Authorization (including Bearer); PLUGIN_ZIP = local ZIP path.

Use the session's temporary upload credential, rather than your long-term MCP Token. Do not put Tokens in URLs or send local paths or Base64 file content as MCP arguments.

Call get_plugin_update_status with {"update_id":"<your update ID>"}. Wait until the state is ready before submitting for review.

# 4. Submit for review

To replace only the package, call update_plugin:

{
  "plugin_code": "example",
  "update_id": "<your update ID>",
  "idempotency_key": "example-2.0.0-release-1",
  "fields": {}
}

To create a plugin, retrieve the field requirements first, then call create_plugin, for example:

{
  "plugin_code": "example",
  "update_id": "<your update ID>",
  "idempotency_key": "example-create-1",
  "fields": {
    "price": 99,
    "description": {
      "zh_cn": "插件的中文功能说明。",
      "en": "Plugin features and usage instructions."
    },
    "versions": [1]
  }
}

This example uses the name, type, and icon from the package as defaults. The 1 in versions is an example ID: replace it with an actual ID returned by the schema tool, and provide descriptions in the required languages it returns.

A successful submission returns pending_review. Continue querying get_plugin_update_status for the result. approved means the submission was approved; rejected means it was rejected. Read the reason, make corrections, and submit again.

# Editing information without a package

You do not need an upload session or a new package. Omit update_id from update_plugin and provide only the fields you want to change:

{
  "plugin_code": "example",
  "idempotency_key": "example-description-1",
  "fields": {
    "description": {
      "zh_cn": "更新后的中文说明，支持 Markdown。"
    }
  }
}

Changes to compatible versions and service prices also require review.

# States and troubleshooting

State Meaning
awaiting_upload Waiting for a package upload
validating File received; validation is in progress
ready Validation passed; not yet submitted for review
failed / expired Processing failed or the upload session expired
pending_review Submitted and waiting for administrator review
approved / rejected / ban Approved, rejected, or frozen
applied A separate price or listing change has taken effect immediately
  • Authentication fails: check the Token, expiry date, revocation status, and developer access.
  • Local files cannot be uploaded: check local file processing and HTTPS upload capabilities.
  • Validation fails: check the reported error, package structure, code, version, file size, and SHA-256. Fix the package and prepare a new upload session.
  • A pending submission already exists: existing drafts cannot be overwritten, including drafts submitted through the website. Wait for the review result; rejected drafts can be revised and submitted again.
  • A connection is interrupted or a call needs retrying: query the status first. Keep the same idempotency_key for retries of the same submission, and use a different key for each new submission to avoid duplicate creation or submission.
  • An upload session expires: sessions last one hour by default. Each developer can prepare up to 10 active package sessions at a time. Prepare a new session after expiry.

← Data dictionary →