@modootoday/pmcp 0.18.0 → 0.18.2
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/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.mcp.json +1 -1
- package/CHANGELOG.md +112 -20
- package/CONTRIBUTING.md +71 -0
- package/README.md +98 -206
- package/SECURITY.md +17 -1
- package/dist/{apply-4IGTXOCQ.js → apply-JUTGS5WZ.js} +11 -11
- package/dist/{broadcast-3RY3OZGY.js → broadcast-CBMVOV3G.js} +4 -4
- package/dist/{chunk-SG5TPMKH.js → chunk-26WLNWDG.js} +2 -2
- package/dist/{chunk-ELAGZ635.js → chunk-2FIV63WC.js} +5 -5
- package/dist/{chunk-JUXNIXN4.js → chunk-3FCFAQDG.js} +2 -2
- package/dist/{chunk-EJBZGIDK.js → chunk-3IDXEV5E.js} +3 -3
- package/dist/chunk-65KAQSJP.js +7 -0
- package/dist/{chunk-665TA55Z.js → chunk-7HFIGCSL.js} +2 -2
- package/dist/{chunk-R4L6LJJ2.js → chunk-7UCZAN4J.js} +2 -2
- package/dist/{chunk-J6QLLQVL.js → chunk-A7VF7A35.js} +5 -5
- package/dist/{chunk-NZS5CD72.js → chunk-AJ4VXM2U.js} +20 -4
- package/dist/{chunk-25GHX674.js → chunk-D77IRGHO.js} +6 -6
- package/dist/{chunk-4VCC2NXE.js → chunk-DMZHQZ7P.js} +2 -2
- package/dist/{chunk-Q65R3XKX.js → chunk-EAWPJHJ7.js} +2 -2
- package/dist/{chunk-PLX3BOOS.js → chunk-F5QYZK7E.js} +2 -2
- package/dist/{chunk-YMHUM7AV.js → chunk-F5XMGOOX.js} +7 -1
- package/dist/{chunk-7BLPN3W6.js → chunk-FENOGX3U.js} +2 -2
- package/dist/{chunk-N5AQ3PP7.js → chunk-I2ZP2PSA.js} +5 -5
- package/dist/{chunk-UOCLRM7P.js → chunk-IG33DXLT.js} +16 -16
- package/dist/{chunk-RK4PYD7L.js → chunk-LBXO4VPG.js} +2 -2
- package/dist/{chunk-BVCTKPT3.js → chunk-LMUBBIE2.js} +2 -2
- package/dist/{chunk-Z4HRRXRF.js → chunk-LTZH5E3G.js} +6 -5
- package/dist/{chunk-MWFOUBFC.js → chunk-LW4TG7EL.js} +2 -2
- package/dist/{chunk-LAZQBMAU.js → chunk-NLEXKE7U.js} +3 -3
- package/dist/{chunk-ZH6R642Z.js → chunk-PKODFR5F.js} +2 -2
- package/dist/{chunk-IGYRMM62.js → chunk-QEF7EK3T.js} +2 -2
- package/dist/{chunk-MM2Y43LC.js → chunk-RPQOBHVU.js} +2 -2
- package/dist/{chunk-3NYG4SGU.js → chunk-TXQ7L33K.js} +3 -3
- package/dist/{chunk-PWSJJXLQ.js → chunk-VMHUEOT5.js} +8 -8
- package/dist/{chunk-65ZHM5RH.js → chunk-VRPMYPZU.js} +9 -9
- package/dist/{cli-VYCQJZ5X.js → cli-MI4ZCAZ3.js} +9 -9
- package/dist/{cli-ZTCBSDW4.js → cli-ZN7ZVDEZ.js} +3 -3
- package/dist/cli.js +4 -4
- package/dist/{completion-E7RRG3ZT.js → completion-ILSRB3LW.js} +3 -3
- package/dist/{diagnostics-XXH4FLUG.js → diagnostics-XKXVVQWH.js} +6 -6
- package/dist/{doctor-ZIOESU3N.js → doctor-O2E63YGO.js} +13 -13
- package/dist/{entry-ZNFCTDVE.js → entry-X6CSYQRQ.js} +10 -10
- package/dist/{exec-mcp-X6372BLE.js → exec-mcp-2PMWBPD7.js} +8 -8
- package/dist/{harness-F2XFDYXF.js → harness-L2KSI2ZB.js} +5 -5
- package/dist/harness-launch-gate.js +4 -4
- package/dist/harness-worker.js +6 -6
- package/dist/hook-body.js +7 -6
- package/dist/{hooks-FYE2L5RW.js → hooks-BHTA44X7.js} +3 -3
- package/dist/{host-GRY3VAHH.js → host-UIZAXXQH.js} +7 -7
- package/dist/{host-X6BR6X4O.js → host-UWK754BW.js} +20 -10
- package/dist/{host-run-GCA6H6SR.js → host-run-BI2OTZDZ.js} +5 -5
- package/dist/http.js +1 -1
- package/dist/{import-mcp-2TTBPVLY.js → import-mcp-GPKJI7DI.js} +6 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +13 -13
- package/dist/{init-627KFXTG.js → init-3C2Y7BNJ.js} +2 -2
- package/dist/{invoke-LW22Z6ET.js → invoke-44CJRVMK.js} +8 -8
- package/dist/{list-NGMSQ5SH.js → list-WL6L4J5H.js} +8 -8
- package/dist/{logout-6CSHUWWE.js → logout-F5EJ5MOU.js} +7 -7
- package/dist/{logs-SPB6AANY.js → logs-TBUA4UWU.js} +4 -4
- package/dist/{mailbox-7BV54Q4R.js → mailbox-BMTZOSZ7.js} +4 -4
- package/dist/{mainline-JQTTYJMI.js → mainline-KAD2ERLP.js} +2 -2
- package/dist/{mcp-2DKVU3SW.js → mcp-235QZN2A.js} +2 -2
- package/dist/{mcp-V23HC3LB.js → mcp-FJ2UQ4RH.js} +2 -2
- package/dist/{pause-FFAYRBWI.js → pause-7LILUVGL.js} +4 -4
- package/dist/{project-FY62G55N.js → project-5YV5CUEG.js} +4 -4
- package/dist/{resume-UU4HZIUP.js → resume-26VFAAMH.js} +4 -4
- package/dist/{run-OGA3P7FC.js → run-3AXTZSR7.js} +7 -7
- package/dist/{run-HALGEJNJ.js → run-3SOVRQIA.js} +4 -4
- package/dist/{serve-NBKT5BKY.js → serve-DQMKTFIV.js} +3 -3
- package/dist/{start-login-UIQYQBMC.js → start-login-YTZV6KMF.js} +7 -7
- package/dist/{status-NOOHW5WA.js → status-MROQ7WR7.js} +7 -7
- package/dist/{status-VHODZPXB.js → status-RO55QPKV.js} +4 -4
- package/dist/{status-XQANBVXW.js → status-UME2L33L.js} +11 -11
- package/dist/stdio.js +2 -2
- package/dist/{sweep-64JDCGK6.js → sweep-35LGQTTO.js} +4 -4
- package/dist/{test-MKAXFJOL.js → test-AGZOJLRZ.js} +7 -7
- package/dist/{tui-MWKAXE4K.js → tui-G5LLWCSV.js} +5 -5
- package/dist/{unbroadcast-KPUEFLZD.js → unbroadcast-5QNGAJR2.js} +4 -4
- package/dist/{validate-5GZ5YWNA.js → validate-IU52H2IC.js} +2 -2
- package/dist/{worker-RQ575EJL.js → worker-QZ5T6LJD.js} +8 -8
- package/docs/authoring.md +82 -0
- package/docs/browser-and-desktop.md +46 -0
- package/docs/commands.md +325 -0
- package/docs/compare.md +35 -0
- package/docs/compatibility.md +55 -0
- package/docs/embeddings.md +1 -1
- package/docs/getting-started.md +105 -0
- package/docs/git-workflow.md +60 -0
- package/docs/glossary.md +31 -0
- package/docs/hooks.md +264 -0
- package/docs/install.md +72 -0
- package/docs/library-skills.md +132 -0
- package/docs/mailbox.md +16 -5
- package/docs/project-configuration.md +51 -386
- package/docs/sessions.md +64 -0
- package/docs/skills.md +4 -45
- package/docs/terminal-harness.md +26 -21
- package/docs/terminal-workspace.md +4 -13
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +8 -6
- package/plugin.json +2 -2
- package/plugins/pmcp/.claude-plugin/plugin.json +2 -2
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/mod/sessions/types.ts +1 -1
- package/plugins/pmcp/plugin.json +2 -2
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +0 -4
- package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
- package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +19 -11
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +20 -28
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +4 -3
- package/schema/catalog-v1.json +36 -7
- package/schema/library.json +40 -8
- package/schema/marketplace-manifest.json +19 -5
- package/schema/plugin-manifest.json +6 -2
- package/schema/skill-frontmatter.json +33 -7
- package/schema/skill-metadata-core.json +26 -5
- package/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
- package/skills/package-skill-catalog/SKILL.md +0 -4
- package/skills/pmcp-browser/SKILL.md +27 -0
- package/skills/pmcp-desktop/SKILL.md +25 -0
- package/skills/pmcp-project-init/SKILL.md +19 -11
- package/skills/pmcp-sessions-and-git/SKILL.md +20 -28
- package/skills/skill-package-scaffold/SKILL.md +4 -3
- package/dist/chunk-E7OOHLQR.js +0 -7
- package/docs/manual-library-skills.md +0 -74
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import {
|
|
2
2
|
change
|
|
3
|
-
} from "./chunk-
|
|
4
|
-
import "./chunk-
|
|
5
|
-
import "./chunk-
|
|
3
|
+
} from "./chunk-LBXO4VPG.js";
|
|
4
|
+
import "./chunk-26WLNWDG.js";
|
|
5
|
+
import "./chunk-LTZH5E3G.js";
|
|
6
6
|
import "./chunk-C4NHQGHL.js";
|
|
7
7
|
import "./chunk-A4PKLESO.js";
|
|
8
8
|
import "./chunk-OEH47H6A.js";
|
|
@@ -15,4 +15,4 @@ var run = (context) => change(context, "sweep");
|
|
|
15
15
|
export {
|
|
16
16
|
run
|
|
17
17
|
};
|
|
18
|
-
//# sourceMappingURL=sweep-
|
|
18
|
+
//# sourceMappingURL=sweep-35LGQTTO.js.map
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import {
|
|
2
2
|
specFrom
|
|
3
|
-
} from "./chunk-
|
|
3
|
+
} from "./chunk-FENOGX3U.js";
|
|
4
4
|
import {
|
|
5
5
|
sourceFor
|
|
6
6
|
} from "./chunk-7TD53M7L.js";
|
|
@@ -12,7 +12,7 @@ import {
|
|
|
12
12
|
RUNTIME_IDS,
|
|
13
13
|
commandsOf,
|
|
14
14
|
customPolicy
|
|
15
|
-
} from "./chunk-
|
|
15
|
+
} from "./chunk-VRPMYPZU.js";
|
|
16
16
|
import {
|
|
17
17
|
DEFAULT_LOG_SETTINGS,
|
|
18
18
|
LEVEL_RANK
|
|
@@ -26,12 +26,12 @@ import "./chunk-OPYFEHKG.js";
|
|
|
26
26
|
import "./chunk-EATCUWGG.js";
|
|
27
27
|
import "./chunk-NRBQK6UX.js";
|
|
28
28
|
import "./chunk-3PW4FI7U.js";
|
|
29
|
-
import "./chunk-
|
|
29
|
+
import "./chunk-26WLNWDG.js";
|
|
30
30
|
import {
|
|
31
31
|
SESSION_ID,
|
|
32
32
|
createFilesStore,
|
|
33
33
|
writeJson
|
|
34
|
-
} from "./chunk-
|
|
34
|
+
} from "./chunk-LTZH5E3G.js";
|
|
35
35
|
import {
|
|
36
36
|
STATE_FILES,
|
|
37
37
|
asBroadcast,
|
|
@@ -47,7 +47,7 @@ import {
|
|
|
47
47
|
one
|
|
48
48
|
} from "./chunk-A4PKLESO.js";
|
|
49
49
|
import "./chunk-V4NPDK6X.js";
|
|
50
|
-
import "./chunk-
|
|
50
|
+
import "./chunk-7HFIGCSL.js";
|
|
51
51
|
import {
|
|
52
52
|
expandPath
|
|
53
53
|
} from "./chunk-OEH47H6A.js";
|
|
@@ -55,7 +55,7 @@ import {
|
|
|
55
55
|
checkoutOf,
|
|
56
56
|
worktreesOf
|
|
57
57
|
} from "./chunk-IJBSOWHK.js";
|
|
58
|
-
import "./chunk-
|
|
58
|
+
import "./chunk-65KAQSJP.js";
|
|
59
59
|
import "./chunk-QPL7E2HW.js";
|
|
60
60
|
import "./chunk-PMJG2CXF.js";
|
|
61
61
|
|
|
@@ -558,4 +558,4 @@ async function run(context) {
|
|
|
558
558
|
export {
|
|
559
559
|
run
|
|
560
560
|
};
|
|
561
|
-
//# sourceMappingURL=test-
|
|
561
|
+
//# sourceMappingURL=test-AGZOJLRZ.js.map
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import {
|
|
2
2
|
unsupportedHost,
|
|
3
3
|
unsupportedReceipt
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-F5XMGOOX.js";
|
|
5
5
|
import {
|
|
6
6
|
tuiSpec
|
|
7
7
|
} from "./chunk-3Y3HDMHA.js";
|
|
@@ -112,10 +112,10 @@ var tuiCommand = {
|
|
|
112
112
|
try {
|
|
113
113
|
let receipt;
|
|
114
114
|
if (invocation.action === "doctor") {
|
|
115
|
-
const { inspectTerminalHost } = await import("./diagnostics-
|
|
115
|
+
const { inspectTerminalHost } = await import("./diagnostics-XKXVVQWH.js");
|
|
116
116
|
receipt = inspectTerminalHost();
|
|
117
117
|
} else if (invocation.action === "start-worker") {
|
|
118
|
-
const { startWorkspaceWorker } = await import("./worker-
|
|
118
|
+
const { startWorkspaceWorker } = await import("./worker-QZ5T6LJD.js");
|
|
119
119
|
receipt = await startWorkspaceWorker(
|
|
120
120
|
{ config: invocation.startup?.config, cwd: context.cwd },
|
|
121
121
|
invocation.startup.runtime,
|
|
@@ -128,7 +128,7 @@ var tuiCommand = {
|
|
|
128
128
|
cwd: context.cwd
|
|
129
129
|
});
|
|
130
130
|
} else {
|
|
131
|
-
const { launchStartup, planStartup } = await import("./entry-
|
|
131
|
+
const { launchStartup, planStartup } = await import("./entry-X6CSYQRQ.js");
|
|
132
132
|
const request = { ...invocation.startup, cwd: context.cwd };
|
|
133
133
|
receipt = invocation.action === "plan" ? planStartup(request) : await launchStartup(
|
|
134
134
|
request,
|
|
@@ -150,4 +150,4 @@ var tuiCommand = {
|
|
|
150
150
|
export {
|
|
151
151
|
tuiCommand
|
|
152
152
|
};
|
|
153
|
-
//# sourceMappingURL=tui-
|
|
153
|
+
//# sourceMappingURL=tui-G5LLWCSV.js.map
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import {
|
|
2
2
|
change
|
|
3
|
-
} from "./chunk-
|
|
4
|
-
import "./chunk-
|
|
5
|
-
import "./chunk-
|
|
3
|
+
} from "./chunk-LBXO4VPG.js";
|
|
4
|
+
import "./chunk-26WLNWDG.js";
|
|
5
|
+
import "./chunk-LTZH5E3G.js";
|
|
6
6
|
import "./chunk-C4NHQGHL.js";
|
|
7
7
|
import "./chunk-A4PKLESO.js";
|
|
8
8
|
import "./chunk-OEH47H6A.js";
|
|
@@ -15,4 +15,4 @@ var run = (context) => change(context, "unbroadcast");
|
|
|
15
15
|
export {
|
|
16
16
|
run
|
|
17
17
|
};
|
|
18
|
-
//# sourceMappingURL=unbroadcast-
|
|
18
|
+
//# sourceMappingURL=unbroadcast-5QNGAJR2.js.map
|
|
@@ -7,7 +7,7 @@ import {
|
|
|
7
7
|
import {
|
|
8
8
|
validateCatalog,
|
|
9
9
|
validateSkillDir
|
|
10
|
-
} from "./chunk-
|
|
10
|
+
} from "./chunk-AJ4VXM2U.js";
|
|
11
11
|
import "./chunk-73AKO4UL.js";
|
|
12
12
|
import {
|
|
13
13
|
validateSpec
|
|
@@ -43,4 +43,4 @@ var validateCommand = {
|
|
|
43
43
|
export {
|
|
44
44
|
validateCommand
|
|
45
45
|
};
|
|
46
|
-
//# sourceMappingURL=validate-
|
|
46
|
+
//# sourceMappingURL=validate-IU52H2IC.js.map
|
|
@@ -1,24 +1,24 @@
|
|
|
1
1
|
import {
|
|
2
2
|
invoke
|
|
3
|
-
} from "./chunk-
|
|
3
|
+
} from "./chunk-2FIV63WC.js";
|
|
4
4
|
import {
|
|
5
5
|
readStartup,
|
|
6
6
|
startupFile,
|
|
7
7
|
startupSettings
|
|
8
8
|
} from "./chunk-PAX3QXX2.js";
|
|
9
9
|
import "./chunk-DZ2MRTYT.js";
|
|
10
|
-
import "./chunk-
|
|
11
|
-
import "./chunk-
|
|
10
|
+
import "./chunk-3IDXEV5E.js";
|
|
11
|
+
import "./chunk-LW4TG7EL.js";
|
|
12
12
|
import {
|
|
13
13
|
locateExecutable
|
|
14
14
|
} from "./chunk-R2GPCZUX.js";
|
|
15
|
-
import "./chunk-
|
|
15
|
+
import "./chunk-7UCZAN4J.js";
|
|
16
16
|
import "./chunk-34DECPVC.js";
|
|
17
|
-
import "./chunk-
|
|
18
|
-
import "./chunk-
|
|
17
|
+
import "./chunk-DMZHQZ7P.js";
|
|
18
|
+
import "./chunk-7HFIGCSL.js";
|
|
19
19
|
import "./chunk-OEH47H6A.js";
|
|
20
20
|
import "./chunk-IJBSOWHK.js";
|
|
21
|
-
import "./chunk-
|
|
21
|
+
import "./chunk-65KAQSJP.js";
|
|
22
22
|
import "./chunk-QPL7E2HW.js";
|
|
23
23
|
import "./chunk-PMJG2CXF.js";
|
|
24
24
|
import {
|
|
@@ -77,4 +77,4 @@ async function startWorkspaceWorker(request, runtime, memoryMb) {
|
|
|
77
77
|
export {
|
|
78
78
|
startWorkspaceWorker
|
|
79
79
|
};
|
|
80
|
-
//# sourceMappingURL=worker-
|
|
80
|
+
//# sourceMappingURL=worker-QZ5T6LJD.js.map
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Shipping a skill in your package
|
|
2
|
+
|
|
3
|
+
[Back to the overview](../README.md)
|
|
4
|
+
|
|
5
|
+
Three things have to be true: the file is somewhere the walk reaches, its frontmatter carries a `description`, and the tarball actually contains it.
|
|
6
|
+
|
|
7
|
+
## Where the file goes
|
|
8
|
+
|
|
9
|
+
Any of these, and the walk does not care which. They are the conventions different agents settled on, and one directory read sees them all:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
<package>/skills/<slug>/SKILL.md
|
|
13
|
+
<package>/.agent/skills/<slug>/SKILL.md
|
|
14
|
+
<package>/.claude/skills/<slug>/SKILL.md
|
|
15
|
+
<package>/.gemini/skills/<slug>/SKILL.md
|
|
16
|
+
<package>/.codex/skills/<slug>/SKILL.md
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The path is not what makes it a skill; the file is. Each installed package is walked to a depth of three, and any `SKILL.md` found is a skill, so a convention nobody has invented yet works too.
|
|
20
|
+
|
|
21
|
+
### Where it must not go
|
|
22
|
+
|
|
23
|
+
The walk skips directories that cannot hold a package's own skill and are expensive or misleading to enter. A `SKILL.md` under any of these is invisible:
|
|
24
|
+
|
|
25
|
+
| Kind | Directories |
|
|
26
|
+
| -------------------------- | ------------------------------------------------------------------------------------------- |
|
|
27
|
+
| build output | `dist`, `build`, `out`, `lib`, `es`, `esm`, `cjs`, `umd` |
|
|
28
|
+
| sources and types | `src`, `types`, `typings`, `bin` |
|
|
29
|
+
| test corpora | `test`, `tests`, `__tests__`, `fixtures`, `__fixtures__`, `example`, `examples`, `coverage` |
|
|
30
|
+
| nested installs and caches | `node_modules`, `.git`, `.turbo`, `.cache` |
|
|
31
|
+
|
|
32
|
+
The common mistake is authoring the skill in `src/` and letting the build copy it to `dist/`. Both ends of that are skipped. Keep the file at a path that ships as written.
|
|
33
|
+
|
|
34
|
+
## The frontmatter
|
|
35
|
+
|
|
36
|
+
```markdown
|
|
37
|
+
---
|
|
38
|
+
name: release-runbook
|
|
39
|
+
description: A deploy went out but the container still runs the old bundle, and rebuilding does not change it.
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
# Releasing
|
|
43
|
+
|
|
44
|
+
…
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Two fields are read. `name` becomes the slug, and the skill is addressed as `<package>/<slug>`; leave it out and the directory holding the file names it, or the package itself does when the file sits at the package root.
|
|
48
|
+
|
|
49
|
+
`description` is the only text that [`skill_find`](getting-started.md) ranks. A skill without one is skipped rather than listed: ranking could never surface it, so listing it would spend a session's tokens on an entry that cannot answer.
|
|
50
|
+
|
|
51
|
+
The reader is not a YAML parser. It takes flat scalars on their own line, strips one pair of surrounding quotes, and ignores anything nested. That is the honest limit rather than a partial YAML, and it means a description folded over several lines is not read as you intended.
|
|
52
|
+
|
|
53
|
+
## Write the description as a symptom
|
|
54
|
+
|
|
55
|
+
A reader arrives with a problem, not with your vocabulary. They will not type your package's name, because not knowing it is why they are asking. Descriptions that name the symptom are the ones a sentence can reach.
|
|
56
|
+
|
|
57
|
+
| Instead of | Write |
|
|
58
|
+
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
59
|
+
| `Utilities for distributed locks, leases and fencing tokens.` | `A job ran twice because two workers took the same lock, or a lock outlived the worker holding it.` |
|
|
60
|
+
| `Deployment helpers and image build configuration.` | `A deploy went out but the container still runs the old bundle, and rebuilding does not change it.` |
|
|
61
|
+
|
|
62
|
+
Both halves of the lexical score reward this. It compares the words of the question against the words of the description, and a feature list shares its words with every other feature list in the catalog.
|
|
63
|
+
|
|
64
|
+
Name the failure, the surprise, and the thing the reader already tried. One or two sentences. It is read by whoever is choosing between five candidates, so it is a filter, not a summary of the body.
|
|
65
|
+
|
|
66
|
+
## Ship the file
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"files": ["dist", "skills", "README.md"]
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A `SKILL.md` outside the manifest's `files` array is not in the tarball, and therefore not in anyone's `node_modules`. This fails quietly: your repository has the skill, your tests find it, and no consumer ever sees it.
|
|
75
|
+
|
|
76
|
+
Check by installing your own tarball into an empty project and running `npx -y @modootoday/pmcp list` there. If the name is not in that output, no agent will find it either.
|
|
77
|
+
|
|
78
|
+
## The body
|
|
79
|
+
|
|
80
|
+
Everything after the closing `---` is the body, and `skill_call` returns it whole. It is read on its own, by someone who has seen only the description, so it should not depend on the rest of your documentation site to make sense.
|
|
81
|
+
|
|
82
|
+
**Two skills can share a name only once.** The catalog is keyed by `<package>/<slug>` and the first root wins, so a nested copy of your package is ignored in favour of the one the project actually resolved.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Browser and desktop for agents
|
|
2
|
+
|
|
3
|
+
[Back to the overview](../README.md)
|
|
4
|
+
|
|
5
|
+
pmcp-browser and pmcp-desktop give agents a browser and a desktop on a Linux server, as MCP
|
|
6
|
+
servers. What they may reach is set in `[host]` of the [pmcp.toml reference](project-configuration.md#sessions-pmcp-pty-hosts).
|
|
7
|
+
|
|
8
|
+
Claude Code and Codex offer browser and computer use only through their
|
|
9
|
+
desktop apps, not on a Linux server. Two MCP servers built from this
|
|
10
|
+
repository cover that ground for every runtime pmcp projects to:
|
|
11
|
+
|
|
12
|
+
- `pmcp-browser` (`crates/pmcp-plugin-browser-use`): an isolated Chromium,
|
|
13
|
+
headless, with a fresh profile per launch. It reaches public http(s) sites
|
|
14
|
+
only: every request goes through its own proxy, which refuses loopback,
|
|
15
|
+
private, link-local, metadata and CGNAT addresses and every port but 80 and 443. Local schemes such as `file:` are blocked in the page.
|
|
16
|
+
- `pmcp-desktop` (`crates/pmcp-plugin-computer-use`): an Xvfb desktop driven
|
|
17
|
+
through screenshots and XTEST input, for any X11 app.
|
|
18
|
+
|
|
19
|
+
Each runs in its own memory-capped systemd scope (2G and 512M by default),
|
|
20
|
+
and `pmcp-browser` allows two at a time on the host. Both have `doctor`
|
|
21
|
+
(read-only, with the exact fix) and `setup --plan`; root steps are printed,
|
|
22
|
+
never run. Both ship in the Linux platform package npm installs with PMCP
|
|
23
|
+
(glibc 2.35 or later), which does not put them on PATH. Declare them like
|
|
24
|
+
any MCP server with the bare name as `command`; `pmcp project` resolves it to
|
|
25
|
+
the installed binary, so pmcp.toml names no host path:
|
|
26
|
+
|
|
27
|
+
```toml
|
|
28
|
+
[mcp.pmcp-browser]
|
|
29
|
+
command = "pmcp-browser"
|
|
30
|
+
args = ["serve", "--approved", "<the directory pmcp harness host status reports>"]
|
|
31
|
+
|
|
32
|
+
[mcp.pmcp-desktop]
|
|
33
|
+
command = "pmcp-desktop"
|
|
34
|
+
args = ["serve", "--geometry", "1440x900x24"]
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`pmcp doctor` reports where each resolved, or why not (no platform
|
|
38
|
+
package for this host, as on macOS); an unresolved name runs from PATH. An
|
|
39
|
+
absolute `command`, such as your own build, is kept as written.
|
|
40
|
+
|
|
41
|
+
The names avoid Claude Code's built-in `computer-use`. `--approved` is
|
|
42
|
+
optional: without it the browser is public-only and the desktop launches
|
|
43
|
+
nothing. `[host.browser] allow_private` and `[[host.desktop.launch]]` come
|
|
44
|
+
into force only through `pmcp harness host approve`. Running the browser
|
|
45
|
+
headed on the desktop's display also needs the managed Chromium policy that
|
|
46
|
+
`pmcp-browser setup --plan` prints for you to install.
|
package/docs/commands.md
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
# Command reference
|
|
2
|
+
|
|
3
|
+
[Back to the overview](../README.md)
|
|
4
|
+
|
|
5
|
+
Every pmcp command with its flags, behaviour and exit codes. `pmcp <command> --help` prints
|
|
6
|
+
the same usage from the command itself.
|
|
7
|
+
|
|
8
|
+
## The invocation a host uses
|
|
9
|
+
|
|
10
|
+
- `pmcp` opens a workspace on a supported terminal; a piped launch runs the MCP server on
|
|
11
|
+
stdio.
|
|
12
|
+
- `pmcp --root ./node_modules`: a leading option with no command is still a server, because
|
|
13
|
+
hosts pass options without one.
|
|
14
|
+
|
|
15
|
+
An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option, takes that path.
|
|
16
|
+
|
|
17
|
+
## status
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pmcp status [--config <file>] [--json]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, and logged errors from the last hour. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 2 when projection or worktree ahead/behind drift exists. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stderr; JSON retains the full details.
|
|
24
|
+
|
|
25
|
+
## init
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
pmcp init [--preset solo|multi-session] [--force]
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Create `pmcp.toml` in the current directory. Solo enables Claude/Codex targets, the stage-all and heredoc guards, and detected git settings. Multi-session adds registry, pause and broadcast; in git it also enables worktree commands and shared-checkout warnings. Git remote and mainline come from the same detection used by the git workflow. No gate, installation command, MCP credential or provider is invented. Both presets are parsed and compiled before writing. Existing files require `--force`. Output explains each choice; projection remains a separate explicit operation. Exit 0 on creation, 2 for a bad preset or refused overwrite, 1 for a write failure.
|
|
32
|
+
|
|
33
|
+
## hooks
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pmcp hooks list [--runtime claude|codex] [--config <file>] [--json]
|
|
37
|
+
pmcp hooks test --runtime claude|codex --event before_tool --command "git add -A" [--json]
|
|
38
|
+
pmcp hooks test --runtime claude --event before_tool --path fixture.txt --session-state state.json
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
List compiled policies per runtime and neutral event, including mode and source table. Test constructs a synthetic payload in that runtime's recorded shape, normalizes it, runs policy selection and composition, lowers unsupported asks, and renders the native response. The event accepts a neutral name or a supported native name. Choose at most one of `--command`, `--path` and `--tool`; these selectors require a tool event. Tool accepts a native name or shell, edit, read or other, subject to that runtime's tool vocabulary. No native runtime or model call is needed.
|
|
42
|
+
|
|
43
|
+
Session state is isolated in a temporary directory, then removed. Commands and patches are classified, never executed. External custom guards, validators, Stop projection subprocesses and worktree synchronization are explicitly marked skipped. Their simulated context reports this limitation; the command does not claim a full live result. Exit 0 means the simulation completed, even when the rendered decision denies; invalid input exits 2. Per-policy timings and reasons precede the rendered output in human mode.
|
|
44
|
+
|
|
45
|
+
`--session-state` accepts a JSON object with optional `records` (session records with valid 8–64 character IDs), `pause` (by, reason, since), `leases` (name to pid, subject, since, optional cwd), and `broadcast` (id, by, text, since). Pause and broadcast may be null. Existing liveness and unseen-broadcast rules apply. This file and the real session store remain unchanged.
|
|
46
|
+
|
|
47
|
+
## Read command JSON schemas
|
|
48
|
+
|
|
49
|
+
These opt-in snapshots write one JSON object and a newline to stdout, with `version: 1`. No color or human summary is mixed into stdout. Errors remain on stderr. Without the flag, existing human output is retained, including MCP status's original unversioned object and logs' JSONL stream. Schemas are named in [schemas.json](https://pmcp.build/commands/schemas.json); each entry under `schemas` uses the shared root `$defs`. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
|
|
50
|
+
|
|
51
|
+
| Command | Schema | Fields after version |
|
|
52
|
+
| -------------------------- | ----------------- | --------------------------------------------------------------------- |
|
|
53
|
+
| `status --json` | status | config, drift, features, projection, sessions, worktrees, mcp, errors |
|
|
54
|
+
| `hooks list --json` | hooks-list | policies: runtime, event, policy, mode, source |
|
|
55
|
+
| `hooks test --json` | hooks-test | runtime, event, payload, decision, policies, rendered |
|
|
56
|
+
| `sessions status --json` | sessions-status | live, pause, leases, broadcasts with unseenBy session IDs |
|
|
57
|
+
| `logs --json` | logs | records; filtered snapshot, incompatible with --follow and --pretty |
|
|
58
|
+
| `git worktree list --json` | git-worktree-list | worktrees: path, main, optional alias, branch, behind and ahead |
|
|
59
|
+
| `mcp status <name> --json` | mcp-status | name, present, expiresAt (UTC string or null), scopes |
|
|
60
|
+
|
|
61
|
+
Feature rows have feature, enabled and source. Projection has drift, outputs and problems. Session snapshots include only live records; broadcasts include the IDs that have not yet seen each entry. Worktree counts are omitted when the upstream cannot be compared; absence does not assert equality. Status auth rows add a redacted error when credentials are unavailable or invalid. Errors are JSONL records with valid timestamps within the last hour, excluding future rows. Hooks test observations have policy, mode, decision, durationMs, skipped, source, verdict and reason; rendered has stdout and exitCode. The final decision includes runtime lowering, while each policy row retains its configured verdict. Mutating sessions, git and MCP verbs reject `--json`.
|
|
62
|
+
|
|
63
|
+
## serve
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
pmcp serve [--config <file>] [--root <dir>] [--scope <prefix>] [embedding options]
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Reachable by name so it appears in help. It writes nothing to standard output: from the moment it starts, standard output is the protocol, and a diagnostic printed there corrupts the stream.
|
|
70
|
+
|
|
71
|
+
## list
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
pmcp list [--root <dir>] [--scope <prefix>] [--json]
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The skills discovered in `node_modules`, as two aligned columns, or as JSON for a script. This is the command that answers "would the server see anything from here".
|
|
78
|
+
|
|
79
|
+
## marketplace
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
pmcp marketplace list --json
|
|
83
|
+
pmcp marketplace export typescript-5 --runtime agy --output ./typescript-plugin
|
|
84
|
+
agy plugin install ./typescript-plugin
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
List the bundled free plugins or export one selected native package. Choose `claude`, `codex`, `gemini`, `grok` or `agy`. An export preserves existing destinations and does not edit runtime configuration or bypass native installation consent. CLI discovery includes the built-in catalog unless `--no-builtin` or `[catalog] builtin = false` is configured.
|
|
88
|
+
|
|
89
|
+
An empty catalog is a finding rather than a success. It exits **1** and names the roots it walked, because a project that installed this and sees nothing has a misconfiguration worth an exit code.
|
|
90
|
+
|
|
91
|
+
## index
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
pmcp index [--config <file>] [embedding options] [--local-only] [--dry-run] [--force] [--json]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Encodes each description once so ranking can be semantic, and stores the vectors beside the tree they describe, so two projects never share one index. Only what changed is re-encoded; an unchanged description produces the same vector at the same cost as the first time.
|
|
98
|
+
|
|
99
|
+
Vectors written by one model are never scored against another, so `--model` is part of the key rather than a preference. Without the optional peer installed it exits **3** and tells you ranking stays lexical, which is the default and not a failure.
|
|
100
|
+
|
|
101
|
+
A partial index is reported rather than called success: it exits **1** and says how many of the catalog it covered, because ranking needs a vector for every entry and falls back to lexical without one.
|
|
102
|
+
|
|
103
|
+
## models
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
pmcp models [--json]
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Lists the default E5 encoder and optional EmbeddingGemma presets with their dimensions and asset revisions. It does not load an encoder or download weights. Configure `[embedding]` in `pmcp.toml` or override individual settings on the CLI.
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
pmcp index --model embeddinggemma-2 --dtype q4 --dimensions 256
|
|
113
|
+
pmcp serve --model embeddinggemma-2 --dtype q4 --dimensions 256
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Shared embedding options are `--model`, `--dtype`, `--dimensions`, `--model-revision`, `--model-path`, `--model-cache`, `--query-prefix`, `--passage-prefix`, and `--pooling`. They override the corresponding configuration fields. Use `--no-config` for an independent CLI selection. Model identity includes revision, dtype, dimensions, prefixes, pooling, and projection, so incompatible vectors and query caches stay separate.
|
|
117
|
+
|
|
118
|
+
`index --local-only` refuses downloads, `--dry-run` previews work without loading a model or writing vectors, and `--force` rebuilds only the selected encoder's index. `serve` never downloads weights: it uses a complete matching local index or reports a lexical fallback. Restart after switching encoder settings.
|
|
119
|
+
|
|
120
|
+
## mailbox
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
pmcp mailbox init --config ./pmcp.toml
|
|
124
|
+
pmcp mailbox actor --config ./pmcp.toml --actor reviewer --actor-file /private/reviewer.actor.json
|
|
125
|
+
pmcp serve --config ./pmcp.toml --mailbox-actor-file /private/reviewer.actor.json --mailbox-runtime codex-cli
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Mailbox is disabled by default. Initialization creates a project UUID and preserves existing configuration. A launcher-bound actor enables `mailbox_send`, `mailbox_inbox`, `mailbox_read`, `mailbox_ack`, and `mailbox_sessions`. Reading records a receipt; acknowledgement requires reading first. Acknowledgement does not assert task completion.
|
|
129
|
+
|
|
130
|
+
Credentials and attachment files contain secrets and must stay outside source control. State defaults to the user's XDG state directory. Administrative `rotate`, `export`, `backup`, and `restore` operations require `--operator`. Use `pmcp mailbox --help` for inputs. The mailbox exchanges peer data; the host owns authentication, automatic runtime delivery, and enterprise policy.
|
|
131
|
+
|
|
132
|
+
## project
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
pmcp project
|
|
136
|
+
pmcp project --check
|
|
137
|
+
pmcp project import-mcp --source codex:/path/to/config.toml
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes, and MCP import previews changes by default; `--write` applies them. [Configuration and guard examples](project-configuration.md).
|
|
141
|
+
|
|
142
|
+
Configuration files and the ownership lock are replaced atomically one file at a time. If projection is interrupted, inspect with `pmcp project --check`, then run `pmcp project` explicitly to repair drift. Projection does not start a runtime or replay terminal input. The complete set of files is not a single transaction.
|
|
143
|
+
|
|
144
|
+
## sessions
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
pmcp sessions status
|
|
148
|
+
pmcp sessions pause "release freeze" [--by <name>]
|
|
149
|
+
pmcp sessions resume
|
|
150
|
+
pmcp sessions broadcast "main moved; rebase before delivering" [--by <name>]
|
|
151
|
+
pmcp sessions unbroadcast
|
|
152
|
+
pmcp sessions sweep
|
|
153
|
+
pmcp sessions send --to <selector>... [--subject <s>] [--wake] <body>
|
|
154
|
+
pmcp sessions inbox
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Coordinate the live agent sessions of this repository and its worktrees, through the state the hooks keep for [`[sessions]`](project-configuration.md#sessions). `status` (the default verb) prints each live session, the pause, current broadcasts, held leases and undelivered edits in a shared checkout to standard output, or `no live sessions`. `pause` refuses edits and mutating commands in every other session until `resume`; `broadcast` delivers its text once to each session as context, and `unbroadcast` withdraws it. `--by` names the sender, whose own session is exempt; it defaults to `operator`. `sweep` removes records whose process is gone. `send` addresses `all`, `session:<id>`, `alias:<name>`, `role:<name>` or `worktree:<path>` through `[sessions.mailbox]`; `inbox` lists your messages. [Run several agents](sessions.md) walks through them. Exit 0, or 2 for an unknown verb, missing text or no `pmcp.toml`.
|
|
158
|
+
|
|
159
|
+
## logs
|
|
160
|
+
|
|
161
|
+
```sh
|
|
162
|
+
pmcp logs --since 10m --level warn --pretty
|
|
163
|
+
pmcp logs --session 4f92 --component hooks
|
|
164
|
+
pmcp logs --trace 7cef825e8fbd8c3f
|
|
165
|
+
pmcp logs --follow
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Read this project's JSONL logs from the state directory, or the file `[hooks] error_log` names. Filters combine: `--session` takes an id prefix, `--trace` one hook call, `--component` a component and those below it, `--level` that level and more severe, `--since` a duration (`10m`, `2h`, `3d`) or an ISO time. Records print as JSON lines unless `--pretty`; `--follow` keeps printing until interrupted. Secret values, prompt text and environment values are redacted at write time, per [`[logging]`](project-configuration.md#logging). Exit 0, or 2 for an unusable filter or no `pmcp.toml`.
|
|
169
|
+
|
|
170
|
+
## git
|
|
171
|
+
|
|
172
|
+
```sh
|
|
173
|
+
pmcp git worktree create review [--base <ref>]
|
|
174
|
+
pmcp git worktree list
|
|
175
|
+
pmcp git worktree sync
|
|
176
|
+
pmcp git deliver [<commit>...] [--during-pause]
|
|
177
|
+
pmcp git sync
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it the command exits 1 and names the missing table.
|
|
181
|
+
|
|
182
|
+
- `worktree create <alias>` makes a linked worktree under `[git.worktrees] root` on a new branch from the upstream (or `--base`), links the configured files from the main checkout, runs `bootstrap`, and prints the path.
|
|
183
|
+
- `worktree list` prints alias, branch, behind/ahead and path for the main checkout and each linked worktree.
|
|
184
|
+
- `worktree sync` moves the current worktree onto the mainline when that loses nothing; exit 1 when it is held back.
|
|
185
|
+
- `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` or `during_pause = "allow"`. Exit 0 delivered or nothing to deliver, 1 refused, gate failed or attempts exhausted, 2 fetch failed.
|
|
186
|
+
- `sync` moves the main checkout to the mainline, installs when a listed file changed, and follows clean submodule pins. Exit 0 moved or already equal, 1 when local work would be lost, 2 when blocked (undelivered edits) or the fetch failed.
|
|
187
|
+
|
|
188
|
+
## completion
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
pmcp completion bash > ~/.local/share/bash-completion/completions/pmcp
|
|
192
|
+
pmcp completion zsh > "${fpath[1]}/_pmcp"
|
|
193
|
+
pmcp completion fish > ~/.config/fish/completions/pmcp.fish
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Print a completion script for commands and global options to standard output. Exit 0, or 2 for another shell.
|
|
197
|
+
|
|
198
|
+
## mcp
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
pmcp mcp login remote [--no-wait | --code <callback-or-code>] [--port <port>] [--client-id <id>] [--bearer-env <name>]
|
|
202
|
+
pmcp mcp status remote
|
|
203
|
+
pmcp mcp logout remote
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Manage a shared remote MCP session for a server declared with `auth = "pmcp"`. Login prints an authorization URL and accepts a loopback callback or pasted code. Status reports presence, UTC expiry and scopes; tokens are never printed. Bearer credentials can be loaded with `--bearer-env`. Native authentication remains the default. [Shared authentication configuration](project-configuration.md#shared-remote-mcp-authentication).
|
|
207
|
+
|
|
208
|
+
## doctor
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
pmcp doctor
|
|
212
|
+
pmcp doctor --memory
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Inspect native configuration and prerequisites. The optional memory report shows enabled state and paths; it does not read memory contents or synchronize personal memory. [Doctor scope and runtime compatibility](project-configuration.md).
|
|
216
|
+
|
|
217
|
+
## validate
|
|
218
|
+
|
|
219
|
+
```sh
|
|
220
|
+
pmcp validate
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Validate discovered skill documents and their contracts without starting a native runtime. [Skills reference](skills.md).
|
|
224
|
+
|
|
225
|
+
## harness
|
|
226
|
+
|
|
227
|
+
```sh
|
|
228
|
+
pmcp harness doctor inspect
|
|
229
|
+
pmcp harness group inspect --group-file "$GROUP_FILE"
|
|
230
|
+
pmcp harness recovery inspect --group-file "$GROUP_FILE"
|
|
231
|
+
pmcp harness host approve | status | up | down | unit
|
|
232
|
+
pmcp harness mcp
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Optional local supervision of owned native main and worker sessions on pmcp-pty. Groups run on Linux (glibc 2.35 or later, with a working user systemd manager) or macOS, with Node.js 22. Start, input, stop and recovery actions are explicit CLI operations. Provider OAuth, trust and approvals remain native; MCP tools cannot invoke this execution path. [Group creation, control and recovery](terminal-harness.md).
|
|
236
|
+
|
|
237
|
+
`harness host` runs the long-running sessions listed in `[host]` of `pmcp.toml`: `approve` records your approval of the projected policy, `status` reports it, `up` starts pmcp-pty and the approved sessions, `down` stops them and `unit` prints a systemd user unit. `up` and `unit` need Linux. `harness mcp` is a stdio MCP server for one pmcp-pty socket (`PMCP_PTY_SOCKET`); its write tools exist only when the approved policy sets `mcp_write`. [The [host] table](project-configuration.md#sessions-pmcp-pty-hosts).
|
|
238
|
+
|
|
239
|
+
## tui
|
|
240
|
+
|
|
241
|
+
```sh
|
|
242
|
+
pmcp
|
|
243
|
+
pmcp tui plan
|
|
244
|
+
pmcp tui --runtime codex-cli
|
|
245
|
+
pmcp tui doctor
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
Open a native main terminal, worker dock and coordination panel with defaults or an optional `[tui]` table in `pmcp.toml`. The first launch confirms the selected runtime; later launches reconnect to this project's owned workspace. The workspace starts read only; taking control and stopping a runtime require explicit actions. Opening requires an interactive terminal and the same host as the harness. [Keys, mailbox observation and cleanup](terminal-workspace.md).
|
|
249
|
+
|
|
250
|
+
## The written skills
|
|
251
|
+
|
|
252
|
+
Local discovery, configuration and terminal supervision need no PMCP account. Configuration and supervision can change local state; native runtimes retain their own provider login requirements. [Package-specific skills](https://pmcp.build/skills/) are free to read, download and install without PMCP login. Each skill page links the original SKILL.md and a content-only archive that your package manager can install directly. The service commands below also support hosted catalogs with their own access policies.
|
|
253
|
+
|
|
254
|
+
All four take `--project <dir>`, `--api <origin>`, `--json`, and `--catalog <file>`, which reads a saved response so the command runs with no network at all.
|
|
255
|
+
|
|
256
|
+
## available
|
|
257
|
+
|
|
258
|
+
```sh
|
|
259
|
+
pmcp available [--project <dir>] [--catalog <file>] [--json]
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Which written skills match the dependencies this project already has. It reads your `package.json` to decide what matches and does not upload it. No account needed.
|
|
263
|
+
|
|
264
|
+
## preview
|
|
265
|
+
|
|
266
|
+
```sh
|
|
267
|
+
pmcp preview <skill-package> [--json]
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
A skill's contents and one complete example. The sample is taken from the skill's own bytes rather than described, so it cannot drift from what you would receive. No account needed.
|
|
271
|
+
|
|
272
|
+
## login · logout · whoami
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
pmcp login [--issuer <url>]
|
|
276
|
+
pmcp logout
|
|
277
|
+
pmcp whoami [--json]
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
`login` signs this machine in without a browser: it prints a code and a URL to open anywhere. The credential is kept outside the project, so it cannot be committed or copied into an image. `whoami` answers on stdout, so a script can read it. This optional service login is not needed to use the free package skills on pmcp.build.
|
|
281
|
+
|
|
282
|
+
[skills.modoo.today](https://skills.modoo.today) is a separate skill catalog service built on pmcp, with its own accounts and access policies; `pmcp login` and `--provider hosted` reach it. pmcp itself needs no account there.
|
|
283
|
+
|
|
284
|
+
## install · sync
|
|
285
|
+
|
|
286
|
+
```sh
|
|
287
|
+
pmcp install <skill-package>... | --all [--dry-run | --yes]
|
|
288
|
+
pmcp sync [--project <dir>] [--dry-run | --yes]
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`install` adds skill packages as dev dependencies with your own package manager, and what gets installed is checked against the digest the catalogue published — not its name and version, which any registry can claim. `sync` updates the ones already declared and removes nothing else. pmcp uses the free bundled public catalog by default and verifies immutable archives and installed resources without login. Explicit `--provider hosted` or `--api` selects a separate service's credentialed distribution, such as skills.modoo.today (see [login](#login--logout--whoami)).
|
|
292
|
+
|
|
293
|
+
Both show the project and lockfile changes and stop: `--yes` approves them, `--dry-run` prints the plan and changes nothing.
|
|
294
|
+
|
|
295
|
+
## Options
|
|
296
|
+
|
|
297
|
+
| Option | Where | Effect |
|
|
298
|
+
| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------- |
|
|
299
|
+
| `--root <dir>` | `serve`, `list`, `index` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
|
|
300
|
+
| `--scope <prefix>` | `serve`, `list`, `index` | only packages whose names start with this; repeatable, matched with a plain prefix test |
|
|
301
|
+
| `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
|
|
302
|
+
| `--json` | `list`, `index`, `models` | emit JSON on standard output rather than a table or a summary |
|
|
303
|
+
| `--help`, `-h` | anywhere | the help for that command, generated from the command itself |
|
|
304
|
+
| `--version` | on its own | the version, on standard output |
|
|
305
|
+
|
|
306
|
+
Options are parsed against the command's own list, so an unknown flag is an error rather than a silently ignored typo. Giving a non-repeatable option twice, or leaving off a value it needs, is the same error.
|
|
307
|
+
|
|
308
|
+
## Exit codes
|
|
309
|
+
|
|
310
|
+
| Code | Means | For example |
|
|
311
|
+
| ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
312
|
+
| `0` | it did what you asked | skills listed, or the whole catalog indexed |
|
|
313
|
+
| `1` | it ran and found a problem | no skills under those roots, a partial index, no SQLite in this runtime to store vectors in, a refused or failed `git deliver` |
|
|
314
|
+
| `2` | the arguments were unusable, or a check found drift | an unknown command, an unknown option, a missing value; `project --check` drift, stale or undeclared outputs; a `git` fetch that failed or a sync blocked by undelivered edits |
|
|
315
|
+
| `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
|
|
316
|
+
|
|
317
|
+
The distinction between 1 and 3 is worth wiring into a script: 1 says the project is not what you expected, and 3 says the machine is missing something optional and the server still works without it.
|
|
318
|
+
|
|
319
|
+
**Data on stdout, everything else on stderr.** The JSON from `--json` and the string from `--version` go to standard output so they can be piped. Tables, help and messages go to standard error, which is what keeps a pipeline's input clean.
|
|
320
|
+
|
|
321
|
+
## Runtime
|
|
322
|
+
|
|
323
|
+
- Node 22 or later, or Bun 1.3 or later.
|
|
324
|
+
- Runtime dependencies: `@modelcontextprotocol/server`, `zod`, `semver`, `smol-toml` and `yaml`. See [dependency licence notices](https://pmcp.build/licence/).
|
|
325
|
+
- Vector storage uses whichever SQLite the running binary already has. Neither is a dependency; without one, the server still runs and ranking falls back.
|