@piagent/platform 1.2.15 → 1.2.17

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 (75) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +3 -3
  3. package/docs/README.md +1 -1
  4. package/docs/command-reference-vietnamese.md +2 -2
  5. package/docs/distribution-standard.md +7 -7
  6. package/docs/model-options.md +1 -1
  7. package/docs/operator-manual-vietnamese.md +7 -7
  8. package/docs/release-install-policy.md +6 -6
  9. package/docs/security-threat-model.md +1 -1
  10. package/docs/team-onboarding.md +2 -2
  11. package/docs/vercel-docs-site.md +7 -5
  12. package/docs-site/architecture.html +12 -6
  13. package/docs-site/assets/docs.css +52 -1
  14. package/docs-site/assets/docs.js +4 -2
  15. package/docs-site/benchmark.html +12 -6
  16. package/docs-site/commands.html +12 -6
  17. package/docs-site/content/en/architecture.html +33 -0
  18. package/docs-site/content/en/benchmark.html +164 -0
  19. package/docs-site/content/en/commands.html +39 -0
  20. package/docs-site/content/en/context-engine.html +30 -0
  21. package/docs-site/content/en/index.html +85 -0
  22. package/docs-site/content/en/mcp-approval.html +74 -0
  23. package/docs-site/content/en/mcp-auth.html +57 -0
  24. package/docs-site/content/en/mcp-servers.html +91 -0
  25. package/docs-site/content/en/mcp.html +90 -0
  26. package/docs-site/content/en/permissions.html +19 -0
  27. package/docs-site/content/en/profiles.html +27 -0
  28. package/docs-site/content/en/quickstart.html +126 -0
  29. package/docs-site/content/en/runtime.html +27 -0
  30. package/docs-site/content/en/scope.html +45 -0
  31. package/docs-site/content/en/security.html +33 -0
  32. package/docs-site/content/en/team.html +14 -0
  33. package/docs-site/content/en/workflows.html +21 -0
  34. package/docs-site/content/quickstart.html +1 -1
  35. package/docs-site/context-engine.html +12 -6
  36. package/docs-site/en/architecture.html +166 -0
  37. package/docs-site/en/benchmark.html +297 -0
  38. package/docs-site/en/commands.html +172 -0
  39. package/docs-site/en/context-engine.html +163 -0
  40. package/docs-site/en/index.html +203 -0
  41. package/docs-site/en/mcp-approval.html +207 -0
  42. package/docs-site/en/mcp-auth.html +190 -0
  43. package/docs-site/en/mcp-servers.html +224 -0
  44. package/docs-site/en/mcp.html +223 -0
  45. package/docs-site/en/permissions.html +152 -0
  46. package/docs-site/en/profiles.html +160 -0
  47. package/docs-site/en/quickstart.html +259 -0
  48. package/docs-site/en/runtime.html +160 -0
  49. package/docs-site/en/scope.html +178 -0
  50. package/docs-site/en/security.html +166 -0
  51. package/docs-site/en/team.html +143 -0
  52. package/docs-site/en/workflows.html +154 -0
  53. package/docs-site/index.html +12 -6
  54. package/docs-site/mcp-approval.html +12 -6
  55. package/docs-site/mcp-auth.html +12 -6
  56. package/docs-site/mcp-servers.html +12 -6
  57. package/docs-site/mcp.html +12 -6
  58. package/docs-site/permissions.html +12 -6
  59. package/docs-site/profiles.html +12 -6
  60. package/docs-site/quickstart.html +13 -7
  61. package/docs-site/runtime.html +12 -6
  62. package/docs-site/scope.html +12 -6
  63. package/docs-site/security.html +12 -6
  64. package/docs-site/team.html +12 -6
  65. package/docs-site/workflows.html +12 -6
  66. package/package.json +1 -1
  67. package/packages/piagent-core/package.json +1 -1
  68. package/scripts/build-docs-site.mjs +224 -50
  69. package/scripts/configure-model-scope.sh +4 -4
  70. package/scripts/install-global.sh +1 -1
  71. package/scripts/setup.sh +2 -2
  72. package/scripts/verify-local.sh +7 -1
  73. package/scripts/verify-release-identity.mjs +15 -6
  74. package/templates/global/settings.json +2 -2
  75. package/templates/project/.pi/settings.json +1 -1
package/docs-site/en/mcp-servers.html ADDED
@@ -0,0 +1,224 @@
1
+ <!doctype html>
2
+ <html lang="en" data-copy-success="Copied" data-copy-fallback="Select command">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Add, inspect, and remove MCP servers · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="piagent-mcp provides deterministic add, remove, get, list, enable, and disable operations across all four scopes." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/en/mcp-servers" />
10
+ <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/mcp-servers" />
11
+ <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/mcp-servers" />
12
+ <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/mcp-servers" />
13
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
14
+ <meta property="og:title" content="Add, inspect, and remove MCP servers · Pi Agent Platform Docs" />
15
+ <meta property="og:description" content="piagent-mcp provides deterministic add, remove, get, list, enable, and disable operations across all four scopes." />
16
+ <meta property="og:url" content="https://piagent.io.vn/en/mcp-servers" />
17
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
18
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
19
+ <link
20
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
21
+ rel="stylesheet"
22
+ />
23
+ <link rel="stylesheet" href="/assets/docs.css" />
24
+ <script src="/assets/docs.js" defer></script>
25
+ </head>
26
+ <body>
27
+ <header class="topbar">
28
+ <a class="brand" href="/en/" aria-label="Pi Agent Platform">
29
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
30
+ <span>Pi Agent Platform</span>
31
+ </a>
32
+ <div class="top-actions">
33
+ <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · EN</span>
34
+ <nav class="language-switch" aria-label="Language">
35
+ <a class="language-option" href="/mcp-servers" hreflang="vi" lang="vi">VI</a>
36
+ <a class="language-option current" href="/en/mcp-servers" hreflang="en" lang="en" aria-current="true">EN</a>
37
+ </nav>
38
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Open GitHub repository">
39
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
40
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
41
+ </svg>
42
+ GitHub
43
+ </a>
44
+ <button class="button mobile-menu" type="button" data-menu>Menu</button>
45
+ <a class="button top-command-link" href="/en/commands">Commands</a>
46
+ </div>
47
+ </header>
48
+
49
+ <div class="layout with-toc">
50
+ <aside class="sidebar" data-sidebar>
51
+ <div class="sidebar-search" aria-label="Search documentation">
52
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
53
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
54
+ </svg>
55
+ <input type="search" placeholder="Search pages" data-filter />
56
+ </div>
57
+
58
+ <nav aria-label="Documentation">
59
+ <div class="nav-group">
60
+ <p class="nav-title">Get started</p>
61
+ <a class="nav-link" href="/en/">Overview</a>
62
+ <a class="nav-link" href="/en/quickstart">Quickstart</a>
63
+ <a class="nav-link" href="/en/scope">Platform scope</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">Build</p>
67
+ <a class="nav-link" href="/en/profiles">Project profiles</a>
68
+ <a class="nav-link" href="/en/permissions">Permission modes</a>
69
+ <a class="nav-link" href="/en/commands">Command catalog</a>
70
+ <a class="nav-link" href="/en/workflows">Workflows</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">MCP</p>
74
+ <a class="nav-link" href="/en/mcp">MCP overview</a>
75
+ <a class="nav-link current" href="/en/mcp-servers" aria-current="page">Server management</a>
76
+ <a class="nav-link" href="/en/mcp-auth">Authentication</a>
77
+ <a class="nav-link" href="/en/mcp-approval">Approval gate</a>
78
+ </div>
79
+ <div class="nav-group">
80
+ <p class="nav-title">Operate</p>
81
+ <a class="nav-link" href="/en/security">Security model</a>
82
+ <a class="nav-link" href="/en/architecture">Architecture</a>
83
+ <a class="nav-link" href="/en/context-engine">Context Engine</a>
84
+ <a class="nav-link" href="/en/benchmark">Benchmark</a>
85
+ <a class="nav-link" href="/en/runtime">Runtime tools</a>
86
+ <a class="nav-link" href="/en/team">Team usage</a>
87
+ </div>
88
+ </nav>
89
+ </aside>
90
+
91
+ <main>
92
+ <div class="content-shell" data-article>
93
+ <nav class="breadcrumb" aria-label="Breadcrumb">
94
+ <a href="/en/">Docs</a>
95
+ <span aria-hidden="true">/</span>
96
+ <span>MCP</span>
97
+ <span aria-hidden="true">/</span>
98
+ <span>Server management</span>
99
+ </nav>
100
+ <div class="page-head">
101
+ <h1>Add, inspect, and remove MCP servers</h1>
102
+ <p>piagent-mcp provides deterministic add, remove, get, list, enable, and disable operations across all four scopes.</p>
103
+ </div>
104
+ <section class="section">
105
+ <h2 id="two-surfaces">Two surfaces for two contexts</h2>
106
+ <p>Inside a Pi session, use the <strong>slash command</strong>. In a terminal, use the <strong>CLI</strong>. Both read the same state; the difference is where the operation runs.</p>
107
+ <div class="table-wrap">
108
+ <table>
109
+ <thead><tr><th>Task</th><th>In a session</th><th>In a terminal</th></tr></thead>
110
+ <tbody>
111
+ <tr><td>Open the menu</td><td><span class="inline-code">/piagent-mcp</span></td><td>—</td></tr>
112
+ <tr><td>List servers and state</td><td><span class="inline-code">/piagent-mcp status</span></td><td><span class="inline-code">piagent-mcp list</span></td></tr>
113
+ <tr><td>Inspect one server</td><td><span class="inline-code">/piagent-mcp get &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp get &lt;name&gt;</span></td></tr>
114
+ <tr><td>Show readiness blockers</td><td><span class="inline-code">/piagent-mcp doctor</span></td><td><span class="inline-code">piagent-mcp doctor</span></td></tr>
115
+ <tr><td>Approve a repository server</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp approve &lt;name&gt;</span></td></tr>
116
+ <tr><td>Enable or disable</td><td><span class="inline-code">/piagent-mcp enable|disable &lt;name&gt;</span></td><td><span class="inline-code">piagent-mcp enable|disable &lt;name&gt;</span></td></tr>
117
+ <tr><td>Add, remove, or seed a preset</td><td>—</td><td><span class="inline-code">piagent-mcp add|remove|--preset</span></td></tr>
118
+ <tr><td>Live connection state or OAuth</td><td><span class="inline-code">/mcp</span>, <span class="inline-code">/mcp-auth</span></td><td>—</td></tr>
119
+ </tbody>
120
+ </table>
121
+ </div>
122
+ <div class="callout ok-callout">
123
+ <strong>Why use a slash command instead of invoking the CLI in-session</strong>
124
+ <p>Asking the model to run <span class="inline-code">piagent-mcp list</span> through bash spends model turns executing, reading, and restating data that the current process already has. Pi dispatches the slash command directly to its handler: no model tokens, no interpretation, and a deterministic response.</p>
125
+ </div>
126
+ <div class="callout">
127
+ <strong>Adding a server remains terminal-only</strong>
128
+ <p><span class="inline-code">add</span> includes shell quoting, <span class="inline-code">${VAR}</span> references, and a command line after <span class="inline-code">--</span>. The shell already parses these correctly. Reimplementing that parser in a slash command would create a second, weaker grammar. <span class="inline-code">/piagent-mcp add</span> prints the exact terminal command to run.</p>
129
+ </div>
130
+ </section>
131
+
132
+ <section class="section">
133
+ <h2 id="commands">Commands</h2>
134
+ <div class="command-grid">
135
+ <article class="command-card">
136
+ <h3 id="in-session">In a session</h3>
137
+ <p>No arguments opens the menu. Direct commands support Tab completion for subcommands and server names.</p>
138
+ <pre><code>/piagent-mcp menu
139
+ /piagent-mcp status full table
140
+ /piagent-mcp get sentry
141
+ /piagent-mcp doctor
142
+ /piagent-mcp approve internal</code></pre>
143
+ </article>
144
+ <article class="command-card">
145
+ <h3 id="add-server">Add a server</h3>
146
+ <p>Use <span class="inline-code">--url</span> for a remote server, or place a local server command after <span class="inline-code">--</span>. Run this in a terminal.</p>
147
+ <pre><code>piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
148
+ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp</code></pre>
149
+ </article>
150
+ <article class="command-card">
151
+ <h3 id="inspect">Inspect</h3>
152
+ <p><span class="inline-code">list</span> shows every server visible from the current project and its state. <span class="inline-code">get</span> shows one server in detail.</p>
153
+ <pre><code>piagent-mcp list
154
+ piagent-mcp get sentry</code></pre>
155
+ </article>
156
+ <article class="command-card">
157
+ <h3 id="disable-remove">Disable and remove</h3>
158
+ <p><span class="inline-code">disable</span> preserves the definition but stops using it. <span class="inline-code">remove</span> deletes it from a scope.</p>
159
+ <pre><code>piagent-mcp disable sentry
160
+ piagent-mcp enable sentry
161
+ piagent-mcp remove sentry --scope global</code></pre>
162
+ </article>
163
+ <article class="command-card">
164
+ <h3 id="preset-command">Preset</h3>
165
+ <p>Seed a pinned group of servers. <span class="inline-code">--replace</span> returns preset-owned servers to their baseline.</p>
166
+ <pre><code>piagent-mcp --preset core --scope global --replace
167
+ piagent-mcp --list</code></pre>
168
+ </article>
169
+ </div>
170
+ </section>
171
+
172
+ <section class="section">
173
+ <h2 id="output">Output names the modified file</h2>
174
+ <p>All four configuration layers are read, so the first debugging question is which file is active. <span class="inline-code">add</span> answers that directly:</p>
175
+ <pre><code>$ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
176
+ Added local MCP server internal with command: npx -y @acme/internal-mcp in project scope
177
+ File modified: /Users/you/repo/.mcp.json
178
+ This scope is part of the repository, so the server is not usable until approved: piagent-mcp approve internal</code></pre>
179
+ <p><span class="inline-code">list</span> renders a table whose <span class="inline-code">STATE</span> column identifies immediately usable servers:</p>
180
+ <pre><code>NAME SCOPE TRANSPORT TARGET STATE
181
+ context7 global stdio npx -y @upstash/context7-mcp@3.2.4 ready
182
+ chrome-devtools global stdio npx -y chrome-devtools-mcp@1.6.0 ... ready
183
+ github global stdio docker run -i --rm -e GITHUB_PERSON... needs-env
184
+ internal project stdio npx -y @acme/internal-mcp pending-approval</code></pre>
185
+ </section>
186
+
187
+ <section class="section">
188
+ <h2 id="updates">Custom servers and updates</h2>
189
+ <p>Each <span class="inline-code">piagent-update</span> reapplies the selected preset with <span class="inline-code">--replace</span>. The merge touches only server IDs owned by that preset.</p>
190
+ <div class="split">
191
+ <div class="card"><h3 id="preserved">Preserved</h3><p>Custom IDs such as <span class="inline-code">my-internal</span> or <span class="inline-code">sentry</span> survive every update.</p></div>
192
+ <div class="card"><h3 id="overwritten">Replaced</h3><p>Manual edits to preset-owned IDs such as <span class="inline-code">github</span> or <span class="inline-code">context7</span> return to baseline on the next update. Use a distinct ID for a custom variant.</p></div>
193
+ </div>
194
+ </section>
195
+ <nav class="pager" aria-label="Adjacent pages">
196
+ <a class="pager-prev" href="/en/mcp">
197
+ <span class="pager-label">Previous</span>
198
+ <span class="pager-title">MCP overview</span>
199
+ </a>
200
+ <a class="pager-next" href="/en/mcp-auth">
201
+ <span class="pager-label">Next</span>
202
+ <span class="pager-title">Authentication</span>
203
+ </a>
204
+ </nav>
205
+
206
+ <footer class="footer">
207
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
208
+ <div class="footer-links" aria-label="External links">
209
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
210
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
211
+ <a href="/mcp-servers" hreflang="vi">Tiếng Việt</a>
212
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
213
+ </div>
214
+ </footer>
215
+ </div>
216
+ </main>
217
+
218
+ <aside class="toc" aria-label="Page contents">
219
+ <p class="toc-title">On this page</p>
220
+ <nav data-toc></nav>
221
+ </aside>
222
+ </div>
223
+ </body>
224
+ </html>
package/docs-site/en/mcp.html ADDED
@@ -0,0 +1,223 @@
1
+ <!doctype html>
2
+ <html lang="en" data-copy-success="Copied" data-copy-fallback="Select command">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>MCP in Pi Agent Platform · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="The platform installs pi-mcp-adapter for token-efficient MCP access and manages servers across four configuration layers." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/en/mcp" />
10
+ <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/mcp" />
11
+ <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/mcp" />
12
+ <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/mcp" />
13
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
14
+ <meta property="og:title" content="MCP in Pi Agent Platform · Pi Agent Platform Docs" />
15
+ <meta property="og:description" content="The platform installs pi-mcp-adapter for token-efficient MCP access and manages servers across four configuration layers." />
16
+ <meta property="og:url" content="https://piagent.io.vn/en/mcp" />
17
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
18
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
19
+ <link
20
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
21
+ rel="stylesheet"
22
+ />
23
+ <link rel="stylesheet" href="/assets/docs.css" />
24
+ <script src="/assets/docs.js" defer></script>
25
+ </head>
26
+ <body>
27
+ <header class="topbar">
28
+ <a class="brand" href="/en/" aria-label="Pi Agent Platform">
29
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
30
+ <span>Pi Agent Platform</span>
31
+ </a>
32
+ <div class="top-actions">
33
+ <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · EN</span>
34
+ <nav class="language-switch" aria-label="Language">
35
+ <a class="language-option" href="/mcp" hreflang="vi" lang="vi">VI</a>
36
+ <a class="language-option current" href="/en/mcp" hreflang="en" lang="en" aria-current="true">EN</a>
37
+ </nav>
38
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Open GitHub repository">
39
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
40
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
41
+ </svg>
42
+ GitHub
43
+ </a>
44
+ <button class="button mobile-menu" type="button" data-menu>Menu</button>
45
+ <a class="button top-command-link" href="/en/commands">Commands</a>
46
+ </div>
47
+ </header>
48
+
49
+ <div class="layout with-toc">
50
+ <aside class="sidebar" data-sidebar>
51
+ <div class="sidebar-search" aria-label="Search documentation">
52
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
53
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
54
+ </svg>
55
+ <input type="search" placeholder="Search pages" data-filter />
56
+ </div>
57
+
58
+ <nav aria-label="Documentation">
59
+ <div class="nav-group">
60
+ <p class="nav-title">Get started</p>
61
+ <a class="nav-link" href="/en/">Overview</a>
62
+ <a class="nav-link" href="/en/quickstart">Quickstart</a>
63
+ <a class="nav-link" href="/en/scope">Platform scope</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">Build</p>
67
+ <a class="nav-link" href="/en/profiles">Project profiles</a>
68
+ <a class="nav-link" href="/en/permissions">Permission modes</a>
69
+ <a class="nav-link" href="/en/commands">Command catalog</a>
70
+ <a class="nav-link" href="/en/workflows">Workflows</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">MCP</p>
74
+ <a class="nav-link current" href="/en/mcp" aria-current="page">MCP overview</a>
75
+ <a class="nav-link" href="/en/mcp-servers">Server management</a>
76
+ <a class="nav-link" href="/en/mcp-auth">Authentication</a>
77
+ <a class="nav-link" href="/en/mcp-approval">Approval gate</a>
78
+ </div>
79
+ <div class="nav-group">
80
+ <p class="nav-title">Operate</p>
81
+ <a class="nav-link" href="/en/security">Security model</a>
82
+ <a class="nav-link" href="/en/architecture">Architecture</a>
83
+ <a class="nav-link" href="/en/context-engine">Context Engine</a>
84
+ <a class="nav-link" href="/en/benchmark">Benchmark</a>
85
+ <a class="nav-link" href="/en/runtime">Runtime tools</a>
86
+ <a class="nav-link" href="/en/team">Team usage</a>
87
+ </div>
88
+ </nav>
89
+ </aside>
90
+
91
+ <main>
92
+ <div class="content-shell" data-article>
93
+ <nav class="breadcrumb" aria-label="Breadcrumb">
94
+ <a href="/en/">Docs</a>
95
+ <span aria-hidden="true">/</span>
96
+ <span>MCP</span>
97
+ <span aria-hidden="true">/</span>
98
+ <span>MCP overview</span>
99
+ </nav>
100
+ <div class="page-head">
101
+ <h1>MCP in Pi Agent Platform</h1>
102
+ <p>The platform installs pi-mcp-adapter for token-efficient MCP access and manages servers across four configuration layers.</p>
103
+ </div>
104
+ <section class="section">
105
+ <h2 id="start">Where to start</h2>
106
+ <p>Enter <span class="inline-code">/piagent-mcp</span> to open a menu. You do not need to memorize subcommands:</p>
107
+ <pre><code>MCP
108
+ Servers — 2/3 ready
109
+ Doctor — 1 need attention (recommended)
110
+ Inspect a server
111
+ Approve a repository server — 1 waiting
112
+ Turn a server off
113
+ Add a server
114
+ All subcommands</code></pre>
115
+ <p>The menu reflects the current project. It does not offer "turn back on" when no server is disabled or "approve" when nothing is waiting. When an action requires a server, it asks which one unless only one choice exists.</p>
116
+ <p>Every menu item also has a direct command:</p>
117
+ <pre><code>/piagent-mcp doctor show what is blocked and what it needs
118
+ /piagent-mcp status show the full table
119
+ /mcp show live connection state from the adapter
120
+ /mcp-auth &lt;name&gt; authenticate one OAuth server</code></pre>
121
+ <p>In a terminal, use the same command family without the slash: <span class="inline-code">piagent-mcp list</span> or <span class="inline-code">piagent-mcp doctor</span>. Adding and removing server definitions is terminal-only. See <a href="/en/mcp-servers">Server management</a>.</p>
122
+ </section>
123
+
124
+ <section class="section">
125
+ <h2 id="three-similar-names">Three similar names that are not connected</h2>
126
+ <p>No code maps a capability name to an MCP server ID. Declaring <span class="inline-code">"github"</span> in <span class="inline-code">mcpCapabilities</span> does <strong>not</strong> enable the MCP server named <span class="inline-code">github</span>, and the reverse is also false.</p>
127
+ <div class="table-wrap">
128
+ <table>
129
+ <thead><tr><th>Item</th><th>Location</th><th>Meaning</th></tr></thead>
130
+ <tbody>
131
+ <tr><td><span class="inline-code">mcpCapabilities: ["github"]</span></td><td><span class="inline-code">.pi/piagent-profile.json</span></td><td>A capability label for the tool registry</td></tr>
132
+ <tr><td><span class="inline-code">toolCapabilities</span></td><td><span class="inline-code">base-policy.json</span></td><td>Maps a tool <strong>named</strong> <span class="inline-code">github</span> to a capability</td></tr>
133
+ <tr><td><span class="inline-code">github</span> server</td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>The actual MCP server, running through Docker</td></tr>
134
+ </tbody>
135
+ </table>
136
+ </div>
137
+ </section>
138
+
139
+ <section class="section">
140
+ <h2 id="four-config-layers">Four configuration layers</h2>
141
+ <p>All four files are read. The <span class="inline-code">--scope</span> option of <span class="inline-code">piagent-mcp</span> uses these names.</p>
142
+ <div class="table-wrap">
143
+ <table>
144
+ <thead><tr><th>Scope</th><th>File</th><th>Use</th></tr></thead>
145
+ <tbody>
146
+ <tr><td><span class="inline-code">global</span></td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>Default shared configuration for multiple agents and projects</td></tr>
147
+ <tr><td><span class="inline-code">pi-global</span></td><td><span class="inline-code">~/.pi/agent/mcp.json</span></td><td>Pi-specific global overrides</td></tr>
148
+ <tr><td><span class="inline-code">project</span></td><td><span class="inline-code">.mcp.json</span></td><td>Repository-specific, committable server definitions</td></tr>
149
+ <tr><td><span class="inline-code">pi-project</span></td><td><span class="inline-code">.pi/mcp.json</span></td><td>Pi-specific overrides for one repository</td></tr>
150
+ </tbody>
151
+ </table>
152
+ </div>
153
+ <div class="callout">
154
+ <strong>The final two layers travel with the repository</strong>
155
+ <p>Cloning a repository also brings its <span class="inline-code">.mcp.json</span>. Servers from these scopes must pass the <a href="/en/mcp-approval">approval gate</a> before use.</p>
156
+ </div>
157
+ </section>
158
+
159
+ <section class="section">
160
+ <h2 id="presets">Pinned presets</h2>
161
+ <p><span class="inline-code">piagent-setup</span> and <span class="inline-code">piagent-install</span> install <span class="inline-code">pi-mcp-adapter</span> and seed the <span class="inline-code">core</span> preset by default. Skip this with <span class="inline-code">--no-mcp</span>.</p>
162
+ <div class="table-wrap">
163
+ <table>
164
+ <thead><tr><th>Preset</th><th>Servers</th><th>Purpose</th></tr></thead>
165
+ <tbody>
166
+ <tr><td><span class="inline-code">minimal</span></td><td>—</td><td>Safe settings only</td></tr>
167
+ <tr><td><span class="inline-code">docs</span></td><td>Context7</td><td>Current framework and library docs</td></tr>
168
+ <tr><td><span class="inline-code">browser</span></td><td>Chrome DevTools, Playwright</td><td>UI/runtime inspection and browser automation</td></tr>
169
+ <tr><td><span class="inline-code">github</span></td><td>GitHub MCP</td><td>Issue, PR, repository, and release workflows</td></tr>
170
+ <tr><td><span class="inline-code">design</span></td><td>Figma remote</td><td>Design-to-code through Figma OAuth</td></tr>
171
+ <tr><td><span class="inline-code">design-local</span></td><td>Figma desktop</td><td>Local Dev Mode MCP</td></tr>
172
+ <tr><td><span class="inline-code">web</span></td><td>Context7, Chrome DevTools, Playwright</td><td>Frontend and web workflows</td></tr>
173
+ <tr><td><span class="inline-code">core</span></td><td>Context7, Chrome DevTools, GitHub</td><td>Default team baseline</td></tr>
174
+ <tr><td><span class="inline-code">popular</span></td><td>core + Playwright + Figma</td><td>A broader development baseline</td></tr>
175
+ <tr><td><span class="inline-code">all</span></td><td>popular + Figma desktop</td><td>Complete preset</td></tr>
176
+ </tbody>
177
+ </table>
178
+ </div>
179
+ <p>Every server is pinned by version or digest. An MCP server is code running on the operator's machine with the operator's credentials, so floating tags would turn each session into an unattended supply-chain decision.</p>
180
+ <div class="callout">
181
+ <strong>Writing configuration does not prove readiness</strong>
182
+ <p>Servers connect lazily and are not checked until first use. <a href="/en/mcp-auth">Authentication and readiness</a> explains which servers can actually run.</p>
183
+ </div>
184
+ </section>
185
+
186
+ <section class="section">
187
+ <h2 id="token-efficiency">Token efficiency</h2>
188
+ <p><span class="inline-code">pi-mcp-adapter</span> exposes all servers through one proxy tool named <span class="inline-code">mcp</span> instead of loading every tool schema into startup context. Defaults include <span class="inline-code">directTools: false</span>, <span class="inline-code">outputGuard</span>, and <span class="inline-code">idleTimeout</span>.</p>
189
+ <div class="callout">
190
+ <strong>Warning when enabling <span class="inline-code">toolRegistry: enforce</span></strong>
191
+ <p>The proxy tool <span class="inline-code">mcp</span> is not in <span class="inline-code">alwaysAllowedTools</span> or <span class="inline-code">toolCapabilities</span>, so enforce mode blocks <strong>all</strong> MCP access. Adding <span class="inline-code">mcpCapabilities</span> cannot bypass that earlier block. The only exception is <span class="inline-code">trusted-full-access</span>.</p>
192
+ </div>
193
+ </section>
194
+ <nav class="pager" aria-label="Adjacent pages">
195
+ <a class="pager-prev" href="/en/workflows">
196
+ <span class="pager-label">Previous</span>
197
+ <span class="pager-title">Workflows</span>
198
+ </a>
199
+ <a class="pager-next" href="/en/mcp-servers">
200
+ <span class="pager-label">Next</span>
201
+ <span class="pager-title">Server management</span>
202
+ </a>
203
+ </nav>
204
+
205
+ <footer class="footer">
206
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
207
+ <div class="footer-links" aria-label="External links">
208
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
209
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
210
+ <a href="/mcp" hreflang="vi">Tiếng Việt</a>
211
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
212
+ </div>
213
+ </footer>
214
+ </div>
215
+ </main>
216
+
217
+ <aside class="toc" aria-label="Page contents">
218
+ <p class="toc-title">On this page</p>
219
+ <nav data-toc></nav>
220
+ </aside>
221
+ </div>
222
+ </body>
223
+ </html>
package/docs-site/en/permissions.html ADDED
@@ -0,0 +1,152 @@
1
+ <!doctype html>
2
+ <html lang="en" data-copy-success="Copied" data-copy-fallback="Select command">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Change task permissions with one command · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Permission modes are session-local overrides. Changing a mode does not modify the project profile." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/en/permissions" />
10
+ <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/permissions" />
11
+ <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/permissions" />
12
+ <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/permissions" />
13
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
14
+ <meta property="og:title" content="Change task permissions with one command · Pi Agent Platform Docs" />
15
+ <meta property="og:description" content="Permission modes are session-local overrides. Changing a mode does not modify the project profile." />
16
+ <meta property="og:url" content="https://piagent.io.vn/en/permissions" />
17
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
18
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
19
+ <link
20
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
21
+ rel="stylesheet"
22
+ />
23
+ <link rel="stylesheet" href="/assets/docs.css" />
24
+ <script src="/assets/docs.js" defer></script>
25
+ </head>
26
+ <body>
27
+ <header class="topbar">
28
+ <a class="brand" href="/en/" aria-label="Pi Agent Platform">
29
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
30
+ <span>Pi Agent Platform</span>
31
+ </a>
32
+ <div class="top-actions">
33
+ <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · EN</span>
34
+ <nav class="language-switch" aria-label="Language">
35
+ <a class="language-option" href="/permissions" hreflang="vi" lang="vi">VI</a>
36
+ <a class="language-option current" href="/en/permissions" hreflang="en" lang="en" aria-current="true">EN</a>
37
+ </nav>
38
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Open GitHub repository">
39
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
40
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
41
+ </svg>
42
+ GitHub
43
+ </a>
44
+ <button class="button mobile-menu" type="button" data-menu>Menu</button>
45
+ <a class="button top-command-link" href="/en/commands">Commands</a>
46
+ </div>
47
+ </header>
48
+
49
+ <div class="layout with-toc">
50
+ <aside class="sidebar" data-sidebar>
51
+ <div class="sidebar-search" aria-label="Search documentation">
52
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
53
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
54
+ </svg>
55
+ <input type="search" placeholder="Search pages" data-filter />
56
+ </div>
57
+
58
+ <nav aria-label="Documentation">
59
+ <div class="nav-group">
60
+ <p class="nav-title">Get started</p>
61
+ <a class="nav-link" href="/en/">Overview</a>
62
+ <a class="nav-link" href="/en/quickstart">Quickstart</a>
63
+ <a class="nav-link" href="/en/scope">Platform scope</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">Build</p>
67
+ <a class="nav-link" href="/en/profiles">Project profiles</a>
68
+ <a class="nav-link current" href="/en/permissions" aria-current="page">Permission modes</a>
69
+ <a class="nav-link" href="/en/commands">Command catalog</a>
70
+ <a class="nav-link" href="/en/workflows">Workflows</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">MCP</p>
74
+ <a class="nav-link" href="/en/mcp">MCP overview</a>
75
+ <a class="nav-link" href="/en/mcp-servers">Server management</a>
76
+ <a class="nav-link" href="/en/mcp-auth">Authentication</a>
77
+ <a class="nav-link" href="/en/mcp-approval">Approval gate</a>
78
+ </div>
79
+ <div class="nav-group">
80
+ <p class="nav-title">Operate</p>
81
+ <a class="nav-link" href="/en/security">Security model</a>
82
+ <a class="nav-link" href="/en/architecture">Architecture</a>
83
+ <a class="nav-link" href="/en/context-engine">Context Engine</a>
84
+ <a class="nav-link" href="/en/benchmark">Benchmark</a>
85
+ <a class="nav-link" href="/en/runtime">Runtime tools</a>
86
+ <a class="nav-link" href="/en/team">Team usage</a>
87
+ </div>
88
+ </nav>
89
+ </aside>
90
+
91
+ <main>
92
+ <div class="content-shell" data-article>
93
+ <nav class="breadcrumb" aria-label="Breadcrumb">
94
+ <a href="/en/">Docs</a>
95
+ <span aria-hidden="true">/</span>
96
+ <span>Build</span>
97
+ <span aria-hidden="true">/</span>
98
+ <span>Permission modes</span>
99
+ </nav>
100
+ <div class="page-head">
101
+ <h1>Change task permissions with one command</h1>
102
+ <p>Permission modes are session-local overrides. Changing a mode does not modify the project profile.</p>
103
+ </div>
104
+ <section class="section">
105
+ <div class="table-wrap">
106
+ <table>
107
+ <thead><tr><th>Mode</th><th>Use it for</th><th>Boundary</th><th>Command</th></tr></thead>
108
+ <tbody>
109
+ <tr><td><span class="inline-code">read-only</span></td><td>Scouting, audits, mapping, and reviews without source edits.</td><td>Allows read, grep, find, ls, and Piagent tools; blocks shell, write, and unknown tools.</td><td><span class="inline-code">/permission read-only</span></td></tr>
110
+ <tr><td><span class="inline-code">workspace-write</span></td><td>Normal implementation inside the repository.</td><td>Default guarded mode with protected paths, shell policy, capabilities, and verification gates.</td><td><span class="inline-code">/permission workspace-write</span></td></tr>
111
+ <tr><td><span class="inline-code">trusted-full-access</span></td><td>Automation in a trusted repository with a clearly bounded task.</td><td>Expands autonomy while retaining protected paths, redaction, integrity locks, and confirmation gates.</td><td><span class="inline-code">/permission full-access</span></td></tr>
112
+ </tbody>
113
+ </table>
114
+ </div>
115
+
116
+ <div class="command-grid">
117
+ <article class="command-card"><header><span>Show permission</span><button class="clip-btn" data-clip="/permission status">Copy</button></header><pre><code>/permission status</code></pre></article>
118
+ <article class="command-card"><header><span>Read-only session</span><button class="clip-btn" data-clip="/permission read-only">Copy</button></header><pre><code>/permission read-only</code></pre></article>
119
+ <article class="command-card"><header><span>Workspace write</span><button class="clip-btn" data-clip="/permission workspace-write">Copy</button></header><pre><code>/permission workspace-write</code></pre></article>
120
+ <article class="command-card"><header><span>Full access with a task</span><button class="clip-btn" data-clip="/permission full-access Run the trusted local verification suite.">Copy</button></header><pre><code>/permission full-access Run the trusted local verification suite.</code></pre></article>
121
+ </div>
122
+ </section>
123
+ <nav class="pager" aria-label="Adjacent pages">
124
+ <a class="pager-prev" href="/en/profiles">
125
+ <span class="pager-label">Previous</span>
126
+ <span class="pager-title">Project profiles</span>
127
+ </a>
128
+ <a class="pager-next" href="/en/commands">
129
+ <span class="pager-label">Next</span>
130
+ <span class="pager-title">Command catalog</span>
131
+ </a>
132
+ </nav>
133
+
134
+ <footer class="footer">
135
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
136
+ <div class="footer-links" aria-label="External links">
137
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
138
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
139
+ <a href="/permissions" hreflang="vi">Tiếng Việt</a>
140
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
141
+ </div>
142
+ </footer>
143
+ </div>
144
+ </main>
145
+
146
+ <aside class="toc" aria-label="Page contents">
147
+ <p class="toc-title">On this page</p>
148
+ <nav data-toc></nav>
149
+ </aside>
150
+ </div>
151
+ </body>
152
+ </html>