Manifest reference

This page lists the parts of a plugin that the marketplace reads and checks. Use it when you prepare a repository for listing, or when the scanner reports a problem you want to understand.

A plugin is a folder with a PLUGIN.md file. The YAML frontmatter at the top of the file is the plugin's manifest: it says what the plugin is and what it may access. The Markdown body below it holds the instructions the agent receives. The full plugin language, including tools, steps, expressions and UI, is specified in docs/PLUGIN-LANGUAGE.md. For an introduction, read Declarative plugins first.

---
spec: 1
id: canteen-menu
name: 食堂菜单
description: 今天各食堂的菜单和营业时间。
version: 1.0.0
author: alice
icon: food
network: [dining.pku.edu.cn]
tools:
  menu: tools/menu.yaml
widgets:
  today: widgets/today.json
dataSources:
  today: { tool: menu, args: { day: today }, ttl: 30m }
i18n:
  en: { name: Canteen menu, description: "Today's menus and opening hours." }
---

Use `menu` when the user asks what to eat or which canteen is open. Prices are in yuan.

Where the scanner looksCopy Anchor Link

The scanner reads the default branch of the repository through the GitHub API. It finds plugins in one of two ways.

1. If the root of the repository has a pku-harness.json file, the scanner checks only the folders listed there (up to 200), in the order given. This is useful in large monorepos:

   Copy Text

   { "plugins": ["plugins/canteen", "plugins/library-seat"] }

   "." means the root of the repository. If a listed folder has no manifest, the scanner reports an error.

2. Otherwise, every PLUGIN.md in the repository is a plugin, at any depth. The scanner skips folders that hold dependencies, tests or test data, so example manifests in them are never listed. The skipped folders are:

   • node_modules, and any folder whose name starts with .;
   • test, tests and __tests__;
   • fixtures, __fixtures__ and testdata;
   • e2e (end-to-end tests).

   A folder with one of these names is skipped wherever it appears in the path. For example, plugins/canteen/tests/PLUGIN.md is not listed. A folder named in pku-harness.json is always checked, whatever its name.

A folder holds at most one plugin. If a folder contains more than one kind of manifest, PLUGIN.md is used first, then pku-harness.plugin.json, then a package.json with a "pkuHarness" object (see remote MCP plugins).

You can also submit the URL of a sub-folder, such as https://github.com/owner/repo/tree/main/plugins. The scanner then looks only inside that folder.

FrontmatterCopy Anchor Link

The table lists every top-level field. Fields without "yes" are optional.

campus accepts these service names: card, its, treehole, blackboard, elective, cwfw, cwpay, bdkj, library, library-space, portal, and others the app knows. An unknown name is a warning.

abilities accepts verify, otp, todos, timetable, scheduler, browser, campusPage, sms, files, crypto and cloud. The declarative plugins guide lists the operations and effects of each one. Any other name is an error, because the app refuses it.

server declares server functions, which run on PKU harness Cloud (CLOUD-FUNCTIONS.md). A plugin with server needs cloud.disclosure, and it implies cloud.uses: [functions]. Server functions are off on the official server for now, so users of the official instance can't run them. Keep the work on the phone, or use your own backend.

The instructionsCopy Anchor Link

The Markdown body of PLUGIN.md becomes the plugin's instructions for the model. The app sends it with every prompt, so keep it short. Say when to use which tool and what the numbers mean. The marketplace shows the body on the plugin page, cut off at 20,000 characters, and warns when it is longer than 8,000 characters.

ToolsCopy Anchor Link

Each entry in tools is a tool the agent can call. It is either the path of a YAML file, such as tools/menu.yaml, or a tool written inline. Every tool needs a title, a description and an honest effect: read, write, money or public.

A tool can also have a summary: one short line, at most 80 characters, that tells people what the tool does. The description is written for the model and is often long. The summary is written for the user. The plugin page shows it under the tool's title, and the marketplace search includes it.

title: 学术日历
summary: 近期的学术讲座
description: >-
  Academic talks between two dates, sorted by start time. Default: today to 30 days ahead.
effect: read
untrusted: true

To show an English title and summary on the English marketplace, add them under i18n.en.tools.<name> in PLUGIN.md. A tool without an English summary shows the Chinese one.

i18n:
  en:
    name: Campus events
    description: Calendars of academic talks and campus activities.
    tools: { talks: { title: Academic talks, summary: Upcoming academic talks } }

FilesCopy Anchor Link

The app loads only the files that the frontmatter names in tools, shared, widgets and screens. It never lists a folder to find more. For each named path, the scanner checks that it:

• is relative to PLUGIN.md, with no .., no leading / and no URL scheme;
• exists in the repository (a missing file is an error);
• together with PLUGIN.md, stays within 512 KB in total (from the blob sizes in the GitHub tree).

The scanner also downloads each named tool file to read its title, summary and effect. The plugin page shows these as part of the permission sheet. Files that the frontmatter doesn't name, such as tests/, README.md and assets/, are ignored.

Derived capabilitiesCopy Anchor Link

The plugin page and the marketplace filters show a requires list. It contains everything you list in requires, plus everything your other declarations imply:

Install linksCopy Anchor Link

The page of each PLUGIN.md plugin shows how to install it:

• the install link, which is the GitHub folder URL on the default branch, for example https://github.com/alice/campus-tools/tree/main/canteen;
• an Open in app button with the deep link pkuharness://plugin?src=<url-encoded install link>;
• a QR code of that deep link.

The handle shown on the page is owner/repo/path.

Remote MCP pluginsCopy Anchor Link

A remote plugin runs on your own server and speaks the Model Context Protocol (MCP) over Streamable HTTP. The app connects to it as the MCP server mcp-<id>, so set your server's name to the plugin's id.

Describe a remote plugin with a PLUGIN.md that has a remote field and no tools. The tools come from the server, so any tools declared in the file are ignored, with a warning.

---
spec: 1
id: canteen-live
name: 食堂实时人数
description: 各食堂当前排队人数。
version: 1.0.0
author: alice
remote: { mcp: "https://canteen.example.com/mcp", auth: none }
---

Use the tools when the user asks how crowded a canteen is.

A remote server never receives the user's campus session. For that reason, campus on a remote plugin is a warning.

The older format: pku-harness.plugin.jsonCopy Anchor Link

Until remote.mcp in PLUGIN.md replaces it, the marketplace still reads pku-harness.plugin.json, and the "pkuHarness" object in package.json, for remote MCP servers. If you point $schema at /schema/plugin-manifest.v1.json, your editor checks the file as you type.

{
  "$schema": "https://<this site>/schema/plugin-manifest.v1.json",
  "id": "canteen-live",
  "name": "食堂实时人数",
  "description": "各食堂当前排队人数。",
  "endpoint": "https://canteen.example.com/mcp",
  "requires": ["network"],
  "scopes": ["dining.pku.edu.cn"]
}

pku-harness.plugin.json fieldsCopy Anchor Link

The id matters for more than the marketplace. The app installs the plugin as the MCP server mcp-<id> and uses that name to show that the plugin is installed. If your server's name is different, the app can't match the two.

The endpoint must use https:// and a public host, and it must not contain credentials or a query string.

Unknown fields are ignored with a warning, so a typo doesn't drop data without telling you.

In package.jsonCopy Anchor Link

{
  "name": "@campus-tools/library-seat",
  "version": "0.3.0",
  "description": "图书馆座位查询与预约提醒。",
  "license": "MIT",
  "pkuHarness": {
    "id": "library-seat",
    "name": "图书馆座位",
    "endpoint": "https://seat.example.com/mcp",
    "requires": ["network"],
    "scopes": ["seat.lib.pku.edu.cn"]
  }
}

description, version, license and homepage default to the package's own fields. Anything inside pkuHarness overrides them. A pkuHarness object without an id counts as SDK metadata and isn't listed. The bundled plugins use this form, { "builtin": true }.

Capabilities (requires)Copy Anchor Link

Each value below is shown to users on the plugin page, with the meaning in the right column.

A PLUGIN.md plugin gets campus-session by declaring campus; the app then signs the requests itself. A remote MCP server never gets a campus session, so the scanner warns when one asks for it.

A remote plugin runs on your server, so declare only what the phone has to provide.

Cloud disclosureCopy Anchor Link

If a plugin uses PKU harness Cloud, its cloud block must say in plain words what data leaves the device. The marketplace and the app both show these lines on the plugin's page.

"cloud": {
  "uses": ["store"],
  "e2e": true,
  "disclosure": { "zh": ["你的收藏列表会加密存到云端，用于多设备同步。"], "en": ["Your favourites are stored encrypted in the cloud to sync devices."] }
}

The scanner applies the same rules as cloudIssues() in the registry:

• uses has no duplicates;
• if uses is not empty, there is at least one disclosure.zh line that says in plain words what leaves the device;
• no line is empty;
• if disclosure.en is present, it translates every zh line;
• an external backend.url uses https.

What the scanner checksCopy Anchor Link

An error keeps a plugin out of the marketplace. A warning doesn't; it is shown on the plugin's page under Checks. An info note is a suggestion.

The scanner also has size limits:

• 100 plugins and 300 package.json files per repository;
• 40 tool files per plugin, and 400 per repository;
• 256 KB per downloaded file;
• 10 seconds per GitHub request.

If a repository is too big for one GitHub tree request, the scanner warns. Add a pku-harness.json that lists the plugin folders to fix this.