@piagent/platform 1.1.9 → 1.2.0

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 (70) hide show
  1. package/CHANGELOG.md +43 -1
  2. package/README.md +2 -2
  3. package/docs/command-reference-vietnamese.md +13 -4
  4. package/docs/distribution-standard.md +7 -7
  5. package/docs/mcp-and-tools.md +108 -2
  6. package/docs/model-options.md +10 -8
  7. package/docs/operator-manual-vietnamese.md +12 -12
  8. package/docs/publishing-for-teams.md +1 -0
  9. package/docs/quickstart-vietnamese.md +2 -2
  10. package/docs/release-install-policy.md +6 -6
  11. package/docs/security-threat-model.md +1 -1
  12. package/docs/team-onboarding.md +4 -4
  13. package/docs/vercel-docs-site.md +34 -4
  14. package/docs-site/architecture.html +152 -0
  15. package/docs-site/assets/docs.css +1001 -0
  16. package/docs-site/assets/docs.js +84 -0
  17. package/docs-site/commands.html +203 -0
  18. package/docs-site/content/architecture.html +29 -0
  19. package/docs-site/content/commands.html +80 -0
  20. package/docs-site/content/index.html +80 -0
  21. package/docs-site/content/mcp-approval.html +81 -0
  22. package/docs-site/content/mcp-auth.html +76 -0
  23. package/docs-site/content/mcp-servers.html +111 -0
  24. package/docs-site/content/mcp.html +120 -0
  25. package/docs-site/content/permissions.html +54 -0
  26. package/docs-site/content/profiles.html +68 -0
  27. package/docs-site/content/quickstart.html +144 -0
  28. package/docs-site/content/runtime.html +45 -0
  29. package/docs-site/content/scope.html +71 -0
  30. package/docs-site/content/security.html +51 -0
  31. package/docs-site/content/team.html +23 -0
  32. package/docs-site/content/workflows.html +47 -0
  33. package/docs-site/index.html +131 -1534
  34. package/docs-site/mcp-approval.html +204 -0
  35. package/docs-site/mcp-auth.html +199 -0
  36. package/docs-site/mcp-servers.html +234 -0
  37. package/docs-site/mcp.html +243 -0
  38. package/docs-site/permissions.html +177 -0
  39. package/docs-site/profiles.html +191 -0
  40. package/docs-site/quickstart.html +267 -0
  41. package/docs-site/runtime.html +168 -0
  42. package/docs-site/scope.html +194 -0
  43. package/docs-site/security.html +174 -0
  44. package/docs-site/team.html +142 -0
  45. package/docs-site/workflows.html +170 -0
  46. package/package.json +4 -2
  47. package/packages/piagent-core/capabilities/capability-core.js +17 -1
  48. package/packages/piagent-core/extensions/document-intake.ts +5 -5
  49. package/packages/piagent-core/extensions/piagent-guard.ts +316 -0
  50. package/packages/piagent-core/mcp/mcp-approval-store.js +175 -0
  51. package/packages/piagent-core/mcp/mcp-auth-readiness.js +197 -0
  52. package/packages/piagent-core/mcp/mcp-command-actions.js +291 -0
  53. package/packages/piagent-core/mcp/mcp-config-layers.js +133 -0
  54. package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
  55. package/packages/piagent-core/mcp/mcp-server-entry.js +242 -0
  56. package/packages/piagent-core/mcp/mcp-session-view.js +185 -0
  57. package/packages/piagent-core/package.json +7 -3
  58. package/packages/piagent-core/prompts/model-options.md +8 -8
  59. package/scripts/build-docs-site.mjs +421 -0
  60. package/scripts/configure-model-scope.sh +2 -2
  61. package/scripts/configure-subagents.sh +1 -1
  62. package/scripts/install-global.sh +5 -5
  63. package/scripts/mcp-manage.mjs +567 -0
  64. package/scripts/piagent-cli.mjs +1 -1
  65. package/scripts/preview-docs-site.mjs +88 -0
  66. package/scripts/setup.sh +2 -2
  67. package/scripts/team-doctor.sh +18 -2
  68. package/scripts/verify-local.sh +46 -19
  69. package/scripts/verify-release-identity.mjs +8 -2
  70. package/scripts/configure-mcp.sh +0 -349
@@ -0,0 +1,234 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Thêm, xem và gỡ MCP server · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="piagent-mcp có bề mặt lệnh đầy đủ chứ không chỉ seed preset: add, remove, get, list, enable, disable — trên cả bốn scope." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/mcp-servers" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Thêm, xem và gỡ MCP server · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="piagent-mcp có bề mặt lệnh đầy đủ chứ không chỉ seed preset: add, remove, get, list, enable, disable — trên cả bốn scope." />
13
+ <meta property="og:url" content="https://piagent.io.vn/mcp-servers" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ 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"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <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" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link" href="/scope">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link" href="/commands">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link" href="/mcp">MCP overview</a>
68
+ <a class="nav-link current" href="/mcp-servers" aria-current="page">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link" href="/security">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link" href="/runtime">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>MCP</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Quản lý server</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Thêm, xem và gỡ MCP server</h1>
93
+ <p>piagent-mcp có bề mặt lệnh đầy đủ chứ không chỉ seed preset: add, remove, get, list, enable, disable — trên cả bốn scope.</p>
94
+ </div>
95
+ <section class="section">
96
+ <h2 id="hai-be-mat">Hai bề mặt, chọn theo chỗ đang đứng</h2>
97
+ <p>Trong session Pi thì gõ <strong>slash command</strong>. Ngoài terminal thì gõ <strong>CLI</strong>. Cùng một dữ liệu, cùng một cách đọc trạng thái — khác nhau ở chỗ ai chạy.</p>
98
+
99
+ <div class="table-wrap">
100
+ <table>
101
+ <thead>
102
+ <tr><th>Việc</th><th>Trong session</th><th>Trong terminal</th></tr>
103
+ </thead>
104
+ <tbody>
105
+ <tr><td>Mở menu</td><td><span class="inline-code">/piagent-mcp</span></td><td>—</td></tr>
106
+ <tr><td>Xem toàn bộ server + state</td><td><span class="inline-code">/piagent-mcp status</span></td><td><span class="inline-code">piagent-mcp list</span></td></tr>
107
+ <tr><td>Chi tiết một 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>
108
+ <tr><td>Thiếu gì để chạy được</td><td><span class="inline-code">/piagent-mcp doctor</span></td><td><span class="inline-code">piagent-mcp doctor</span></td></tr>
109
+ <tr><td>Duyệt server của repo</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>
110
+ <tr><td>Bật / tắt</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>
111
+ <tr><td>Thêm, xoá, preset</td><td>—</td><td><span class="inline-code">piagent-mcp add|remove|--preset</span></td></tr>
112
+ <tr><td>Trạng thái kết nối, OAuth</td><td><span class="inline-code">/mcp</span>, <span class="inline-code">/mcp-auth</span></td><td>—</td></tr>
113
+ </tbody>
114
+ </table>
115
+ </div>
116
+
117
+ <div class="callout ok-callout">
118
+ <strong>Vì sao slash command chứ không phải gõ CLI trong session</strong>
119
+ <p>Gõ <span class="inline-code">piagent-mcp list</span> giữa session là nhờ model chạy bash, đọc output rồi thuật lại — ba lượt model cho một câu hỏi mà chính process này trả lời được từ file nó đã đọc. Slash command do Pi dispatch thẳng tới handler, <strong>không đi qua model</strong>: không tốn token, không diễn giải lại, và cùng một câu hỏi luôn ra cùng một câu trả lời.</p>
120
+ </div>
121
+
122
+ <div class="callout">
123
+ <strong>Thêm server vẫn ở terminal</strong>
124
+ <p><span class="inline-code">add</span> mang theo shell quoting, tham chiếu <span class="inline-code">${VAR}</span> và một command line sau <span class="inline-code">--</span>. Ba thứ đó đã có một bộ parse đúng là chính shell; viết lại nó bên trong slash command chỉ tạo ra bộ parse thứ hai, tệ hơn. Vì vậy ranh giới là: đọc trạng thái thì ở trong session, ghi định nghĩa server thì ở terminal. Gọi <span class="inline-code">/piagent-mcp add</span> sẽ in ra đúng lệnh terminal cần chạy chứ không đoán.</p>
125
+ </div>
126
+ </section>
127
+
128
+ <section class="section">
129
+ <h2 id="lenh">Lệnh</h2>
130
+
131
+ <div class="command-grid">
132
+ <article class="command-card">
133
+ <h3 id="trong-session">Trong session</h3>
134
+ <p>Không tham số là menu. Biết rồi thì gõ thẳng — Tab auto-complete cả subcommand lẫn tên server.</p>
135
+ <pre><code>/piagent-mcp menu
136
+ /piagent-mcp status bảng đầy đủ
137
+ /piagent-mcp get sentry
138
+ /piagent-mcp doctor
139
+ /piagent-mcp approve internal</code></pre>
140
+ </article>
141
+
142
+ <article class="command-card">
143
+ <h3 id="them-server">Thêm server</h3>
144
+ <p><span class="inline-code">--url</span> cho server remote, <span class="inline-code">--</span> rồi command cho server chạy local. Chạy ở terminal.</p>
145
+ <pre><code>piagent-mcp add sentry --url https://mcp.sentry.dev/mcp --scope global
146
+ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp</code></pre>
147
+ </article>
148
+
149
+ <article class="command-card">
150
+ <h3 id="xem">Xem</h3>
151
+ <p><span class="inline-code">list</span> cho toàn bộ server nhìn thấy được từ project hiện tại, kèm state. <span class="inline-code">get</span> cho chi tiết một server.</p>
152
+ <pre><code>piagent-mcp list
153
+ piagent-mcp get sentry</code></pre>
154
+ </article>
155
+
156
+ <article class="command-card">
157
+ <h3 id="tat-xoa">Tắt và xoá</h3>
158
+ <p><span class="inline-code">disable</span> giữ nguyên định nghĩa, chỉ ngừng dùng. <span class="inline-code">remove</span> xoá hẳn khỏi 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
+
164
+ <article class="command-card">
165
+ <h3 id="preset-lenh">Preset</h3>
166
+ <p>Seed một nhóm server đã pin sẵn. <span class="inline-code">--replace</span> đưa các server thuộc preset về baseline.</p>
167
+ <pre><code>piagent-mcp --preset core --scope global --replace
168
+ piagent-mcp --list</code></pre>
169
+ </article>
170
+ </div>
171
+ </section>
172
+
173
+ <section class="section">
174
+ <h2 id="output">Output nói rõ đã sửa file nào</h2>
175
+ <p>Bốn layer config cùng được đọc, nên câu hỏi đầu tiên khi có gì đó không đúng luôn là "file nào đang có hiệu lực". <span class="inline-code">add</span> trả lời sẵn:</p>
176
+
177
+ <pre><code>$ piagent-mcp add internal --scope project -- npx -y @acme/internal-mcp
178
+ Added local MCP server internal with command: npx -y @acme/internal-mcp in project scope
179
+ File modified: /Users/you/repo/.mcp.json
180
+ This scope is part of the repository, so the server is not usable until approved: piagent-mcp approve internal</code></pre>
181
+
182
+ <p><span class="inline-code">list</span> hiển thị dạng bảng, cột <span class="inline-code">STATE</span> cho biết server nào dùng được ngay:</p>
183
+
184
+ <pre><code>NAME SCOPE TRANSPORT TARGET STATE
185
+ context7 global stdio npx -y @upstash/context7-mcp@3.2.4 ready
186
+ chrome-devtools global stdio npx -y chrome-devtools-mcp@1.6.0 ... ready
187
+ github global stdio docker run -i --rm -e GITHUB_PERSON... needs-env
188
+ internal project stdio npx -y @acme/internal-mcp pending-approval</code></pre>
189
+ </section>
190
+
191
+ <section class="section">
192
+ <h2 id="update">Server tự thêm và luồng update</h2>
193
+ <p>Mỗi lần <span class="inline-code">piagent-update</span> chạy, preset được apply lại với <span class="inline-code">--replace</span>. Vòng merge chỉ đi qua đúng những server ID mà preset sở hữu:</p>
194
+
195
+ <div class="split">
196
+ <div class="card">
197
+ <h3 id="giu-nguyen">Giữ nguyên</h3>
198
+ <p>Server có ID riêng — <span class="inline-code">my-internal</span>, <span class="inline-code">sentry</span>, bất cứ tên nào không thuộc preset — sống qua mọi lần update.</p>
199
+ </div>
200
+ <div class="card">
201
+ <h3 id="bi-ghi-de">Bị ghi đè</h3>
202
+ <p>Sửa tay một server thuộc preset (<span class="inline-code">github</span>, <span class="inline-code">context7</span>…) sẽ bị đưa về baseline ở lần update kế tiếp. Muốn giữ bản riêng thì đặt tên khác.</p>
203
+ </div>
204
+ </div>
205
+ </section>
206
+ <nav class="pager" aria-label="Trang kế tiếp">
207
+ <a class="pager-prev" href="/mcp">
208
+ <span class="pager-label">Trước</span>
209
+ <span class="pager-title">MCP overview</span>
210
+ </a>
211
+ <a class="pager-next" href="/mcp-auth">
212
+ <span class="pager-label">Tiếp</span>
213
+ <span class="pager-title">Auth và readiness</span>
214
+ </a>
215
+ </nav>
216
+
217
+ <footer class="footer">
218
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
219
+ <div class="footer-links" aria-label="External links">
220
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
221
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
222
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
223
+ </div>
224
+ </footer>
225
+ </div>
226
+ </main>
227
+
228
+ <aside class="toc" aria-label="Mục lục trang">
229
+ <p class="toc-title">Trên trang này</p>
230
+ <nav data-toc></nav>
231
+ </aside>
232
+ </div>
233
+ </body>
234
+ </html>
@@ -0,0 +1,243 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>MCP trong Pi Agent Platform · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Pi core không hard-code MCP. Platform cài pi-mcp-adapter để dùng MCP theo kiểu token-efficient, và thêm một lớp quản lý server lên trên bốn layer config." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/mcp" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="MCP trong Pi Agent Platform · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Pi core không hard-code MCP. Platform cài pi-mcp-adapter để dùng MCP theo kiểu token-efficient, và thêm một lớp quản lý server lên trên bốn layer config." />
13
+ <meta property="og:url" content="https://piagent.io.vn/mcp" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ 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"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <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" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link" href="/scope">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link" href="/commands">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link current" href="/mcp" aria-current="page">MCP overview</a>
68
+ <a class="nav-link" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link" href="/security">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link" href="/runtime">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>MCP</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>MCP overview</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>MCP trong Pi Agent Platform</h1>
93
+ <p>Pi core không hard-code MCP. Platform cài pi-mcp-adapter để dùng MCP theo kiểu token-efficient, và thêm một lớp quản lý server lên trên bốn layer config.</p>
94
+ </div>
95
+ <section class="section">
96
+ <h2 id="bat-dau">Bắt đầu ở đâu</h2>
97
+ <p>Gõ <span class="inline-code">/piagent-mcp</span> là ra menu — không cần nhớ subcommand nào:</p>
98
+
99
+ <pre><code>MCP
100
+ Servers — 2/3 ready
101
+ Doctor — 1 need attention (recommended)
102
+ Inspect a server
103
+ Approve a repository server — 1 waiting
104
+ Turn a server off
105
+ Add a server
106
+ All subcommands</code></pre>
107
+
108
+ <p>Menu dựng theo đúng thứ project đang có: chưa server nào bị tắt thì không hiện "turn back on", không server nào chờ duyệt thì không hiện "approve". Chọn việc cần server thì nó hỏi tiếp server nào — trừ khi chỉ có đúng một lựa chọn.</p>
109
+
110
+ <p>Mọi mục trong menu đều gõ thẳng được:</p>
111
+
112
+ <pre><code>/piagent-mcp doctor cái nào chưa chạy được và còn thiếu gì
113
+ /piagent-mcp status bảng đầy đủ
114
+ /mcp trạng thái kết nối live, do adapter giữ
115
+ /mcp-auth &lt;name&gt; đăng nhập OAuth cho một server</code></pre>
116
+
117
+ <p>Ngoài terminal thì cùng bộ lệnh đó bỏ dấu <span class="inline-code">/</span>: <span class="inline-code">piagent-mcp list</span>, <span class="inline-code">piagent-mcp doctor</span>. Thêm và xoá server chỉ có ở terminal. Chi tiết ở <a href="/mcp-servers">Quản lý server</a>.</p>
118
+ </section>
119
+
120
+ <section class="section">
121
+ <h2 id="ba-thu-trung-ten">Ba thứ trùng tên, không nối với nhau</h2>
122
+ <p>Đây là chỗ gây nhầm nhiều nhất. Không có dòng code nào map capability name sang MCP server id — khai <span class="inline-code">"github"</span> trong <span class="inline-code">mcpCapabilities</span> <strong>không</strong> bật server MCP tên <span class="inline-code">github</span>, và ngược lại.</p>
123
+
124
+ <div class="table-wrap">
125
+ <table>
126
+ <thead>
127
+ <tr><th>Thứ</th><th>Ở đâu</th><th>Là gì</th></tr>
128
+ </thead>
129
+ <tbody>
130
+ <tr>
131
+ <td><span class="inline-code">mcpCapabilities: ["github"]</span></td>
132
+ <td><span class="inline-code">.pi/piagent-profile.json</span></td>
133
+ <td>Nhãn capability cho tool registry</td>
134
+ </tr>
135
+ <tr>
136
+ <td><span class="inline-code">toolCapabilities</span></td>
137
+ <td><span class="inline-code">base-policy.json</span></td>
138
+ <td>Map một tool <strong>tên là</strong> <span class="inline-code">github</span> sang capability</td>
139
+ </tr>
140
+ <tr>
141
+ <td>server <span class="inline-code">github</span></td>
142
+ <td><span class="inline-code">~/.config/mcp/mcp.json</span></td>
143
+ <td>Server MCP thật, chạy qua Docker</td>
144
+ </tr>
145
+ </tbody>
146
+ </table>
147
+ </div>
148
+ </section>
149
+
150
+ <section class="section">
151
+ <h2 id="bon-layer-config">Bốn layer config</h2>
152
+ <p>Cả bốn file đều được đọc. <span class="inline-code">--scope</span> của <span class="inline-code">piagent-mcp</span> chính là bốn tên này.</p>
153
+
154
+ <div class="table-wrap">
155
+ <table>
156
+ <thead>
157
+ <tr><th>Scope</th><th>File</th><th>Dùng khi nào</th></tr>
158
+ </thead>
159
+ <tbody>
160
+ <tr><td><span class="inline-code">global</span></td><td><span class="inline-code">~/.config/mcp/mcp.json</span></td><td>Mặc định. Dùng chung cho nhiều agent và nhiều project</td></tr>
161
+ <tr><td><span class="inline-code">pi-global</span></td><td><span class="inline-code">~/.pi/agent/mcp.json</span></td><td>Chỉ khi cần override riêng cho Pi</td></tr>
162
+ <tr><td><span class="inline-code">project</span></td><td><span class="inline-code">.mcp.json</span></td><td>Server đặc thù repo, commit được</td></tr>
163
+ <tr><td><span class="inline-code">pi-project</span></td><td><span class="inline-code">.pi/mcp.json</span></td><td>Override riêng Pi trong một repo</td></tr>
164
+ </tbody>
165
+ </table>
166
+ </div>
167
+
168
+ <div class="callout">
169
+ <strong>Hai layer cuối đi theo repo</strong>
170
+ <p>Clone một repo về là mang theo cả <span class="inline-code">.mcp.json</span> của nó. Vì vậy server ở hai scope đó phải qua <a href="/mcp-approval">approval gate</a> trước khi dùng được.</p>
171
+ </div>
172
+ </section>
173
+
174
+ <section class="section">
175
+ <h2 id="preset">Preset seed sẵn</h2>
176
+ <p><span class="inline-code">piagent-setup</span> và <span class="inline-code">piagent-install</span> đều cài <span class="inline-code">pi-mcp-adapter</span> và seed preset <span class="inline-code">core</span> mặc định. Bỏ qua bằng <span class="inline-code">--no-mcp</span>.</p>
177
+
178
+ <div class="table-wrap">
179
+ <table>
180
+ <thead>
181
+ <tr><th>Preset</th><th>Server</th><th>Mục đích</th></tr>
182
+ </thead>
183
+ <tbody>
184
+ <tr><td><span class="inline-code">minimal</span></td><td>—</td><td>Chỉ seed settings an toàn</td></tr>
185
+ <tr><td><span class="inline-code">docs</span></td><td>Context7</td><td>Docs mới của framework/library</td></tr>
186
+ <tr><td><span class="inline-code">browser</span></td><td>Chrome DevTools, Playwright</td><td>Inspect UI/runtime, browser automation</td></tr>
187
+ <tr><td><span class="inline-code">github</span></td><td>GitHub MCP</td><td>Issue/PR/repo/release workflow</td></tr>
188
+ <tr><td><span class="inline-code">design</span></td><td>Figma remote</td><td>Design-to-code qua Figma OAuth</td></tr>
189
+ <tr><td><span class="inline-code">design-local</span></td><td>Figma desktop</td><td>Dev Mode MCP chạy local</td></tr>
190
+ <tr><td><span class="inline-code">web</span></td><td>Context7, Chrome DevTools, Playwright</td><td>FE/web workflow</td></tr>
191
+ <tr><td><span class="inline-code">core</span></td><td>Context7, Chrome DevTools, GitHub</td><td>Baseline mặc định của team</td></tr>
192
+ <tr><td><span class="inline-code">popular</span></td><td>core + Playwright + Figma</td><td>Baseline nhiều team dev dùng</td></tr>
193
+ <tr><td><span class="inline-code">all</span></td><td>popular + Figma desktop</td><td>Đầy đủ</td></tr>
194
+ </tbody>
195
+ </table>
196
+ </div>
197
+
198
+ <p>Mọi server đều pin theo version hoặc digest. MCP server là code chạy trên máy operator với credential của operator, nên tag trôi nổi sẽ biến mỗi session thành một quyết định supply-chain không ai có mặt để duyệt.</p>
199
+
200
+ <div class="callout">
201
+ <strong>Ghi config không bằng dùng được</strong>
202
+ <p>Server connect lazy — không có gì được kiểm tra cho tới lần gọi đầu tiên. <a href="/mcp-auth">Trạng thái auth</a> cho biết server nào thật sự sẵn sàng.</p>
203
+ </div>
204
+ </section>
205
+
206
+ <section class="section">
207
+ <h2 id="token">Token efficiency</h2>
208
+ <p><span class="inline-code">pi-mcp-adapter</span> đưa mọi server qua một proxy tool duy nhất tên <span class="inline-code">mcp</span>, thay vì nạp toàn bộ tool schema vào context lúc start. Mặc định <span class="inline-code">directTools: false</span>, cộng với <span class="inline-code">outputGuard</span> và <span class="inline-code">idleTimeout</span>.</p>
209
+
210
+ <div class="callout">
211
+ <strong>Bẫy khi bật <span class="inline-code">toolRegistry: enforce</span></strong>
212
+ <p>Proxy tool tên <span class="inline-code">mcp</span> không nằm trong <span class="inline-code">alwaysAllowedTools</span> và không có trong <span class="inline-code">toolCapabilities</span>, nên <span class="inline-code">enforce</span> sẽ chặn <strong>toàn bộ</strong> MCP. Khai thêm <span class="inline-code">mcpCapabilities</span> không cứu được vì block xảy ra trước khi capability được đọc. Ngoại lệ duy nhất là permission profile <span class="inline-code">trusted-full-access</span>.</p>
213
+ </div>
214
+ </section>
215
+ <nav class="pager" aria-label="Trang kế tiếp">
216
+ <a class="pager-prev" href="/workflows">
217
+ <span class="pager-label">Trước</span>
218
+ <span class="pager-title">Workflows</span>
219
+ </a>
220
+ <a class="pager-next" href="/mcp-servers">
221
+ <span class="pager-label">Tiếp</span>
222
+ <span class="pager-title">Quản lý server</span>
223
+ </a>
224
+ </nav>
225
+
226
+ <footer class="footer">
227
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
228
+ <div class="footer-links" aria-label="External links">
229
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
230
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
231
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
232
+ </div>
233
+ </footer>
234
+ </div>
235
+ </main>
236
+
237
+ <aside class="toc" aria-label="Mục lục trang">
238
+ <p class="toc-title">Trên trang này</p>
239
+ <nav data-toc></nav>
240
+ </aside>
241
+ </div>
242
+ </body>
243
+ </html>