@doubao-dev/cli 1.0.0-rc.11 → 1.0.0-rc.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/691.js +5 -5
- package/dist/command~3.js +2 -2
- package/dist/draft.js +2 -2
- package/dist/session.js +1 -1
- package/dist/skills/doubao-plugin-cli/SKILL.md +4 -3
- package/dist/skills/doubao-plugin-cli/references/cli/development.md +4 -2
- package/dist/skills/doubao-plugin-cli/references/cli/project.md +4 -2
- package/dist/skills/doubao-plugin-cli/references/cli/release.md +5 -3
- package/dist/skills/doubao-plugin-cli/references/examples/todo-example.md +35 -9
- package/dist/skills/doubao-plugin-cli/references/examples/workbench-example.md +1 -1
- package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/integration.md +25 -4
- package/dist/skills/doubao-plugin-cli/references/protocols/workbench.md +2 -2
- package/dist/skills/doubao-plugin-cli/references/upstream/SOURCES.md +11 -3
- package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.mdx +139 -147
- package/dist/skills/miaoda-mcp-dev/SKILL.md +20 -0
- package/dist/skills/miaoda-mcp-dev/references/app-plugin-mcp.md +9 -0
- package/dist/skills/miaoda-mcp-dev/references/development.md +62 -0
- package/dist/skills/miaoda-mcp-dev/references/todo-example.md +128 -0
- package/package.json +3 -3
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- For full edit history, see specification/draft/apps.mdx -->
|
|
1
|
+
<!-- For full edit history, see specification/draft/apps.mdx. Local corrections are recorded in SOURCES.md. -->
|
|
2
2
|
|
|
3
3
|
# SEP-1865: MCP Apps: Interactive User Interfaces for MCP
|
|
4
4
|
|
|
@@ -414,57 +414,58 @@ MCP Apps uses JSON-RPC 2.0 over `postMessage` for iframe-host communication. UI
|
|
|
414
414
|
|
|
415
415
|
### Transport Layer
|
|
416
416
|
|
|
417
|
-
|
|
417
|
+
The View connects to the Host via `postMessage`. The Apps handshake uses `ui/initialize` with `appInfo`, `appCapabilities`, and `protocolVersion`, followed by `ui/notifications/initialized`. The Host-to-Server handshake has its own [capability negotiation](#clientserver-capability-negotiation).
|
|
418
|
+
|
|
419
|
+
With `@modelcontextprotocol/ext-apps`, `App.connect()` handles the View handshake:
|
|
418
420
|
|
|
419
421
|
```typescript
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
const
|
|
423
|
-
|
|
422
|
+
import { App } from "@modelcontextprotocol/ext-apps";
|
|
423
|
+
|
|
424
|
+
const app = new App(
|
|
425
|
+
{ name: "My UI", version: "1.0.0" },
|
|
426
|
+
{ availableDisplayModes: ["fullscreen"] },
|
|
427
|
+
);
|
|
428
|
+
await app.connect();
|
|
424
429
|
```
|
|
425
430
|
|
|
426
|
-
|
|
431
|
+
The same handshake can be sent as JSON-RPC over `postMessage`:
|
|
427
432
|
|
|
428
433
|
```typescript
|
|
429
434
|
let nextId = 1;
|
|
430
|
-
function sendRequest(method: string, params:
|
|
435
|
+
function sendRequest(method: string, params: Record<string, unknown>) {
|
|
431
436
|
const id = nextId++;
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
reject(new Error(`Unsupported message: ${JSON.stringify(data)}`));
|
|
437
|
+
return new Promise<unknown>((resolve, reject) => {
|
|
438
|
+
function onResponse(event: MessageEvent) {
|
|
439
|
+
const response = event.data;
|
|
440
|
+
if (event.source !== window.parent || response?.jsonrpc !== "2.0" || response.id !== id) {
|
|
441
|
+
return;
|
|
442
|
+
}
|
|
443
|
+
if (response.error) {
|
|
444
|
+
window.removeEventListener("message", onResponse);
|
|
445
|
+
reject(new Error(response.error.message));
|
|
446
|
+
} else if ("result" in response) {
|
|
447
|
+
window.removeEventListener("message", onResponse);
|
|
448
|
+
resolve(response.result);
|
|
445
449
|
}
|
|
446
|
-
});
|
|
447
|
-
});
|
|
448
|
-
}
|
|
449
|
-
function sendNotification(method: string, params: any) {
|
|
450
|
-
window.parent.postMessage({ jsonrpc: "2.0", method, params }, '*');
|
|
451
|
-
}
|
|
452
|
-
function onNotification(method: string, handler: (params: any) => void) {
|
|
453
|
-
window.addEventListener('message', function listener(event) {
|
|
454
|
-
if (event.data?.method === method) {
|
|
455
|
-
handler(event.data.params);
|
|
456
450
|
}
|
|
451
|
+
window.addEventListener("message", onResponse);
|
|
452
|
+
window.parent.postMessage({ jsonrpc: "2.0", id, method, params }, "*");
|
|
457
453
|
});
|
|
458
454
|
}
|
|
455
|
+
function sendNotification(method: string, params: Record<string, unknown>) {
|
|
456
|
+
window.parent.postMessage({ jsonrpc: "2.0", method, params }, "*");
|
|
457
|
+
}
|
|
459
458
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
clientInfo: {name: "My UI", version: "1.0.0"},
|
|
459
|
+
const initializeResult = await sendRequest("ui/initialize", {
|
|
460
|
+
appCapabilities: { availableDisplayModes: ["fullscreen"] },
|
|
461
|
+
appInfo: { name: "My UI", version: "1.0.0" },
|
|
464
462
|
protocolVersion: "2026-01-26",
|
|
465
463
|
});
|
|
464
|
+
sendNotification("ui/notifications/initialized", {});
|
|
466
465
|
```
|
|
467
466
|
|
|
467
|
+
Declare `appCapabilities.tools` only if the View exposes its own tools to the Host. The Host advertises support for proxying calls to server tools through `hostCapabilities.serverTools`.
|
|
468
|
+
|
|
468
469
|
Hosts act as MCP servers (that can proxy the actual MCP server), receiving and handling requests from UI iframes.
|
|
469
470
|
|
|
470
471
|
### Sandbox proxy
|
|
@@ -513,8 +514,8 @@ When the View sends an `ui/initialize` request to the Host, it MUST include its
|
|
|
513
514
|
|
|
514
515
|
```typescript
|
|
515
516
|
interface McpUiAppCapabilities {
|
|
516
|
-
/** Experimental features
|
|
517
|
-
experimental?:
|
|
517
|
+
/** Experimental features keyed by identifier. */
|
|
518
|
+
experimental?: Record<string, object>;
|
|
518
519
|
/** App exposes MCP-style tools that the host can call. */
|
|
519
520
|
tools?: {
|
|
520
521
|
/** App supports tools/list_changed notifications. */
|
|
@@ -621,15 +622,25 @@ Example:
|
|
|
621
622
|
|
|
622
623
|
### Host Capabilities
|
|
623
624
|
|
|
624
|
-
`
|
|
625
|
-
They describe the features and capabilities that the Host supports.
|
|
625
|
+
`hostCapabilities` in the `ui/initialize` result describes the features supplied by the current Host. The following shape follows `@modelcontextprotocol/ext-apps@^1.7.5`. The View checks the advertised capability before using its associated feature.
|
|
626
626
|
|
|
627
627
|
```typescript
|
|
628
|
+
interface McpUiSupportedContentBlockModalities {
|
|
629
|
+
text?: {};
|
|
630
|
+
image?: {};
|
|
631
|
+
audio?: {};
|
|
632
|
+
resource?: {};
|
|
633
|
+
resourceLink?: {};
|
|
634
|
+
structuredContent?: {};
|
|
635
|
+
}
|
|
636
|
+
|
|
628
637
|
interface HostCapabilities {
|
|
629
|
-
/** Experimental features
|
|
630
|
-
experimental?:
|
|
638
|
+
/** Experimental features keyed by identifier. */
|
|
639
|
+
experimental?: Record<string, object>;
|
|
631
640
|
/** Host supports opening external URLs. */
|
|
632
641
|
openLinks?: {};
|
|
642
|
+
/** Host supports file downloads via ui/download-file. */
|
|
643
|
+
downloadFile?: {};
|
|
633
644
|
/** Host can proxy tool calls to the MCP server. */
|
|
634
645
|
serverTools?: {
|
|
635
646
|
/** Host supports tools/list_changed notifications. */
|
|
@@ -642,6 +653,15 @@ interface HostCapabilities {
|
|
|
642
653
|
};
|
|
643
654
|
/** Host accepts log messages. */
|
|
644
655
|
logging?: {};
|
|
656
|
+
/** Host supports these content types in ui/message. */
|
|
657
|
+
message?: McpUiSupportedContentBlockModalities;
|
|
658
|
+
/** Host supports these content types in ui/update-model-context. */
|
|
659
|
+
updateModelContext?: McpUiSupportedContentBlockModalities;
|
|
660
|
+
/** Host accepts sampling/createMessage requests from the View. */
|
|
661
|
+
sampling?: {
|
|
662
|
+
/** Host supports tools and toolChoice in sampling requests. */
|
|
663
|
+
tools?: {};
|
|
664
|
+
};
|
|
645
665
|
/** Sandbox configuration applied by the host. */
|
|
646
666
|
sandbox?: {
|
|
647
667
|
/** Permissions granted by the host (camera, microphone, geolocation, clipboard-write). */
|
|
@@ -995,43 +1015,27 @@ MCP Apps introduces additional JSON-RPC methods for UI-specific functionality:
|
|
|
995
1015
|
|
|
996
1016
|
Host SHOULD open the URL in the user's default browser or a new tab.
|
|
997
1017
|
|
|
998
|
-
`ui/
|
|
1018
|
+
`ui/download-file` - Request a file download through the Host
|
|
999
1019
|
|
|
1000
|
-
|
|
1001
|
-
// Request
|
|
1002
|
-
{
|
|
1003
|
-
jsonrpc: "2.0",
|
|
1004
|
-
id: 2,
|
|
1005
|
-
method: "ui/message",
|
|
1006
|
-
params: {
|
|
1007
|
-
role: "user",
|
|
1008
|
-
content: {
|
|
1009
|
-
type: "text",
|
|
1010
|
-
text: string
|
|
1011
|
-
}
|
|
1012
|
-
}
|
|
1013
|
-
}
|
|
1020
|
+
The View checks `hostCapabilities.downloadFile` before sending this request. The SDK's `App.downloadFile()` takes `{ contents: (EmbeddedResource | ResourceLink)[] }`. The response can include `isError: true` if the download fails or is declined.
|
|
1014
1021
|
|
|
1015
|
-
|
|
1016
|
-
{
|
|
1017
|
-
jsonrpc: "2.0",
|
|
1018
|
-
id: 2,
|
|
1019
|
-
result: {} // Empty result on success
|
|
1020
|
-
}
|
|
1022
|
+
`ui/message` - Send message content to the host's chat interface
|
|
1021
1023
|
|
|
1022
|
-
|
|
1024
|
+
```json
|
|
1023
1025
|
{
|
|
1024
|
-
jsonrpc: "2.0",
|
|
1025
|
-
id: 2,
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1026
|
+
"jsonrpc": "2.0",
|
|
1027
|
+
"id": 2,
|
|
1028
|
+
"method": "ui/message",
|
|
1029
|
+
"params": {
|
|
1030
|
+
"role": "user",
|
|
1031
|
+
"content": [{ "type": "text", "text": "Show the latest report." }]
|
|
1029
1032
|
}
|
|
1030
1033
|
}
|
|
1031
1034
|
```
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
+
|
|
1036
|
+
The response's `result` can be `{}` on success or `{ "isError": true }` if the Host rejected or failed to deliver the message.
|
|
1037
|
+
|
|
1038
|
+
The Host SHOULD add the message to the conversation context, preserving the specified role. The Host MAY request user consent.
|
|
1035
1039
|
|
|
1036
1040
|
`ui/request-display-mode` - Request host to change display mode
|
|
1037
1041
|
|
|
@@ -1103,33 +1107,29 @@ Host behavior:
|
|
|
1103
1107
|
|
|
1104
1108
|
#### Notifications (Host → View)
|
|
1105
1109
|
|
|
1106
|
-
`ui/notifications/tool-input` -
|
|
1110
|
+
`ui/notifications/tool-input` - Deliver the tool's complete input
|
|
1107
1111
|
|
|
1108
|
-
```
|
|
1112
|
+
```json
|
|
1109
1113
|
{
|
|
1110
|
-
jsonrpc: "2.0",
|
|
1111
|
-
method: "ui/notifications/tool-input",
|
|
1112
|
-
params: {
|
|
1113
|
-
arguments: Record<string, unknown> // Tool input arguments
|
|
1114
|
-
}
|
|
1114
|
+
"jsonrpc": "2.0",
|
|
1115
|
+
"method": "ui/notifications/tool-input",
|
|
1116
|
+
"params": { "arguments": { "location": "San Francisco" } }
|
|
1115
1117
|
}
|
|
1116
1118
|
```
|
|
1117
1119
|
|
|
1118
|
-
Host sends this notification after
|
|
1120
|
+
Host sends this notification after receiving `ui/notifications/initialized`, when the tool input becomes available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`. The SDK accepts `params: {}` when the tool call supplies no arguments.
|
|
1119
1121
|
|
|
1120
1122
|
`ui/notifications/tool-input-partial` - Host MAY send this notification zero or more times while the agent is streaming tool arguments, before `ui/notifications/tool-input` is sent.
|
|
1121
1123
|
|
|
1122
|
-
```
|
|
1124
|
+
```json
|
|
1123
1125
|
{
|
|
1124
|
-
jsonrpc: "2.0",
|
|
1125
|
-
method: "ui/notifications/tool-input-partial",
|
|
1126
|
-
params: {
|
|
1127
|
-
arguments: Record<string, unknown> // Tool input arguments
|
|
1128
|
-
}
|
|
1126
|
+
"jsonrpc": "2.0",
|
|
1127
|
+
"method": "ui/notifications/tool-input-partial",
|
|
1128
|
+
"params": { "arguments": { "location": "San" } }
|
|
1129
1129
|
}
|
|
1130
1130
|
```
|
|
1131
1131
|
|
|
1132
|
-
The arguments object represents best-effort recovery of incomplete JSON, with unclosed structures automatically closed to produce valid JSON. Host behavior (optional):
|
|
1132
|
+
The optional `params.arguments` object represents best-effort recovery of incomplete JSON, with unclosed structures automatically closed to produce valid JSON. Host behavior (optional):
|
|
1133
1133
|
|
|
1134
1134
|
- MAY parse the agent's partial JSON output by closing unclosed brackets/braces
|
|
1135
1135
|
- MAY send recovered arguments as they become available during streaming
|
|
@@ -1156,77 +1156,67 @@ Host MUST send this notification when tool execution completes (if the View is d
|
|
|
1156
1156
|
|
|
1157
1157
|
`ui/notifications/tool-cancelled` - Tool execution was cancelled
|
|
1158
1158
|
|
|
1159
|
-
```
|
|
1159
|
+
```json
|
|
1160
1160
|
{
|
|
1161
|
-
jsonrpc: "2.0",
|
|
1162
|
-
method: "ui/notifications/tool-cancelled",
|
|
1163
|
-
params: {
|
|
1164
|
-
reason: string
|
|
1165
|
-
}
|
|
1161
|
+
"jsonrpc": "2.0",
|
|
1162
|
+
"method": "ui/notifications/tool-cancelled",
|
|
1163
|
+
"params": { "reason": "user cancelled" }
|
|
1166
1164
|
}
|
|
1167
1165
|
```
|
|
1168
1166
|
|
|
1169
|
-
Host MUST send this notification if the tool execution was cancelled
|
|
1167
|
+
Host MUST send this notification if the tool execution was cancelled. The optional `params.reason` can describe the cancellation.
|
|
1170
1168
|
|
|
1171
|
-
`ui/
|
|
1169
|
+
`ui/notifications/host-context-changed` - Host context has changed
|
|
1172
1170
|
|
|
1173
1171
|
```typescript
|
|
1174
1172
|
{
|
|
1175
1173
|
jsonrpc: "2.0",
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
params: {
|
|
1179
|
-
reason: string
|
|
1180
|
-
}
|
|
1174
|
+
method: "ui/notifications/host-context-changed",
|
|
1175
|
+
params: Partial<HostContext> // See HostContext type above
|
|
1181
1176
|
}
|
|
1177
|
+
```
|
|
1182
1178
|
|
|
1183
|
-
|
|
1184
|
-
{
|
|
1185
|
-
jsonrpc: "2.0",
|
|
1186
|
-
id: 1,
|
|
1187
|
-
result: {} // Empty result on success
|
|
1188
|
-
}
|
|
1179
|
+
Host MAY send this notification when any context field changes (e.g., theme toggle, display mode change, device orientation change, window/panel resize). This notification contains partial updates - the View SHOULD merge received fields with its current context state.
|
|
1189
1180
|
|
|
1190
|
-
|
|
1181
|
+
#### Requests (Host → View)
|
|
1182
|
+
|
|
1183
|
+
`ui/resource-teardown` - Request graceful shutdown of the View
|
|
1184
|
+
|
|
1185
|
+
```json
|
|
1191
1186
|
{
|
|
1192
|
-
jsonrpc: "2.0",
|
|
1193
|
-
id: 1,
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
message: "Teardown error"
|
|
1197
|
-
}
|
|
1187
|
+
"jsonrpc": "2.0",
|
|
1188
|
+
"id": 1,
|
|
1189
|
+
"method": "ui/resource-teardown",
|
|
1190
|
+
"params": {}
|
|
1198
1191
|
}
|
|
1199
1192
|
```
|
|
1200
1193
|
|
|
1201
|
-
Host MUST send this
|
|
1202
|
-
|
|
1194
|
+
Host MUST send this request with an empty parameter object before tearing down the UI resource. The View returns an empty result on success or a JSON-RPC error on failure. Host SHOULD wait for a response before tearing down the resource to prevent data loss.
|
|
1195
|
+
|
|
1196
|
+
#### Notifications (View → Host)
|
|
1203
1197
|
|
|
1204
1198
|
`ui/notifications/size-changed` - View's size changed
|
|
1205
1199
|
|
|
1206
|
-
```
|
|
1200
|
+
```json
|
|
1207
1201
|
{
|
|
1208
|
-
jsonrpc: "2.0",
|
|
1209
|
-
method: "ui/notifications/size-changed",
|
|
1210
|
-
params: {
|
|
1211
|
-
width: number, // Viewport width in pixels
|
|
1212
|
-
height: number // Viewport height in pixels
|
|
1213
|
-
}
|
|
1202
|
+
"jsonrpc": "2.0",
|
|
1203
|
+
"method": "ui/notifications/size-changed",
|
|
1204
|
+
"params": { "width": 640, "height": 400 }
|
|
1214
1205
|
}
|
|
1215
1206
|
```
|
|
1216
1207
|
|
|
1217
|
-
The View SHOULD send this notification when rendered content
|
|
1208
|
+
The View SHOULD send this notification when its rendered content size changes, for example using the ResizeObserver API. Each dimension is optional and expressed in pixels.
|
|
1218
1209
|
|
|
1219
|
-
`ui/notifications/
|
|
1210
|
+
`ui/notifications/request-teardown` - Ask the Host to close the View
|
|
1220
1211
|
|
|
1221
|
-
```
|
|
1212
|
+
```json
|
|
1222
1213
|
{
|
|
1223
|
-
jsonrpc: "2.0",
|
|
1224
|
-
method: "ui/notifications/
|
|
1225
|
-
params: Partial<HostContext> // See HostContext type above
|
|
1214
|
+
"jsonrpc": "2.0",
|
|
1215
|
+
"method": "ui/notifications/request-teardown"
|
|
1226
1216
|
}
|
|
1227
1217
|
```
|
|
1228
1218
|
|
|
1229
|
-
|
|
1219
|
+
In SDK v1.7.5, `App.requestTeardown()` sends this notification. It has no reply. If the Host decides to close the View, it sends `ui/resource-teardown` to allow the View to clean up.
|
|
1230
1220
|
|
|
1231
1221
|
#### Reserved Messages (Sandbox Proxy)
|
|
1232
1222
|
|
|
@@ -1528,28 +1518,30 @@ Future versions may add additional settings:
|
|
|
1528
1518
|
|
|
1529
1519
|
#### Server Behavior
|
|
1530
1520
|
|
|
1531
|
-
|
|
1521
|
+
Register the tool before connecting the server transport. After the MCP client initializes, check its capabilities and add UI metadata when it advertises the Apps MIME type. Register the dashboard resource at `ui://weather-server/dashboard` before connecting. If the server already has an `oninitialized` handler, add the metadata update to that handler.
|
|
1532
1522
|
|
|
1533
1523
|
```typescript
|
|
1534
1524
|
import { getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
|
|
1535
|
-
|
|
1536
|
-
|
|
1537
|
-
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
|
|
1541
|
-
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
}
|
|
1545
|
-
});
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1525
|
+
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
1526
|
+
import { z } from "zod";
|
|
1527
|
+
|
|
1528
|
+
function registerWeatherTool(server: McpServer, getWeather: (location: string) => Promise<string>) {
|
|
1529
|
+
const inputSchema = z.object({ location: z.string() });
|
|
1530
|
+
const tool = server.registerTool("get_weather", {
|
|
1531
|
+
description: "Get current weather",
|
|
1532
|
+
inputSchema,
|
|
1533
|
+
}, async ({ location }) => ({
|
|
1534
|
+
content: [{ type: "text" as const, text: await getWeather(location) }]
|
|
1535
|
+
}));
|
|
1536
|
+
|
|
1537
|
+
server.server.oninitialized = () => {
|
|
1538
|
+
const ui = getUiCapability(server.server.getClientCapabilities());
|
|
1539
|
+
tool.update({
|
|
1540
|
+
_meta: ui?.mimeTypes?.includes(RESOURCE_MIME_TYPE)
|
|
1541
|
+
? { ui: { resourceUri: "ui://weather-server/dashboard" } }
|
|
1542
|
+
: {}
|
|
1543
|
+
});
|
|
1544
|
+
};
|
|
1553
1545
|
}
|
|
1554
1546
|
```
|
|
1555
1547
|
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: miaoda-mcp-dev
|
|
3
|
+
description: 使用 lark-cli 在妙搭开发、部署和排查业务 MCP 服务及 MCP Apps。用户选定妙搭或维护已有妙搭服务时使用。
|
|
4
|
+
metadata:
|
|
5
|
+
display_name: 妙搭 MCP 开发
|
|
6
|
+
display_description: 在妙搭实现、发布和验证 MCP 服务及交互界面。
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 妙搭 MCP 开发
|
|
10
|
+
|
|
11
|
+
通过 `lark-cli` 初始化或获取工程、本地编码、发布并交付真实 MCP endpoint。已选 MCP Apps 时实现对应 UI;已有项目沿用原身份与实现。
|
|
12
|
+
|
|
13
|
+
| 当前任务 | 读取 |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| 工具准备、工程接线与本地开发 | [工作流程](references/development.md#平台交互) |
|
|
16
|
+
| 发布、地址与鉴权、服务验证 | [发布与接入](references/development.md#发布授权与代码来源) |
|
|
17
|
+
| 实现待办示例 | [妙搭 TODO 适配](references/todo-example.md) |
|
|
18
|
+
| 为已有应用插件提供实体工具 | [应用插件适配](references/app-plugin-mcp.md) |
|
|
19
|
+
|
|
20
|
+
MCP 协议、MCP Apps 接线与插件打包使用 `doubao-plugin-cli` Skill。服务交付包含应用与环境、正式 endpoint、鉴权、发布和验证结果;宿主内安装与体验由调用方继续。
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# 应用插件的妙搭 MCP 适配
|
|
2
|
+
|
|
3
|
+
已有应用插件继续使用原界面,妙搭提供业务工具与数据;明确选定 MCP Apps 时再实现 HTML 资源。
|
|
4
|
+
|
|
5
|
+
连接与用户授权按 [妙搭鉴权](development.md#连接地址与鉴权) 处理,保留正式 OAuth 地址,由目标客户端完成飞书用户授权。管理账号登录与开发代理身份不能代替安装用户身份。
|
|
6
|
+
|
|
7
|
+
远端实体出卡的 `outputSchema`、`structuredContent.entities`、实体主键及 Widget 绑定规则,读取 `doubao-plugin-app` Skill 的 `references/tools-and-cards.md`。普通业务查询保持自身 schema。
|
|
8
|
+
|
|
9
|
+
妙搭的 Zod 对象 Schema 会限制额外字段。实现实体工具时,将实体契约要求的 `entity_type`、业务 ID 及实际字段显式纳入 Schema,核对平台 SDK 处理后的真实 `tools/list` 与 `tools/call`,再验证应用插件中的出卡结果。
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# 妙搭 MCP 开发
|
|
2
|
+
|
|
3
|
+
## 平台交互
|
|
4
|
+
|
|
5
|
+
使用 `lark-cli apps` 管理妙搭,参数不明时查询对应子命令的 `--help`。只有父级帮助、没有子命令签名时,即使退出码为 0 也不能认定命令可用。
|
|
6
|
+
|
|
7
|
+
缺少 CLI 时按 [lark-cli 官方仓库](https://github.com/larksuite/cli) 的安装说明准备;宿主提供 `lark-apps`、`lark-shared` Skill 时复用其平台操作与认证指引。已有 CLI 与登录态直接复用,不依赖豆包专有工具。
|
|
8
|
+
|
|
9
|
+
## 定位应用与源码
|
|
10
|
+
|
|
11
|
+
修改已有应用时,使用 `apps +list` 查找原应用,`+get` 读取详情,沿用原应用身份。使用当前可用的 `+init` 或 `+export` 获取源码;`+export` 导出默认分支最近一次提交,不含沙箱未提交改动。生成器尚未提交的内容由原生成会话回收,不能用旧归档覆盖。
|
|
12
|
+
|
|
13
|
+
源码查询失败时按实际错误核对账号和项目权限。文件存储通过 `+file-list` / `+file-download` 获取,与源码归档分别处理。
|
|
14
|
+
|
|
15
|
+
## 工程接线
|
|
16
|
+
|
|
17
|
+
本地开发入口见[发布与代码来源](#发布授权与代码来源)。NestJS 全栈模板生成 `.agents/skills/mcp-guide/SKILL.md`,按需读取工具、界面、身份、调试及客户端接入章节,SDK 导入与构建方式以工程指引及已安装类型为准。
|
|
18
|
+
|
|
19
|
+
模板内置 `POST /__innerapi__/mcp`。工具类加入 NestJS 模块的 `providers`,模块接入 `app.module.ts`。MCP Apps 位于 `server/mcp/ui/<entry>/`,构建生成单文件 HTML,通过 UI Resource 返回,沿用模板接线。
|
|
20
|
+
|
|
21
|
+
MCP 标准与宿主扩展使用 `doubao-plugin-cli` Skill;平台 CLI 用于开发管理,运行时使用平台 SDK/API 和实际用户身份。
|
|
22
|
+
|
|
23
|
+
需要 Web 首页时,在 `client/src/app.tsx` 的首页路由实现服务名称、用途和使用入口。Web 页面与 MCP Apps 资源分别验证,页面上线不表示 MCP 已接通。
|
|
24
|
+
|
|
25
|
+
## 开发态验证
|
|
26
|
+
|
|
27
|
+
NestJS 模板用 `npm run dev` 启动;`apps +env-pull` 提供本地开发身份,启动与代理方式按工程 `mcp-guide`。
|
|
28
|
+
|
|
29
|
+
开发态地址为 `http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp`,端口与前缀取实际启动日志及工程配置。身份由开发代理注入,直连 NestJS 端口不具备该身份。
|
|
30
|
+
|
|
31
|
+
使用 `dbx inspect --mcp-server <开发态地址> --no-open` 检查工具、资源和界面交互。开发态代理验证、线上用户授权与目标宿主体验分别记录。
|
|
32
|
+
|
|
33
|
+
## 发布授权与代码来源
|
|
34
|
+
|
|
35
|
+
用户已授权发布且目标应用、环境和范围明确时执行;需要发布但缺少授权时,完成开发准备后交接具体目标与影响。
|
|
36
|
+
|
|
37
|
+
| 当前命令集 | 工程与发布方式 |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| `+create`、`+init`、`+release-create` | 应用类型为 `full_stack`,`+init` 获取工程,身份保存在 `.spark/meta.json`;源码提交并推送到 `sprint/default` 后发布该分支,`main` 为平台发布快照 |
|
|
40
|
+
| `+init-template`、`+deploy` | 使用 `--type full_stack` 初始化本地工程,身份绑定与发布参数按生成模板及命令帮助处理 |
|
|
41
|
+
|
|
42
|
+
按当前 CLI 帮助选用一条流程,不混用两种工程配置。具体命令示例见 [TODO 适配](todo-example.md#发布)。已有生成器完成发布时核对本次回执即可;转为本地发布前确认已取得完整的本次源码。
|
|
43
|
+
|
|
44
|
+
MCP Apps UI 随服务构建与发布,不另走静态 HTML 发布流程。
|
|
45
|
+
|
|
46
|
+
## 发布结果
|
|
47
|
+
|
|
48
|
+
查询本次 `release_id` 的成功终态与真实 `online_url`。异步发布约每 20 秒查一次;结果未知先查原发布,不重复创建。历史 `is_published` 不证明本次已上线。长时间等待时说明进展,失败或需要用户操作时交接实际状态。
|
|
49
|
+
|
|
50
|
+
## 连接地址与鉴权
|
|
51
|
+
|
|
52
|
+
从同一应用、同一环境的发布结果或工程 `mcp-guide` 取得 MCP 连接方式。当前 NestJS 模板发布并获准启用后,可用当前 CLI 支持的 `apps +mcp-get --app-id <app_id>` 获取连接信息。保持正式 URL 原样,不从 Web 预览地址或应用 ID 拼接。
|
|
53
|
+
|
|
54
|
+
`+mcp-get` 与 `+mcp-key-create` 可能创建运行态凭据,仅在已授权接入范围内执行,不作为只读探针。含凭据的 URL 按秘密处理,不放入聊天或可分发包。
|
|
55
|
+
|
|
56
|
+
用真实 MCP 初始化响应或有效 OAuth 发现元数据核对连接;有效 OAuth challenge 的 401 进入客户端授权,普通网页登录跳转不能代替 MCP 授权。飞书用户 OAuth 由目标客户端完成,管理登录与业务用户授权分别验证。
|
|
57
|
+
|
|
58
|
+
## 服务交接
|
|
59
|
+
|
|
60
|
+
交回应用 ID、环境、发布回执、正式 MCP endpoint、传输和鉴权方式、实际工具与 UI 验证结果及缺项。引用既有部署结果或生成回执时确认服务归属;不回传凭据。
|
|
61
|
+
|
|
62
|
+
按目标验收核心业务工具,MCP Apps 还需验证资源读取、工具结果进入 UI 及一次真实交互。主流程接入插件后继续目标宿主验证,不将发布成功或 Inspector 通过视为宿主体验通过。
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# TODO 妙搭实现
|
|
2
|
+
|
|
3
|
+
实现 `doubao-plugin-cli` Skill 的 `references/examples/todo-example.md` 所定义的业务契约与验收目标。本页仅说明 NestJS 模板中的平台实现,API 写法以工程 `mcp-guide` 和已安装 SDK 类型为准。
|
|
4
|
+
|
|
5
|
+
## 创建工程与目录
|
|
6
|
+
|
|
7
|
+
宿主提供 `+init` 与 `+release-create` 时:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
lark-cli apps +create --name "我的待办 MCP" --app-type full_stack --as user
|
|
11
|
+
# app_id 使用上一步返回值;已有应用跳过创建
|
|
12
|
+
lark-cli apps +init --app-id <app_id> --dir ./todo-mcp --as user
|
|
13
|
+
cd ./todo-mcp
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
初始化后读取工程 `.agents/skills/mcp-guide/SKILL.md`。本例新增或修改的位置:
|
|
17
|
+
|
|
18
|
+
```text
|
|
19
|
+
todo-mcp/
|
|
20
|
+
├── client/src/app.tsx # Web 预览首页路由
|
|
21
|
+
├── server/
|
|
22
|
+
│ ├── app.module.ts # 配置 MCP 名称、说明,注册 TodoTools
|
|
23
|
+
│ ├── database/schema.ts # 平台生成的数据库类型
|
|
24
|
+
│ └── mcp/
|
|
25
|
+
│ ├── tools/todo.tools.ts # 四个工具及可选 UI Resource
|
|
26
|
+
│ ├── skills/todo-list/SKILL.md # 给消费方 Agent 的待办使用说明
|
|
27
|
+
│ └── ui/todos/ # 仅 MCP Apps 需要
|
|
28
|
+
│ ├── index.html
|
|
29
|
+
│ └── main.tsx
|
|
30
|
+
└── .spark/meta.json # 初始化器写入的应用身份
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
界面的 TypeScript 配置及构建入口按工程 `mcp-guide` 的 MCP Apps 章节准备。工具类加入 `app.module.ts` 的 `providers`;在已有 `PlatformModule.forRoot()` 中合并 `mcp.serverName: 'todo-list'` 和 `mcp.instructions`,例如“管理个人待办,从 todo_list 查询开始”。
|
|
34
|
+
|
|
35
|
+
## 数据与工具适配
|
|
36
|
+
|
|
37
|
+
通过 `lark-cli apps +db-execute` 按通用业务契约建立 `todos` 表,以 UUID 为主键,`owner_id` 保存所属用户。审计列、RLS 和 Schema 生成沿用工程数据库指引;Drizzle 字段名以 `server/database/schema.ts` 为准。
|
|
38
|
+
|
|
39
|
+
身份取 `ctx.user.userId`。查询、更新和删除都同时限制所属用户;创建时写入该用户。工具只返回表中的业务字段,不把整行审计信息传给模型。
|
|
40
|
+
|
|
41
|
+
以下是 `todo.tools.ts` 中创建工具的完整片段;其余工具按通用示例的契约在同一类中实现。`todos` 从平台生成的 Schema 导入,数据库由平台注入:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { Inject } from '@nestjs/common';
|
|
45
|
+
import { z } from 'zod';
|
|
46
|
+
import {
|
|
47
|
+
DRIZZLE_DATABASE, McpTools, McpTool,
|
|
48
|
+
type PostgresJsDatabase, type Infer, type McpContext, type McpToolResult
|
|
49
|
+
} from '@lark-apaas/fullstack-nestjs-core';
|
|
50
|
+
import { todos } from '../../database/schema';
|
|
51
|
+
|
|
52
|
+
const CreateInput = {
|
|
53
|
+
title: z.string().trim().min(1).max(200).describe('待办标题')
|
|
54
|
+
};
|
|
55
|
+
const TodoOutput = {
|
|
56
|
+
todo: z.object({ id: z.string(), title: z.string(), completed: z.boolean() })
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
@McpTools()
|
|
60
|
+
export class TodoTools {
|
|
61
|
+
constructor(@Inject(DRIZZLE_DATABASE) private readonly db: PostgresJsDatabase) {}
|
|
62
|
+
|
|
63
|
+
@McpTool({
|
|
64
|
+
name: 'todo_create',
|
|
65
|
+
title: '添加待办',
|
|
66
|
+
description: '用户要求添加任务时创建本人待办,返回 ID、标题和完成状态;重复调用会新增。',
|
|
67
|
+
inputSchema: CreateInput,
|
|
68
|
+
outputSchema: TodoOutput,
|
|
69
|
+
annotations: {
|
|
70
|
+
readOnlyHint: false, destructiveHint: false,
|
|
71
|
+
idempotentHint: false, openWorldHint: false
|
|
72
|
+
}
|
|
73
|
+
})
|
|
74
|
+
async create(
|
|
75
|
+
input: Infer<typeof CreateInput>, ctx: McpContext
|
|
76
|
+
): Promise<McpToolResult<typeof TodoOutput>> {
|
|
77
|
+
const [todo] = await this.db.insert(todos)
|
|
78
|
+
.values({ title: input.title, ownerId: ctx.user.userId! })
|
|
79
|
+
.returning({ id: todos.id, title: todos.title, completed: todos.completed });
|
|
80
|
+
return { structuredContent: { todo } };
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
本模板默认要求用户身份,SDK 自动把 `structuredContent` 补充为可读文本结果。`server/mcp/skills/todo-list/SKILL.md` 描述四个工具的用法、ID 来源和错误处理;它由妙搭 SDK 提供给消费方,豆包插件包内的业务 Skill 由插件主流程维护。
|
|
86
|
+
|
|
87
|
+
## 可选 MCP Apps 界面
|
|
88
|
+
|
|
89
|
+
`todo_list` 的 `@McpTool` 增加 `ui: { resourceUri: 'ui://todo/list' }`。在同一工具类注册资源,相关符号从平台 SDK 导入:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
@McpUiResource({
|
|
93
|
+
uri: 'ui://todo/list', title: '我的待办',
|
|
94
|
+
description: '查看、添加和完成个人待办。',
|
|
95
|
+
csp: { connectDomains: [], resourceDomains: [] }
|
|
96
|
+
})
|
|
97
|
+
view() { return readMcpUiTemplate('todos'); }
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
上例空 CSP 适用于构建后的 HTML 无外部网络依赖的情况。接入外链资源或直接联网时,按 `doubao-plugin-cli` Skill 的 `references/protocols/mcp-apps/integration.md` 中「CSP 域名清单」补齐声明,并核对资源响应和宿主渲染。
|
|
101
|
+
|
|
102
|
+
`server/mcp/ui/todos/index.html` 提供 `root` 节点并加载 `main.tsx`。前端使用工程指引中的 `useApp` 连接宿主,在 `onAppCreated` 中注册 `ontoolresult`,按通用示例约定渲染 `structuredContent.items`。表单、勾选、删除与分页通过 `app.callServerTool` 调用相同业务工具。UI Resource 读取模板构建的 HTML,具体 `useApp` 接线按工程 `mcp-guide`;不另建网页 API 或 MCP 路由。
|
|
103
|
+
|
|
104
|
+
## 可选 Web 首页
|
|
105
|
+
|
|
106
|
+
本次交付需要 Web 预览时,在 `client/src/app.tsx` 首页路由展示服务名称、用途和实际使用入口。该页面与 MCP Apps 资源独立;宿主提出其他交付要求时一并实现。
|
|
107
|
+
|
|
108
|
+
## 验证
|
|
109
|
+
|
|
110
|
+
运行 `npm run dev`,从启动日志和工程配置取得开发态 MCP 地址,按 [开发态验证](development.md#开发态验证) 使用 Inspector,执行通用 TODO 示例的业务与 UI 检查。平台代理身份仅用于开发态,发布后继续验证实际用户授权。
|
|
111
|
+
|
|
112
|
+
## 发布
|
|
113
|
+
|
|
114
|
+
以下适用于已核实提供 `+init` 与 `+release-create` 的 CLI;另一命令集见 [发布入口](development.md#发布授权与代码来源)。
|
|
115
|
+
|
|
116
|
+
在工程目录提交本次源码与必要配置并发布:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
git add <本次源码与配置>
|
|
120
|
+
git commit -m "feat: add todo MCP service"
|
|
121
|
+
git push origin sprint/default
|
|
122
|
+
lark-cli apps +release-create --app-id <app_id> --branch sprint/default --as user
|
|
123
|
+
lark-cli apps +release-get --app-id <app_id> --release-id <release_id> --as user
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
命令差异和发布授权见[发布流程](development.md#发布授权与代码来源)。发布完成后按[连接地址与鉴权](development.md#连接地址与鉴权)取得线上 MCP endpoint,再交接插件接入;发布返回的 `online_url` 不作为 MCP endpoint。
|
|
127
|
+
|
|
128
|
+
发布完成后,由插件接入流程执行通用示例中的账号同步和目标宿主验收。
|