@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.
Files changed (134) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +2 -2
  4. package/.mcp.json +1 -1
  5. package/CHANGELOG.md +112 -20
  6. package/CONTRIBUTING.md +71 -0
  7. package/README.md +98 -206
  8. package/SECURITY.md +17 -1
  9. package/dist/{apply-4IGTXOCQ.js → apply-JUTGS5WZ.js} +11 -11
  10. package/dist/{broadcast-3RY3OZGY.js → broadcast-CBMVOV3G.js} +4 -4
  11. package/dist/{chunk-SG5TPMKH.js → chunk-26WLNWDG.js} +2 -2
  12. package/dist/{chunk-ELAGZ635.js → chunk-2FIV63WC.js} +5 -5
  13. package/dist/{chunk-JUXNIXN4.js → chunk-3FCFAQDG.js} +2 -2
  14. package/dist/{chunk-EJBZGIDK.js → chunk-3IDXEV5E.js} +3 -3
  15. package/dist/chunk-65KAQSJP.js +7 -0
  16. package/dist/{chunk-665TA55Z.js → chunk-7HFIGCSL.js} +2 -2
  17. package/dist/{chunk-R4L6LJJ2.js → chunk-7UCZAN4J.js} +2 -2
  18. package/dist/{chunk-J6QLLQVL.js → chunk-A7VF7A35.js} +5 -5
  19. package/dist/{chunk-NZS5CD72.js → chunk-AJ4VXM2U.js} +20 -4
  20. package/dist/{chunk-25GHX674.js → chunk-D77IRGHO.js} +6 -6
  21. package/dist/{chunk-4VCC2NXE.js → chunk-DMZHQZ7P.js} +2 -2
  22. package/dist/{chunk-Q65R3XKX.js → chunk-EAWPJHJ7.js} +2 -2
  23. package/dist/{chunk-PLX3BOOS.js → chunk-F5QYZK7E.js} +2 -2
  24. package/dist/{chunk-YMHUM7AV.js → chunk-F5XMGOOX.js} +7 -1
  25. package/dist/{chunk-7BLPN3W6.js → chunk-FENOGX3U.js} +2 -2
  26. package/dist/{chunk-N5AQ3PP7.js → chunk-I2ZP2PSA.js} +5 -5
  27. package/dist/{chunk-UOCLRM7P.js → chunk-IG33DXLT.js} +16 -16
  28. package/dist/{chunk-RK4PYD7L.js → chunk-LBXO4VPG.js} +2 -2
  29. package/dist/{chunk-BVCTKPT3.js → chunk-LMUBBIE2.js} +2 -2
  30. package/dist/{chunk-Z4HRRXRF.js → chunk-LTZH5E3G.js} +6 -5
  31. package/dist/{chunk-MWFOUBFC.js → chunk-LW4TG7EL.js} +2 -2
  32. package/dist/{chunk-LAZQBMAU.js → chunk-NLEXKE7U.js} +3 -3
  33. package/dist/{chunk-ZH6R642Z.js → chunk-PKODFR5F.js} +2 -2
  34. package/dist/{chunk-IGYRMM62.js → chunk-QEF7EK3T.js} +2 -2
  35. package/dist/{chunk-MM2Y43LC.js → chunk-RPQOBHVU.js} +2 -2
  36. package/dist/{chunk-3NYG4SGU.js → chunk-TXQ7L33K.js} +3 -3
  37. package/dist/{chunk-PWSJJXLQ.js → chunk-VMHUEOT5.js} +8 -8
  38. package/dist/{chunk-65ZHM5RH.js → chunk-VRPMYPZU.js} +9 -9
  39. package/dist/{cli-VYCQJZ5X.js → cli-MI4ZCAZ3.js} +9 -9
  40. package/dist/{cli-ZTCBSDW4.js → cli-ZN7ZVDEZ.js} +3 -3
  41. package/dist/cli.js +4 -4
  42. package/dist/{completion-E7RRG3ZT.js → completion-ILSRB3LW.js} +3 -3
  43. package/dist/{diagnostics-XXH4FLUG.js → diagnostics-XKXVVQWH.js} +6 -6
  44. package/dist/{doctor-ZIOESU3N.js → doctor-O2E63YGO.js} +13 -13
  45. package/dist/{entry-ZNFCTDVE.js → entry-X6CSYQRQ.js} +10 -10
  46. package/dist/{exec-mcp-X6372BLE.js → exec-mcp-2PMWBPD7.js} +8 -8
  47. package/dist/{harness-F2XFDYXF.js → harness-L2KSI2ZB.js} +5 -5
  48. package/dist/harness-launch-gate.js +4 -4
  49. package/dist/harness-worker.js +6 -6
  50. package/dist/hook-body.js +7 -6
  51. package/dist/{hooks-FYE2L5RW.js → hooks-BHTA44X7.js} +3 -3
  52. package/dist/{host-GRY3VAHH.js → host-UIZAXXQH.js} +7 -7
  53. package/dist/{host-X6BR6X4O.js → host-UWK754BW.js} +20 -10
  54. package/dist/{host-run-GCA6H6SR.js → host-run-BI2OTZDZ.js} +5 -5
  55. package/dist/http.js +1 -1
  56. package/dist/{import-mcp-2TTBPVLY.js → import-mcp-GPKJI7DI.js} +6 -6
  57. package/dist/index.d.ts +1 -1
  58. package/dist/index.js +13 -13
  59. package/dist/{init-627KFXTG.js → init-3C2Y7BNJ.js} +2 -2
  60. package/dist/{invoke-LW22Z6ET.js → invoke-44CJRVMK.js} +8 -8
  61. package/dist/{list-NGMSQ5SH.js → list-WL6L4J5H.js} +8 -8
  62. package/dist/{logout-6CSHUWWE.js → logout-F5EJ5MOU.js} +7 -7
  63. package/dist/{logs-SPB6AANY.js → logs-TBUA4UWU.js} +4 -4
  64. package/dist/{mailbox-7BV54Q4R.js → mailbox-BMTZOSZ7.js} +4 -4
  65. package/dist/{mainline-JQTTYJMI.js → mainline-KAD2ERLP.js} +2 -2
  66. package/dist/{mcp-2DKVU3SW.js → mcp-235QZN2A.js} +2 -2
  67. package/dist/{mcp-V23HC3LB.js → mcp-FJ2UQ4RH.js} +2 -2
  68. package/dist/{pause-FFAYRBWI.js → pause-7LILUVGL.js} +4 -4
  69. package/dist/{project-FY62G55N.js → project-5YV5CUEG.js} +4 -4
  70. package/dist/{resume-UU4HZIUP.js → resume-26VFAAMH.js} +4 -4
  71. package/dist/{run-OGA3P7FC.js → run-3AXTZSR7.js} +7 -7
  72. package/dist/{run-HALGEJNJ.js → run-3SOVRQIA.js} +4 -4
  73. package/dist/{serve-NBKT5BKY.js → serve-DQMKTFIV.js} +3 -3
  74. package/dist/{start-login-UIQYQBMC.js → start-login-YTZV6KMF.js} +7 -7
  75. package/dist/{status-NOOHW5WA.js → status-MROQ7WR7.js} +7 -7
  76. package/dist/{status-VHODZPXB.js → status-RO55QPKV.js} +4 -4
  77. package/dist/{status-XQANBVXW.js → status-UME2L33L.js} +11 -11
  78. package/dist/stdio.js +2 -2
  79. package/dist/{sweep-64JDCGK6.js → sweep-35LGQTTO.js} +4 -4
  80. package/dist/{test-MKAXFJOL.js → test-AGZOJLRZ.js} +7 -7
  81. package/dist/{tui-MWKAXE4K.js → tui-G5LLWCSV.js} +5 -5
  82. package/dist/{unbroadcast-KPUEFLZD.js → unbroadcast-5QNGAJR2.js} +4 -4
  83. package/dist/{validate-5GZ5YWNA.js → validate-IU52H2IC.js} +2 -2
  84. package/dist/{worker-RQ575EJL.js → worker-QZ5T6LJD.js} +8 -8
  85. package/docs/authoring.md +82 -0
  86. package/docs/browser-and-desktop.md +46 -0
  87. package/docs/commands.md +325 -0
  88. package/docs/compare.md +35 -0
  89. package/docs/compatibility.md +55 -0
  90. package/docs/embeddings.md +1 -1
  91. package/docs/getting-started.md +105 -0
  92. package/docs/git-workflow.md +60 -0
  93. package/docs/glossary.md +31 -0
  94. package/docs/hooks.md +264 -0
  95. package/docs/install.md +72 -0
  96. package/docs/library-skills.md +132 -0
  97. package/docs/mailbox.md +16 -5
  98. package/docs/project-configuration.md +51 -386
  99. package/docs/sessions.md +64 -0
  100. package/docs/skills.md +4 -45
  101. package/docs/terminal-harness.md +26 -21
  102. package/docs/terminal-workspace.md +4 -13
  103. package/gemini-extension.json +2 -2
  104. package/mcp.json +1 -1
  105. package/package.json +8 -6
  106. package/plugin.json +2 -2
  107. package/plugins/pmcp/.claude-plugin/plugin.json +2 -2
  108. package/plugins/pmcp/.mcp.json +1 -1
  109. package/plugins/pmcp/gemini-extension.json +2 -2
  110. package/plugins/pmcp/mcp.json +1 -1
  111. package/plugins/pmcp/mod/sessions/types.ts +1 -1
  112. package/plugins/pmcp/plugin.json +2 -2
  113. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
  114. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +0 -4
  115. package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
  116. package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
  117. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +19 -11
  118. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +20 -28
  119. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +4 -3
  120. package/schema/catalog-v1.json +36 -7
  121. package/schema/library.json +40 -8
  122. package/schema/marketplace-manifest.json +19 -5
  123. package/schema/plugin-manifest.json +6 -2
  124. package/schema/skill-frontmatter.json +33 -7
  125. package/schema/skill-metadata-core.json +26 -5
  126. package/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
  127. package/skills/package-skill-catalog/SKILL.md +0 -4
  128. package/skills/pmcp-browser/SKILL.md +27 -0
  129. package/skills/pmcp-desktop/SKILL.md +25 -0
  130. package/skills/pmcp-project-init/SKILL.md +19 -11
  131. package/skills/pmcp-sessions-and-git/SKILL.md +20 -28
  132. package/skills/skill-package-scaffold/SKILL.md +4 -3
  133. package/dist/chunk-E7OOHLQR.js +0 -7
  134. package/docs/manual-library-skills.md +0 -74
@@ -0,0 +1,72 @@
1
+ # Installation
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Two of these write the configuration for you. The rest are a line of JSON or a command, depending on where your agent keeps its servers.
6
+
7
+ ## One click
8
+
9
+ [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=pmcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2Rvb3RvZGF5L3BtY3AiXX0=) [Add to VS Code](vscode://mcp/install?name=pmcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modootoday%2Fpmcp%22%5D%7D)
10
+
11
+ Those two links carry the whole server definition in their payload, so the editor opens with the form already filled in.
12
+
13
+ ## As a dev dependency
14
+
15
+ ```sh
16
+ npm install --save-dev @modootoday/pmcp
17
+ ```
18
+
19
+ Installing it is optional. Every configuration below runs it through `npx -y @modootoday/pmcp`, which works with nothing installed; adding it to the project pins the version your team gets.
20
+
21
+ ## Native marketplace
22
+
23
+ The `pmcp` plugin adds the MCP bridge to Claude Code, Codex and Grok, and Gemini installs it
24
+ with `gemini extensions install https://github.com/modootoday/pmcp`. Library instructions
25
+ install the same way, one plugin per library major: see [Library skills](library-skills.md).
26
+
27
+ ## A host that spawns servers over stdio
28
+
29
+ ```json
30
+ {
31
+ "mcpServers": {
32
+ "pmcp": { "command": "npx", "args": ["-y", "@modootoday/pmcp"] }
33
+ }
34
+ }
35
+ ```
36
+
37
+ That is the shape most hosts read. The file it goes in differs by host, and the two commands below write it for you.
38
+
39
+ ## Claude Code
40
+
41
+ ```sh
42
+ claude mcp add pmcp -- npx -y @modootoday/pmcp
43
+ ```
44
+
45
+ ## VS Code, from a script
46
+
47
+ ```sh
48
+ code --add-mcp '{"name":"pmcp","command":"npx","args":["-y","@modootoday/pmcp"]}'
49
+ ```
50
+
51
+ The same thing the badge does, for setting up a workstation rather than clicking through one.
52
+
53
+ ## Options the server takes
54
+
55
+ - `--root <dir>`: a `node_modules` directory to walk, instead of discovering upwards from
56
+ the working directory; repeatable.
57
+ - `--scope <prefix>`: only packages whose names start with this; repeatable, and takes a
58
+ comma-separated list.
59
+
60
+ Both go in the `args` array beside `pmcp`. A host that passes them with no command still gets the server, because a bare spawn is what the protocol expects.
61
+
62
+ ## What arrives
63
+
64
+ - Node 22 or later, or Bun 1.3 or later.
65
+ - Runtime dependencies: `@modelcontextprotocol/server`, `zod`, `semver`, `smol-toml` and `yaml`. Their MIT, ISC and BSD-3-Clause notices are listed in the package's `NOTICE`.
66
+ - No postinstall hook, and nothing downloaded at install time. Semantic ranking needs an optional peer you install yourself.
67
+
68
+ ## Optional native workspace
69
+
70
+ Share MCP settings through the [pmcp.toml reference](project-configuration.md). The [native harness](terminal-harness.md) and [terminal workspace](terminal-workspace.md) run on Linux (glibc 2.35 or later, with a working user systemd manager) or macOS, with Node.js 22; npm installs pmcp-pty and pmcp-tui with pmcp. Run `pmcp tui doctor` to check the host. Provider credentials stay with the native tools.
71
+
72
+ **Check it before you trust it.** `npx -y @modootoday/pmcp list` prints what the server would see from this directory. The CLI includes the free catalog; `--no-builtin` restricts discovery to your own roots. [Getting started](getting-started.md) is the five-minute version.
@@ -0,0 +1,132 @@
1
+ # Library skills
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Free instructions for public libraries, one plugin per library major line. Install them as
6
+ native plugins from the public marketplace, as npm skill packages with `pmcp install`, or, for
7
+ Python, Rust and Go, copy them into a local collection. How pmcp finds and serves skills in
8
+ general is in the [skills reference](skills.md).
9
+
10
+ ## How they are matched and verified
11
+
12
+ Each npm library skill is for one package and major line, not for a kind of task: its
13
+ description names the package and major (most read "Use <package> <major> to ..."). In `docs/catalog.json`, every entry's
14
+ `targets` name the `packageName` and the version `range` it applies to, and
15
+ `pmcp available` and `pmcp install` match that against the version your project has
16
+ installed. Every entry also carries the evidence it was checked against: `evidence.examplesExecuted`
17
+ (the examples that ran), `evidence.verifiedOn` (the date) and, per target,
18
+ `verifiedVersions` (the exact versions they ran on). A native plugin install does not match
19
+ versions for you, so choose the major you use.
20
+
21
+ ## Native plugins from the public marketplace
22
+
23
+ The public repository's canonical sources are standard Agent Skills folders:
24
+ `plugins/<product-major>/skills/<skill-name>/SKILL.md`. Each supported library
25
+ major is a separate selectable plugin. The PMCP bridge has its own `pmcp` plugin.
26
+ The website's `docs/skills/` files are generated downloads from those sources,
27
+ with immutable archives.
28
+
29
+ | Tool | Native distribution |
30
+ | --------------- | -------------------------------------------------------------------- |
31
+ | Claude Code | `.claude-plugin/marketplace.json` and plugin manifests |
32
+ | Codex | `.agents/plugins/marketplace.json` and portable `plugin.json` |
33
+ | Grok Build | Claude-compatible marketplace and plugin manifests |
34
+ | Gemini CLI | `gemini-extension.json`; selected CLI exports are extensions |
35
+ | Antigravity CLI | Selected CLI export with its own `plugin.json` and `mcp_config.json` |
36
+
37
+ The native marketplace commands are in the [README](../README.md#free-library-skills-as-native-plugins).
38
+ Gemini and Antigravity need their own package formats for selected library plugins;
39
+ do not assume that identically named manifest files accept the same schema.
40
+ `pmcp marketplace export <plugin> --runtime <tool> --output <new-directory>`
41
+ materializes a selected package without altering native
42
+ settings or installing it. Use the native manager to review and install that folder.
43
+ Existing export destinations are preserved.
44
+
45
+ The built-in catalog is available without remote fetching.
46
+ `--no-builtin` or `[catalog] builtin = false` opts out; library APIs continue to
47
+ read explicitly supplied catalog roots. `--marketplace <directory>` reads installed
48
+ Claude, Codex and Grok local descriptors, rejects path escapes and does not fetch
49
+ remote plugin sources. Add a remote marketplace with its native manager first.
50
+
51
+ ## npm skill packages
52
+
53
+ Public npm skill installation uses the bundled catalog, a matching installed
54
+ dependency version and immutable free archive URLs. It verifies archive integrity,
55
+ content-only metadata, instruction digests and installed file bytes. npm, Bun or pnpm
56
+ changes the project and lockfile only after confirmation, with scripts disabled.
57
+ `--provider hosted` remains a separate service path with its own access policy.
58
+ Native plugin installation does not automatically version-match dependencies:
59
+ select the appropriate major yourself. Non-npm library instructions remain manual.
60
+
61
+ ## Python, Rust and Go libraries
62
+
63
+ These three library-major skills provide free public instructions for Python,
64
+ Rust and Go libraries. Select them yourself and copy them into a local collection
65
+ you choose. No PMCP login, subscription or registry account is required to read
66
+ the files or load that collection.
67
+
68
+ | Ecosystem | Library | Selected version | Instructions |
69
+ | ---------- | -------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
70
+ | PyPI | `pydantic` 2 | `2.13.4` | [Pydantic SKILL.md](https://pmcp.build/skills/pydantic/2/SKILL.md) |
71
+ | crates.io | `serde_json` 1 | `1.0.149`, with Serde `1.0.228` | [serde_json SKILL.md](https://pmcp.build/skills/serde-json/1/SKILL.md) |
72
+ | Go modules | `github.com/google/uuid` 1 | `v1.6.0` | [Google UUID SKILL.md](https://pmcp.build/skills/google-uuid/1/SKILL.md) |
73
+
74
+ Selected versions identify each skill's scope. They are not a statement that
75
+ every project, feature or AI runtime has been verified. Each SKILL.md contains
76
+ its own supported task boundaries and links to primary documentation and
77
+ licenses. Keep those sources when copying or adapting the instructions.
78
+
79
+ ### Choose a collection and copy only the skills you need
80
+
81
+ Place each downloaded file under its frontmatter name:
82
+
83
+ ```text
84
+ chosen-collection/
85
+ skills/
86
+ pydantic/
87
+ SKILL.md
88
+ serde-json/
89
+ SKILL.md
90
+ google-uuid/
91
+ SKILL.md
92
+ ```
93
+
94
+ Include only your selected files; all three are not required locally. The
95
+ collection may be a plain directory without a package.json. Keep SKILL.md
96
+ frontmatter, source links and any accompanying reference files intact. The
97
+ collection's directory name is a local discovery label, not a registry package
98
+ identity.
99
+
100
+ ### Register the collection explicitly
101
+
102
+ For a direct CLI invocation:
103
+
104
+ ```bash
105
+ pmcp serve --package /absolute/path/to/chosen-collection
106
+ ```
107
+
108
+ Or merge the chosen path into the existing project's pmcp.toml:
109
+
110
+ ```toml
111
+ [catalog]
112
+ packages = ["./chosen-collection"]
113
+ ```
114
+
115
+ Preserve other catalog entries rather than replacing them with this example.
116
+ Project-relative paths resolve from the configuration's directory. The
117
+ existing `skill_catalog`, `skill_find` and `skill_call` tools can then discover
118
+ and read the selected local instructions. Leave folder trust and tool approval
119
+ to the native AI runtime.
120
+
121
+ ### Understand the manual boundary
122
+
123
+ PMCP does not automatically detect these libraries from PyPI, Cargo or Go
124
+ dependencies. They are separate from the managed npm skill catalog and are
125
+ not installed through `pmcp available` or `pmcp install`. Serving a local
126
+ collection does not install a library, download a compiler or run its examples.
127
+
128
+ Loading an instruction file also does not establish model execution evidence.
129
+ Check the project's installed library major, lockfile and environment before
130
+ applying guidance, and run the appropriate project checks after code changes.
131
+ This explicit workflow supplements the package skill discovery described in
132
+ the [skills reference](skills.md).
package/docs/mailbox.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  [Back to the overview](../README.md)
4
4
 
5
+ ## Which mailbox?
6
+
7
+ pmcp has two message systems; pick by who talks to whom.
8
+
9
+ | You want | Use |
10
+ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
11
+ | Agents working in one repository to message each other and you | `[sessions.mailbox]` and `pmcp sessions send` ([Run several agents](sessions.md)) |
12
+ | Actors with their own credentials to exchange messages across projects or hosts, or a mailbox in your own application | this page: `pmcp mailbox` and the mailbox library |
13
+
14
+ They do not share messages, state or credentials.
15
+
5
16
  ## Optional local mailbox
6
17
 
7
18
  Mailbox is disabled by default. The six catalog tools stay read-only. A launcher
@@ -26,9 +37,9 @@ grok-cli, and antigravity; the Antigravity executable is agy.
26
37
 
27
38
  The mailbox CLI also supports send, inbox, read, ack, sessions, rotate, export,
28
39
  backup, and restore. Actor operations accept a private actor-file or existing
29
- binding-file and JSON input file. Administration requires explicit operator
30
- intent. Backups and exports are sensitive. Encrypted recovery bundles are
31
- available through the mailbox API; key custody belongs to the operator.
40
+ binding-file and JSON input file. Administration runs only when you ask for
41
+ it explicitly. Backups and exports are sensitive. Encrypted recovery bundles are
42
+ available through the mailbox API; you keep their keys.
32
43
 
33
44
  ```ts
34
45
  import { MailboxService, MailboxStore } from "@modootoday/pmcp/mailbox";
@@ -54,6 +65,6 @@ The public package contains one reusable local mailbox domain. Optional owned
54
65
  terminal supervision and explicit input delivery are provided separately by the
55
66
  [local CLI harness](terminal-harness.md); MCP mailbox tools cannot reach those
56
67
  execution paths. Provider credentials and approvals remain with native runtimes.
57
- Organization identity, fleet policy and enterprise audit retention belong to a
58
- dedicated host. Existing arbitrary terminal sessions are not captured. Elastic
68
+ Organization identity, organization-wide policy and enterprise audit retention
69
+ belong to a dedicated host. Existing arbitrary terminal sessions are not captured. Elastic
59
70
  License 2.0 and NOTICE continue to apply.