@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,204 @@
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>Server đến từ repo phải được duyệt · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/mcp-approval" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Server đến từ repo phải được duyệt · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest." />
13
+ <meta property="og:url" content="https://piagent.io.vn/mcp-approval" />
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" 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 current" href="/mcp-approval" aria-current="page">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>Approval gate</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Server đến từ repo phải được duyệt</h1>
93
+ <p>Clone một repo lạ rồi mở session không được phép cho tác giả repo đó một process trên máy mình. Quyết định lưu ngoài repo và pin theo digest.</p>
94
+ </div>
95
+ <section class="section">
96
+ <h2 id="van-de">Vấn đề</h2>
97
+ <p>Repo mang theo được <span class="inline-code">.mcp.json</span> và <span class="inline-code">.pi/mcp.json</span>. Clone một repo lạ rồi mở session <strong>không</strong> được phép cho tác giả repo đó một process trên máy mình, với credential của mình. Nên server ở hai scope này không dùng được cho tới khi có người trên máy này duyệt.</p>
98
+
99
+ <pre><code>/piagent-mcp get internal # đọc trước
100
+ /piagent-mcp approve internal # hoặc reject, hoặc reset</code></pre>
101
+
102
+ <p>Trong terminal thì bỏ dấu <span class="inline-code">/</span>: <span class="inline-code">piagent-mcp get internal</span>. Cùng một quyết định, cùng một file.</p>
103
+
104
+ <p><span class="inline-code">approve</span> in ra định nghĩa trước khi ghi quyết định — duyệt mà không đọc chính là thứ gate này sinh ra để ngăn.</p>
105
+ </section>
106
+
107
+ <section class="section">
108
+ <h2 id="ba-tinh-chat">Ba tính chất</h2>
109
+
110
+ <div class="grid">
111
+ <div class="card">
112
+ <h3 id="ngoai-repo">Quyết định nằm ngoài repo</h3>
113
+ <p>Ghi vào <span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. Repo tự duyệt được cho chính nó thì gate coi như không tồn tại. Fork, đổi tên, checkout thứ hai — tất cả bắt đầu lại từ <span class="inline-code">pending</span>.</p>
114
+ </div>
115
+ <div class="card">
116
+ <h3 id="pin-digest">Pin theo digest</h3>
117
+ <p>Duyệt là đồng ý với <em>thứ server đó chạy</em>. Đổi command, URL hay args là một câu hỏi mới, state về <span class="inline-code">approval-changed</span>. Cùng cách tách consent với build mà capability lock đang dùng.</p>
118
+ </div>
119
+ <div class="card">
120
+ <h3 id="enforce-tool-call">Enforce ở tool call</h3>
121
+ <p>Guard chặn cả proxy (<span class="inline-code">mcp</span> với <span class="inline-code">input.server</span>) lẫn dạng direct tool (<span class="inline-code">mcp__&lt;server&gt;__&lt;tool&gt;</span>). Gate chỉ đọc proxy sẽ bị đi vòng bằng cách bật <span class="inline-code">directTools</span>.</p>
122
+ </div>
123
+ </div>
124
+ </section>
125
+
126
+ <section class="section">
127
+ <h2 id="gioi-han">Giới hạn</h2>
128
+
129
+ <div class="callout">
130
+ <strong>Không chặn được connection</strong>
131
+ <p>Adapter sở hữu kết nối; extension không ngăn được việc một kết nối được mở. Cái bị chặn là <strong>mọi tool call</strong>, không phải bản thân kết nối. Phần rủi ro còn lại là chính kết nối đó, và việc server phía kia ghi log rằng có người kết nối tới.</p>
132
+ </div>
133
+
134
+ <p>Server ở <span class="inline-code">global</span> và <span class="inline-code">pi-global</span> không qua gate. Hai layer đó nằm ngoài mọi repo — không repo nào đặt được server vào đó — và bắt người dùng duyệt config của chính mình trên từng máy là vô nghĩa.</p>
135
+ </section>
136
+
137
+ <section class="section">
138
+ <h2 id="thiet-ke">Bốn quyết định thiết kế</h2>
139
+
140
+ <div class="table-wrap">
141
+ <table>
142
+ <thead>
143
+ <tr><th>Quyết định</th><th>Vì sao</th></tr>
144
+ </thead>
145
+ <tbody>
146
+ <tr>
147
+ <td>Chỉ gate server đến từ repo</td>
148
+ <td>Chỉ <span class="inline-code">.mcp.json</span> và <span class="inline-code">.pi/mcp.json</span> đi theo clone. Server người dùng tự đặt trên máy mình không cần ai duyệt.</td>
149
+ </tr>
150
+ <tr>
151
+ <td>Quyết định lưu ngoài repo</td>
152
+ <td><span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. Nếu lưu trong repo thì repo tự duyệt cho chính nó — gate mất nghĩa ngay từ đầu.</td>
153
+ </tr>
154
+ <tr>
155
+ <td>Pin theo digest của định nghĩa</td>
156
+ <td>Duyệt là duyệt <em>đúng</em> command và URL đó. Đổi command, đổi args, đổi URL thì server quay về <span class="inline-code">pending</span> chứ không kế thừa quyết định cũ.</td>
157
+ </tr>
158
+ <tr>
159
+ <td>Chặn ở <span class="inline-code">tool_call</span></td>
160
+ <td>Cả dạng proxy <span class="inline-code">mcp</span> lẫn dạng direct <span class="inline-code">mcp__&lt;server&gt;__&lt;tool&gt;</span>, để không có đường vòng.</td>
161
+ </tr>
162
+ </tbody>
163
+ </table>
164
+ </div>
165
+
166
+ <p>Điểm chặn lý tưởng là trước khi connect, nhưng chặn được ở đó thì phải sở hữu connection. Platform chạy trong Pi và không sở hữu nó, nên nó chọn điểm chặn xa nhất mà nó thật sự kiểm soát được — rồi nói rõ phần còn thừa thay vì để người đọc tự suy ra.</p>
167
+ </section>
168
+
169
+ <section class="section">
170
+ <h2 id="migration">Migration</h2>
171
+ <div class="callout">
172
+ <strong>Project đã có server từ trước</strong>
173
+ <p>Project nào đã có server trong <span class="inline-code">.mcp.json</span> hoặc <span class="inline-code">.pi/mcp.json</span> sẽ chuyển sang <span class="inline-code">pending-approval</span> sau khi update. Chạy <span class="inline-code">/piagent-mcp approve &lt;name&gt;</span> một lần cho mỗi project. Template ship rỗng nên đa số project không bị ảnh hưởng; notice đầu session và <span class="inline-code">doctor</span> đều nêu tên server cần duyệt.</p>
174
+ </div>
175
+ </section>
176
+ <nav class="pager" aria-label="Trang kế tiếp">
177
+ <a class="pager-prev" href="/mcp-auth">
178
+ <span class="pager-label">Trước</span>
179
+ <span class="pager-title">Auth và readiness</span>
180
+ </a>
181
+ <a class="pager-next" href="/security">
182
+ <span class="pager-label">Tiếp</span>
183
+ <span class="pager-title">Security model</span>
184
+ </a>
185
+ </nav>
186
+
187
+ <footer class="footer">
188
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
189
+ <div class="footer-links" aria-label="External links">
190
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
191
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
192
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
193
+ </div>
194
+ </footer>
195
+ </div>
196
+ </main>
197
+
198
+ <aside class="toc" aria-label="Mục lục trang">
199
+ <p class="toc-title">Trên trang này</p>
200
+ <nav data-toc></nav>
201
+ </aside>
202
+ </div>
203
+ </body>
204
+ </html>
@@ -0,0 +1,199 @@
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>Đăng nhập và trạng thái sẵn sàng · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/mcp-auth" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Đăng nhập và trạng thái sẵn sàng · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được." />
13
+ <meta property="og:url" content="https://piagent.io.vn/mcp-auth" />
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" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link current" href="/mcp-auth" aria-current="page">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>Auth và readiness</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Đăng nhập và trạng thái sẵn sàng</h1>
93
+ <p>Platform không giữ token và không tự chạy OAuth. Nó từ chối ghi secret vào config, và cho biết server nào thật sự gọi được.</p>
94
+ </div>
95
+ <section class="section">
96
+ <h2 id="khong-giu-token">Platform không giữ token</h2>
97
+ <p>Token MCP đã có chỗ ở: luồng OAuth thuộc về <span class="inline-code">pi-mcp-adapter</span> — chính nó đăng ký <span class="inline-code">/mcp</span> và <span class="inline-code">/mcp-auth</span>, và chính nó lưu, refresh, thu hồi. Dựng thêm một kho credential nữa để giữ credential của bên thứ ba chỉ tạo thêm một chỗ để token rò ra. Việc của platform vì vậy là <strong>phát hiện và chỉ đường</strong>.</p>
98
+
99
+ <pre><code>/mcp-auth figma</code></pre>
100
+
101
+ <div class="callout ok-callout">
102
+ <strong>Ranh giới</strong>
103
+ <p>Platform không chạy OAuth, không lưu token, không refresh. Nó biết một server <em>cần</em> đăng nhập, nhưng không biết phiên đăng nhập còn hạn hay không — và nó nói đúng như vậy thay vì đoán.</p>
104
+ </div>
105
+ </section>
106
+
107
+ <section class="section">
108
+ <h2 id="tu-choi-secret">Secret bị từ chối ngay khi ghi config</h2>
109
+ <p>MCP config được nhiều client đọc, nằm trong home hoặc trong repo, và ở scope <span class="inline-code">project</span> thì được commit. Một token gõ vào <span class="inline-code">--env</span> sẽ đi tới tất cả những chỗ đó. Nên <span class="inline-code">add</span> từ chối, và nói luôn dạng cần dùng:</p>
110
+
111
+ <pre><code>$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
112
+ FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
113
+ written into MCP config. Export it in your shell and reference it instead:
114
+ --env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'</code></pre>
115
+
116
+ <div class="split">
117
+ <div class="card">
118
+ <h3 id="theo-ten">Theo tên field</h3>
119
+ <p>Tên chứa <span class="inline-code">token</span>, <span class="inline-code">secret</span>, <span class="inline-code">password</span>, <span class="inline-code">api_key</span>, <span class="inline-code">authorization</span>… thì giá trị bắt buộc phải là tham chiếu biến môi trường.</p>
120
+ </div>
121
+ <div class="card">
122
+ <h3 id="theo-gia-tri">Theo giá trị</h3>
123
+ <p>Tên không nói gì thì giá trị vẫn được đọc riêng, nên <span class="inline-code">--env CONFIG=ghp_...</span> cũng bị bắt.</p>
124
+ </div>
125
+ </div>
126
+
127
+ <p>Áp dụng cho cả <span class="inline-code">--header</span>. <span class="inline-code">--url</span> chỉ nhận <span class="inline-code">https</span>, hoặc <span class="inline-code">http</span> khi host là loopback — Figma desktop MCP đúng là trường hợp đó. <span class="inline-code">list</span> và <span class="inline-code">get</span> mask giá trị nhưng in nguyên <span class="inline-code">${VAR}</span>, vì đó là tên biến chứ không phải nội dung.</p>
128
+ </section>
129
+
130
+ <section class="section">
131
+ <h2 id="trang-thai">Trạng thái sẵn sàng</h2>
132
+ <p>Đếm số server không nói được server nào trả lời được. <span class="inline-code">/piagent-mcp doctor</span> phân loại từng cái:</p>
133
+
134
+ <div class="table-wrap">
135
+ <table>
136
+ <thead>
137
+ <tr><th>State</th><th>Nghĩa</th><th>Cách xử lý</th></tr>
138
+ </thead>
139
+ <tbody>
140
+ <tr><td><span class="inline-code">ready</span></td><td>Đủ điều kiện, gọi được</td><td>—</td></tr>
141
+ <tr><td><span class="inline-code">needs-env</span></td><td>Config tham chiếu <span class="inline-code">${VAR}</span> mà biến chưa export</td><td>Export biến trong shell profile</td></tr>
142
+ <tr><td><span class="inline-code">needs-command</span></td><td>Executable không có trên PATH</td><td>Cài, hoặc sửa lại server</td></tr>
143
+ <tr><td><span class="inline-code">pending-approval</span></td><td>Repo khai server này, chưa ai duyệt trên máy này</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td></tr>
144
+ <tr><td><span class="inline-code">approval-changed</span></td><td>Đã duyệt nhưng định nghĩa đã đổi</td><td>Đọc lại rồi duyệt lại</td></tr>
145
+ <tr><td><span class="inline-code">rejected</span></td><td>Đã từ chối cho project này</td><td><span class="inline-code">reset</span> nếu đổi ý</td></tr>
146
+ <tr><td><span class="inline-code">disabled</span></td><td>Tắt bằng <span class="inline-code">disable</span></td><td><span class="inline-code">/piagent-mcp enable &lt;name&gt;</span></td></tr>
147
+ <tr><td><span class="inline-code">oauth</span></td><td>Đăng nhập do Pi giữ</td><td><span class="inline-code">/mcp-auth &lt;name&gt;</span> nếu chưa login</td></tr>
148
+ </tbody>
149
+ </table>
150
+ </div>
151
+
152
+ <p>Chỉ báo cái biết chắc. <span class="inline-code">needs-env</span> in ra <strong>tên biến</strong>, không bao giờ in giá trị.</p>
153
+
154
+ <p>Trong session là <span class="inline-code">/piagent-mcp doctor</span> — cùng báo cáo, và remedy in ra dạng slash command vì đó là thứ chạy được ngay tại chỗ. Ngoài terminal:</p>
155
+
156
+ <pre><code>$ piagent-mcp doctor
157
+ OK context7 (global): ready
158
+ OK chrome-devtools (global): ready
159
+ NEED github (global): GITHUB_PERSONAL_ACCESS_TOKEN is referenced but not set
160
+ -> export GITHUB_PERSONAL_ACCESS_TOKEN=... in your shell profile
161
+ NEED docker: installed but the daemon is not responding
162
+ -> start Docker Desktop, then re-run piagent-mcp doctor</code></pre>
163
+
164
+ <div class="callout">
165
+ <strong>Vì sao <span class="inline-code">oauth</span> không phải lỗi</strong>
166
+ <p>Nó không xuất hiện trong notice đầu session. Platform không phân biệt được đã login hay chưa, nên báo mỗi session sẽ thành nhiễu và hết được đọc. Notice chỉ nêu những state chặn chắc chắn; tắt bằng <span class="inline-code">PIAGENT_NO_MCP_NOTICE=1</span>.</p>
167
+ </div>
168
+
169
+ <p><span class="inline-code">doctor</span> chạy thêm <span class="inline-code">docker info</span> — chậm, nên chỉ có ở doctor chứ không ở session start. <span class="inline-code">piagent-doctor</span> cũng đưa các state chặn vào <span class="inline-code">warnings</span>.</p>
170
+ </section>
171
+ <nav class="pager" aria-label="Trang kế tiếp">
172
+ <a class="pager-prev" href="/mcp-servers">
173
+ <span class="pager-label">Trước</span>
174
+ <span class="pager-title">Quản lý server</span>
175
+ </a>
176
+ <a class="pager-next" href="/mcp-approval">
177
+ <span class="pager-label">Tiếp</span>
178
+ <span class="pager-title">Approval gate</span>
179
+ </a>
180
+ </nav>
181
+
182
+ <footer class="footer">
183
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
184
+ <div class="footer-links" aria-label="External links">
185
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
186
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
187
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
188
+ </div>
189
+ </footer>
190
+ </div>
191
+ </main>
192
+
193
+ <aside class="toc" aria-label="Mục lục trang">
194
+ <p class="toc-title">Trên trang này</p>
195
+ <nav data-toc></nav>
196
+ </aside>
197
+ </div>
198
+ </body>
199
+ </html>