clew-code 0.2.6 → 0.2.8

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 (57) hide show
  1. package/README.md +292 -264
  2. package/dist/main.js +2835 -2950
  3. package/docs/architecture.html +148 -145
  4. package/docs/architecture.th.html +79 -78
  5. package/docs/clew-code-architecture.html +1125 -0
  6. package/docs/commands.html +224 -223
  7. package/docs/commands.th.html +131 -130
  8. package/docs/configuration.html +147 -145
  9. package/docs/configuration.th.html +108 -106
  10. package/docs/css/styles.css +48 -42
  11. package/docs/daemon.html +129 -128
  12. package/docs/daemon.th.html +73 -72
  13. package/docs/features/bridge-mode.html +99 -98
  14. package/docs/features/bridge-mode.th.html +90 -89
  15. package/docs/features/evals.html +182 -181
  16. package/docs/features/evals.th.html +90 -89
  17. package/docs/features/peer.html +178 -177
  18. package/docs/features/searxng-search.html +151 -150
  19. package/docs/features/searxng-search.th.html +95 -94
  20. package/docs/features/sentry-setup.html +157 -156
  21. package/docs/features/sentry-setup.th.html +97 -96
  22. package/docs/index.html +299 -298
  23. package/docs/index.th.html +292 -290
  24. package/docs/installation.html +105 -103
  25. package/docs/installation.th.html +105 -103
  26. package/docs/internals/growthbook-ab-testing.html +113 -112
  27. package/docs/internals/growthbook-ab-testing.th.html +81 -80
  28. package/docs/internals/hidden-features.html +149 -147
  29. package/docs/internals/hidden-features.th.html +109 -107
  30. package/docs/js/main.js +83 -3
  31. package/docs/loop.html +181 -180
  32. package/docs/loop.th.html +227 -226
  33. package/docs/mcp.html +247 -246
  34. package/docs/mcp.th.html +207 -206
  35. package/docs/models.html +111 -110
  36. package/docs/models.th.html +61 -60
  37. package/docs/peer.html +236 -235
  38. package/docs/peer.th.html +280 -279
  39. package/docs/permission-model.html +102 -101
  40. package/docs/permission-model.th.html +67 -66
  41. package/docs/plugins.html +102 -101
  42. package/docs/plugins.th.html +79 -78
  43. package/docs/providers.html +126 -117
  44. package/docs/providers.th.html +80 -78
  45. package/docs/quick-start.html +93 -92
  46. package/docs/quick-start.th.html +40 -39
  47. package/docs/research-memory.html +82 -79
  48. package/docs/research-memory.th.html +72 -71
  49. package/docs/skills.html +117 -116
  50. package/docs/skills.th.html +90 -89
  51. package/docs/tools.html +170 -169
  52. package/docs/tools.th.html +84 -83
  53. package/docs/troubleshooting.html +106 -105
  54. package/docs/troubleshooting.th.html +85 -84
  55. package/package.json +3 -1
  56. package/docs/taste.html +0 -436
  57. package/docs/taste.th.html +0 -236
package/docs/mcp.html CHANGED
@@ -1,246 +1,247 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>MCP — Clew Code</title>
7
- <meta name="description" content="Model Context Protocol (MCP) support — connect external tools, resources, and services with stdio, SSE, and OAuth authentication.">
8
- <link rel="preconnect" href="https://fonts.googleapis.com">
9
- <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
- <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
- <link rel="stylesheet" href="css/styles.css">
12
- <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
- </head>
14
- <body>
15
- <header class="header"></header>
16
- <div class="app">
17
- <aside class="sidebar" id="sidebar"></aside>
18
- <div class="sidebar-overlay" id="sidebarOverlay"></div>
19
- <div class="content-wrap">
20
- <main class="content">
21
- <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>MCP</span></div>
22
- <h1>Model Context Protocol (MCP)</h1>
23
- <p class="section-subtitle">Connect Clew to external tools, data sources, and services via the Model Context Protocol — the open standard for AI-tool integration.</p>
24
-
25
- <p>MCP support lives in <code>src/services/mcp/</code>. Clew discovers MCP servers from <strong>settings.json</strong>, <strong>CLI flags</strong>, and <strong>plugin manifests</strong>, then merges their tools into the runtime at startup and via <code>/mcp</code> at runtime.</p>
26
-
27
- <h2>Architecture</h2>
28
- <pre><code> ┌──────────────────────────────────────────────────────────────────────────┐
29
- │ MCP — MODEL CONTEXT PROTOCOL │
30
- └──────────────────────────────────────────────────────────────────────────┘
31
-
32
- ┌──────────────────────────┐
33
- │ Settings / CLI Config │
34
- │ src/services/mcp/config │
35
- │ (servers.json schema) │
36
- └────────────┬─────────────┘
37
- │
38
- ▼
39
- ┌──────────────────────────┐
40
- │ MCPConnectionManager │
41
- │ src/services/mcp/ │
42
- │ MCPConnectionManager.tsx │
43
- └────────────┬─────────────┘
44
- │
45
- ┌───────────────────┼───────────────────┐
46
- ▼ ▼ ▼
47
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
48
- │ Stdio MCP │ │ SSE MCP │ │Direct Connect│
49
- │ (subprocess) │ │ (remote) │ │ (in-process) │
50
- │ npx/node/etc │ │ WebSocket │ │ │
51
- └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
52
- │ │ │
53
- └──────────────────┼───────────────────┘
54
- │
55
- ▼
56
- ┌──────────────────────┐
57
- │ Client (JSON-RPC) │
58
- │ tools/list │
59
- │ resources/list │
60
- │ prompts/list │
61
- │ tools/call │
62
- │ resources/read │
63
- └──────────┬───────────┘
64
- │
65
- ▼
66
- ┌──────────────────────┐
67
- │ assembleToolPool │
68
- │ (MCP tools + built- │
69
- │ in tools merged) │
70
- └──────────┬───────────┘
71
- │
72
- ▼
73
- ┌──────────────────────┐
74
- │ Query Engine │
75
- │ Model sees all tools│
76
- │ Tool calls routed │
77
- │ to correct server │
78
- └──────────────────────┘
79
-
80
-
81
- ═══ MCP SERVER TYPES ═══
82
-
83
- ┌─────────────────────────────────────────────────────────────────────┐
84
- │ Type │ Transport │ Auth │ Use Case │
85
- ├─────────────┼─────────────┼─────────────┼───────────────────────────┤
86
- │ Stdio │ stdin/stdout│ None │ Local tools (npx, node) │
87
- │ SSE │ HTTP+SSE │ OAuth/Token │ Remote services │
88
- │ Direct │ In-process │ Internal │ Plugin-bundled servers │
89
- └─────────────────────────────────────────────────────────────────────┘</code></pre>
90
-
91
- <h2>How It Works</h2>
92
-
93
- <h3>Server Discovery</h3>
94
- <p>MCP servers are found from <strong>three sources</strong> at startup:</p>
95
- <ol>
96
- <li><strong><code>settings.json</code></strong> — <code>mcpServers</code> key with server definitions (command, args, env)</li>
97
- <li><strong>CLI <code>--mcp-config</code></strong> — JSON file or inline JSON with server definitions</li>
98
- <li><strong>Plugins</strong> — plugin manifests can declare MCP servers; started when plugin loads, stopped when unloaded</li>
99
- </ol>
100
- <p>At runtime, <code>/mcp</code> command can add, remove, or reconnect servers dynamically.</p>
101
-
102
- <h3>Server Connection Types</h3>
103
- <div class="table-wrap">
104
- <table>
105
- <tr><th>Type</th><th>Protocol</th><th>How It Works</th></tr>
106
- <tr>
107
- <td><strong>Stdio</strong></td>
108
- <td>JSON-RPC over stdin/stdout</td>
109
- <td>Clew spawns a subprocess (e.g. <code>npx @modelcontextprotocol/server-filesystem</code>) and communicates via its stdin/stdout streams. The subprocess advertises its capabilities via <code>tools/list</code> and handles <code>tools/call</code> requests.</td>
110
- </tr>
111
- <tr>
112
- <td><strong>SSE</strong></td>
113
- <td>HTTP + Server-Sent Events</td>
114
- <td>Connects to remote MCP servers over HTTP. Uses SSE for server-to-client messages (tool results, resource updates) and HTTP POST for client-to-server requests. Supports OAuth authentication.</td>
115
- </tr>
116
- <tr>
117
- <td><strong>Direct Connect</strong></td>
118
- <td>In-process</td>
119
- <td>Runs an MCP server in the same process via an in-process transport pair. Used by internal subsystems and plugin-bundled servers. No network overhead, no subprocess spawning.</td>
120
- </tr>
121
- </tbody>
122
- </table>
123
-
124
- <h3>Tool Lifecycle</h3>
125
- <pre><code> ┌─────────────────────────────────────────────────────────────────┐
126
- │ MCP TOOL LIFECYCLE │
127
- └─────────────────────────────────────────────────────────────────┘
128
-
129
- 1. CONNECT ──► MCPConnectionManager connects to server
130
- │
131
- ▼
132
- 2. DISCOVER ──► Clew calls tools/list (paginated)
133
- │
134
- ▼
135
- 3. MERGE ──► assembleToolPool() merges MCP tools with
136
- built-in tools (sorted by name, deduplicated)
137
- │
138
- ▼
139
- 4. PRESENT ──► Model sees MCP tools as native tools
140
- │ (with permission gating, hooks, logging)
141
- ▼
142
- 5. EXECUTE ──► Model calls tool → toolExecution.ts
143
- │ routes to correct MCP server
144
- │ mapToolResultToToolResultBlockParam
145
- ▼
146
- 6. RESPOND ──► Result returned to model</code></pre>
147
-
148
- <h3>Authentication</h3>
149
- <p>MCP supports multiple auth flows defined in <code>src/services/mcp/auth.ts</code> and <code>src/services/mcp/oauthPort.ts</code>:</p>
150
- <ul>
151
- <li><strong>OAuth 2.0</strong> — redirect-based flow for remote MCP servers. Opens a local HTTP port to receive the callback.</li>
152
- <li><strong>Bearer token</strong> — static API token in the <code>Authorization</code> header</li>
153
- <li><strong>XAA token</strong> — Claude-specific auth provider token, handled in <code>src/services/mcp/xaa.ts</code></li>
154
- <li><strong>Credential vault</strong> — stored credentials injected via <code>credential_item_ids</code></li>
155
- </ul>
156
-
157
- <h2>MCP Commands</h2>
158
- <table>
159
- <tr><th>Command</th><th>Description</th></tr>
160
- <tr><td><code>/mcp</code></td><td>Open interactive MCP management menu — list servers, add, remove, reconnect</td></tr>
161
- <tr><td><code>/mcp list</code></td><td>List all connected MCP servers with their tools, resources, and prompts</td></tr>
162
- <tr><td><code>/mcp add &lt;name&gt; &lt;command&gt; [args...]</code></td><td>Add a new stdio MCP server</td></tr>
163
- <tr><td><code>/mcp remove &lt;name&gt;</code></td><td>Remove a connected MCP server</td></tr>
164
- <tr><td><code>/mcp reconnect &lt;name&gt;</code></td><td>Reconnect a disconnected MCP server</td></tr>
165
- </table>
166
-
167
- <h2>Server Config Format (settings.json)</h2>
168
- <div class="code-block-wrap">
169
- <div class="code-block-header"><span>json</span></div>
170
- <pre><code>{
171
- "mcpServers": {
172
- "filesystem": {
173
- "command": "npx",
174
- "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
175
- "env": {}
176
- },
177
- "database": {
178
- "command": "node",
179
- "args": ["./mcp/db-server.js"],
180
- "env": {
181
- "DB_URL": "postgresql://localhost:5432/mydb"
182
- }
183
- },
184
- "remote-api": {
185
- "url": "https://mcp.example.com",
186
- "headers": {
187
- "Authorization": "Bearer sk-..."
188
- }
189
- }
190
- }
191
- }</code></pre>
192
- </div>
193
-
194
- <h2>Plugin-Bundled MCP Servers</h2>
195
- <p>Plugins can declare MCP servers in their manifest. When a plugin loads, Clew creates a <strong>DirectConnect</strong> session internally — no subprocess, no network. The MCP server's tools become available as soon as the plugin registers. When the plugin is unloaded, the server is stopped.</p>
196
- <p>See <a href="plugins.html">Plugins</a> for details on plugin development.</p>
197
-
198
- <h2>Tool Pool Integration</h2>
199
- <p>MCP tools are merged with built-in tools via <code>assembleToolPool()</code> in <code>src/tools.ts</code>:</p>
200
- <ul>
201
- <li>Both lists are sorted alphabetically, then concatenated, then deduplicated by name (<code>uniqBy('name')</code>)</li>
202
- <li>Built-in tools take precedence when names collide</li>
203
- <li>MCP tools go through the same permission gating and hook pipeline</li>
204
- <li>Results are formatted via <code>mapToolResultToToolResultBlockParam</code> just like built-in tools</li>
205
- </ul>
206
-
207
- <h2>Integration with Built-in Tools</h2>
208
- <p>Several built-in tools use MCP under the hood:</p>
209
- <table>
210
- <tr><th>Tool</th><th>MCP Used For</th></tr>
211
- <tr><td><code>ListMcpResources</code></td><td>Lists resources from all connected MCP servers (resources/list)</td></tr>
212
- <tr><td><code>ReadMcpResource</code></td><td>Reads a specific resource by URI from an MCP server (resources/read)</td></tr>
213
- </table>
214
-
215
- <h2>Architecture Files</h2>
216
- <table>
217
- <tr><th>Path</th><th>Role</th></tr>
218
- <tr><td><code>src/services/mcp/MCPConnectionManager.tsx</code></td><td>Server lifecycle manager — connect, reconnect, disconnect, list servers</td></tr>
219
- <tr><td><code>src/services/mcp/config.ts</code></td><td>MCP server config loading from settings.json and CLI flags</td></tr>
220
- <tr><td><code>src/services/mcp/client.ts</code></td><td>JSON-RPC client — sends requests, receives responses and notifications</td></tr>
221
- <tr><td><code>src/services/mcp/auth.ts</code></td><td>OAuth and bearer token authentication flow</td></tr>
222
- <tr><td><code>src/services/mcp/oauthPort.ts</code></td><td>Local HTTP server for OAuth callback handling</td></tr>
223
- <tr><td><code>src/services/mcp/types.ts</code></td><td>MCP type definitions and protocol constants</td></tr>
224
- <tr><td><code>src/services/mcp/InProcessTransport.ts</code></td><td>In-process linked transport pair for DirectConnect mode</td></tr>
225
- <tr><td><code>src/services/mcp/SdkControlTransport.ts</code></td><td>SDK-level transport for programmatic control</td></tr>
226
- <tr><td><code>src/services/mcp/normalization.ts</code></td><td>Tool name normalization between MCP and internal formats</td></tr>
227
- <tr><td><code>src/services/mcp/envExpansion.ts</code></td><td>Environment variable expansion in server config</td></tr>
228
- <tr><td><code>src/services/mcp/officialRegistry.ts</code></td><td>Official MCP server registry lookup</td></tr>
229
- <tr><td><code>src/services/mcp/xaa.ts</code></td><td>XAA auth token integration for Claude-specific servers</td></tr>
230
- <tr><td><code>src/tools.ts</code></td><td>Tool registry — assembleToolPool merges MCP tools</td></tr>
231
- </table>
232
-
233
- <footer class="footer">
234
- <span>Clew Code — Open Source</span>
235
- <div class="footer-links">
236
- <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
237
- <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
238
- </div>
239
- </footer>
240
- </main>
241
- <nav class="toc-sidebar"></nav>
242
- </div>
243
- </div>
244
- <script src="js/main.js"></script>
245
- </body>
246
- </html>
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>MCP — Clew Code</title>
7
+ <meta name="description" content="Model Context Protocol (MCP) support — connect external tools, resources, and services with stdio, SSE, and OAuth authentication.">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
+ <link rel="stylesheet" href="css/styles.css">
12
+ <link rel="icon" type="image/svg+xml" href="./assets/clew.svg">
13
+ </head>
14
+ <body>
15
+ <header class="header"></header>
16
+ <div class="app">
17
+ <aside class="sidebar" id="sidebar"></aside>
18
+ <div class="sidebar-overlay" id="sidebarOverlay"></div>
19
+ <div class="content-wrap">
20
+ <main class="content">
21
+ <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>MCP</span></div>
22
+ <h1>Model Context Protocol (MCP)</h1>
23
+ <p class="section-subtitle">Connect Clew to external tools, data sources, and services via the Model Context Protocol — the open standard for AI-tool integration.</p>
24
+
25
+ <p>MCP support lives in <code>src/services/mcp/</code>. Clew discovers MCP servers from <strong>settings.json</strong>, <strong>CLI flags</strong>, and <strong>plugin manifests</strong>, then merges their tools into the runtime at startup and via <code>/mcp</code> at runtime.</p>
26
+
27
+ <h2>Architecture</h2>
28
+ <pre><code> ┌──────────────────────────────────────────────────────────────────────────┐
29
+ │ MCP — MODEL CONTEXT PROTOCOL │
30
+ └──────────────────────────────────────────────────────────────────────────┘
31
+
32
+ ┌──────────────────────────┐
33
+ │ Settings / CLI Config │
34
+ │ src/services/mcp/config │
35
+ │ (servers.json schema) │
36
+ └────────────┬─────────────┘
37
+ │
38
+ â–¼
39
+ ┌──────────────────────────┐
40
+ │ MCPConnectionManager │
41
+ │ src/services/mcp/ │
42
+ │ MCPConnectionManager.tsx │
43
+ └────────────┬─────────────┘
44
+ │
45
+ ┌───────────────────┼───────────────────┐
46
+ â–¼ â–¼ â–¼
47
+ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
48
+ │ Stdio MCP │ │ SSE MCP │ │Direct Connect│
49
+ │ (subprocess) │ │ (remote) │ │ (in-process) │
50
+ │ npx/node/etc │ │ WebSocket │ │ │
51
+ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
52
+ │ │ │
53
+ └──────────────────┼───────────────────┘
54
+ │
55
+ â–¼
56
+ ┌──────────────────────┐
57
+ │ Client (JSON-RPC) │
58
+ │ tools/list │
59
+ │ resources/list │
60
+ │ prompts/list │
61
+ │ tools/call │
62
+ │ resources/read │
63
+ └──────────┬───────────┘
64
+ │
65
+ â–¼
66
+ ┌──────────────────────┐
67
+ │ assembleToolPool │
68
+ │ (MCP tools + built- │
69
+ │ in tools merged) │
70
+ └──────────┬───────────┘
71
+ │
72
+ â–¼
73
+ ┌──────────────────────┐
74
+ │ Query Engine │
75
+ │ Model sees all tools│
76
+ │ Tool calls routed │
77
+ │ to correct server │
78
+ └──────────────────────┘
79
+
80
+
81
+ ═══ MCP SERVER TYPES ═══
82
+
83
+ ┌─────────────────────────────────────────────────────────────────────┐
84
+ │ Type │ Transport │ Auth │ Use Case │
85
+ ├─────────────┼─────────────┼─────────────┼───────────────────────────┤
86
+ │ Stdio │ stdin/stdout│ None │ Local tools (npx, node) │
87
+ │ SSE │ HTTP+SSE │ OAuth/Token │ Remote services │
88
+ │ Direct │ In-process │ Internal │ Plugin-bundled servers │
89
+ └─────────────────────────────────────────────────────────────────────┘</code></pre>
90
+
91
+ <h2>How It Works</h2>
92
+
93
+ <h3>Server Discovery</h3>
94
+ <p>MCP servers are found from <strong>three sources</strong> at startup:</p>
95
+ <ol>
96
+ <li><strong><code>settings.json</code></strong> — <code>mcpServers</code> key with server definitions (command, args, env)</li>
97
+ <li><strong>CLI <code>--mcp-config</code></strong> — JSON file or inline JSON with server definitions</li>
98
+ <li><strong>Plugins</strong> — plugin manifests can declare MCP servers; started when plugin loads, stopped when unloaded</li>
99
+ </ol>
100
+ <p>At runtime, <code>/mcp</code> command can add, remove, or reconnect servers dynamically.</p>
101
+
102
+ <h3>Server Connection Types</h3>
103
+ <div class="table-wrap">
104
+ <table>
105
+ <tr><th>Type</th><th>Protocol</th><th>How It Works</th></tr>
106
+ <tr>
107
+ <td><strong>Stdio</strong></td>
108
+ <td>JSON-RPC over stdin/stdout</td>
109
+ <td>Clew spawns a subprocess (e.g. <code>npx @modelcontextprotocol/server-filesystem</code>) and communicates via its stdin/stdout streams. The subprocess advertises its capabilities via <code>tools/list</code> and handles <code>tools/call</code> requests.</td>
110
+ </tr>
111
+ <tr>
112
+ <td><strong>SSE</strong></td>
113
+ <td>HTTP + Server-Sent Events</td>
114
+ <td>Connects to remote MCP servers over HTTP. Uses SSE for server-to-client messages (tool results, resource updates) and HTTP POST for client-to-server requests. Supports OAuth authentication.</td>
115
+ </tr>
116
+ <tr>
117
+ <td><strong>Direct Connect</strong></td>
118
+ <td>In-process</td>
119
+ <td>Runs an MCP server in the same process via an in-process transport pair. Used by internal subsystems and plugin-bundled servers. No network overhead, no subprocess spawning.</td>
120
+ </tr>
121
+ </tbody>
122
+ </table>
123
+
124
+ <h3>Tool Lifecycle</h3>
125
+ <pre><code> ┌─────────────────────────────────────────────────────────────────┐
126
+ │ MCP TOOL LIFECYCLE │
127
+ └─────────────────────────────────────────────────────────────────┘
128
+
129
+ 1. CONNECT ──► MCPConnectionManager connects to server
130
+ │
131
+ â–¼
132
+ 2. DISCOVER ──► Clew calls tools/list (paginated)
133
+ │
134
+ â–¼
135
+ 3. MERGE ──► assembleToolPool() merges MCP tools with
136
+ built-in tools (sorted by name, deduplicated)
137
+ │
138
+ â–¼
139
+ 4. PRESENT ──► Model sees MCP tools as native tools
140
+ │ (with permission gating, hooks, logging)
141
+ â–¼
142
+ 5. EXECUTE ──► Model calls tool → toolExecution.ts
143
+ │ routes to correct MCP server
144
+ │ mapToolResultToToolResultBlockParam
145
+ â–¼
146
+ 6. RESPOND ──► Result returned to model</code></pre>
147
+
148
+ <h3>Authentication</h3>
149
+ <p>MCP supports multiple auth flows defined in <code>src/services/mcp/auth.ts</code> and <code>src/services/mcp/oauthPort.ts</code>:</p>
150
+ <ul>
151
+ <li><strong>OAuth 2.0</strong> — redirect-based flow for remote MCP servers. Opens a local HTTP port to receive the callback.</li>
152
+ <li><strong>Bearer token</strong> — static API token in the <code>Authorization</code> header</li>
153
+ <li><strong>XAA token</strong> — Claude-specific auth provider token, handled in <code>src/services/mcp/xaa.ts</code></li>
154
+ <li><strong>Credential vault</strong> — stored credentials injected via <code>credential_item_ids</code></li>
155
+ </ul>
156
+
157
+ <h2>MCP Commands</h2>
158
+ <table>
159
+ <tr><th>Command</th><th>Description</th></tr>
160
+ <tr><td><code>/mcp</code></td><td>Open interactive MCP management menu — list servers, add, remove, reconnect</td></tr>
161
+ <tr><td><code>/mcp list</code></td><td>List all connected MCP servers with their tools, resources, and prompts</td></tr>
162
+ <tr><td><code>/mcp add &lt;name&gt; &lt;command&gt; [args...]</code></td><td>Add a new stdio MCP server</td></tr>
163
+ <tr><td><code>/mcp remove &lt;name&gt;</code></td><td>Remove a connected MCP server</td></tr>
164
+ <tr><td><code>/mcp reconnect &lt;name&gt;</code></td><td>Reconnect a disconnected MCP server</td></tr>
165
+ </table>
166
+
167
+ <h2>Server Config Format (settings.json)</h2>
168
+ <div class="code-block-wrap">
169
+ <div class="code-block-header"><span>json</span></div>
170
+ <pre><code>{
171
+ "mcpServers": {
172
+ "filesystem": {
173
+ "command": "npx",
174
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
175
+ "env": {}
176
+ },
177
+ "database": {
178
+ "command": "node",
179
+ "args": ["./mcp/db-server.js"],
180
+ "env": {
181
+ "DB_URL": "postgresql://localhost:5432/mydb"
182
+ }
183
+ },
184
+ "remote-api": {
185
+ "url": "https://mcp.example.com",
186
+ "headers": {
187
+ "Authorization": "Bearer sk-..."
188
+ }
189
+ }
190
+ }
191
+ }</code></pre>
192
+ </div>
193
+
194
+ <h2>Plugin-Bundled MCP Servers</h2>
195
+ <p>Plugins can declare MCP servers in their manifest. When a plugin loads, Clew creates a <strong>DirectConnect</strong> session internally — no subprocess, no network. The MCP server's tools become available as soon as the plugin registers. When the plugin is unloaded, the server is stopped.</p>
196
+ <p>See <a href="plugins.html">Plugins</a> for details on plugin development.</p>
197
+
198
+ <h2>Tool Pool Integration</h2>
199
+ <p>MCP tools are merged with built-in tools via <code>assembleToolPool()</code> in <code>src/tools.ts</code>:</p>
200
+ <ul>
201
+ <li>Both lists are sorted alphabetically, then concatenated, then deduplicated by name (<code>uniqBy('name')</code>)</li>
202
+ <li>Built-in tools take precedence when names collide</li>
203
+ <li>MCP tools go through the same permission gating and hook pipeline</li>
204
+ <li>Results are formatted via <code>mapToolResultToToolResultBlockParam</code> just like built-in tools</li>
205
+ </ul>
206
+
207
+ <h2>Integration with Built-in Tools</h2>
208
+ <p>Several built-in tools use MCP under the hood:</p>
209
+ <table>
210
+ <tr><th>Tool</th><th>MCP Used For</th></tr>
211
+ <tr><td><code>ListMcpResources</code></td><td>Lists resources from all connected MCP servers (resources/list)</td></tr>
212
+ <tr><td><code>ReadMcpResource</code></td><td>Reads a specific resource by URI from an MCP server (resources/read)</td></tr>
213
+ </table>
214
+
215
+ <h2>Architecture Files</h2>
216
+ <table>
217
+ <tr><th>Path</th><th>Role</th></tr>
218
+ <tr><td><code>src/services/mcp/MCPConnectionManager.tsx</code></td><td>Server lifecycle manager — connect, reconnect, disconnect, list servers</td></tr>
219
+ <tr><td><code>src/services/mcp/config.ts</code></td><td>MCP server config loading from settings.json and CLI flags</td></tr>
220
+ <tr><td><code>src/services/mcp/client.ts</code></td><td>JSON-RPC client — sends requests, receives responses and notifications</td></tr>
221
+ <tr><td><code>src/services/mcp/auth.ts</code></td><td>OAuth and bearer token authentication flow</td></tr>
222
+ <tr><td><code>src/services/mcp/oauthPort.ts</code></td><td>Local HTTP server for OAuth callback handling</td></tr>
223
+ <tr><td><code>src/services/mcp/types.ts</code></td><td>MCP type definitions and protocol constants</td></tr>
224
+ <tr><td><code>src/services/mcp/InProcessTransport.ts</code></td><td>In-process linked transport pair for DirectConnect mode</td></tr>
225
+ <tr><td><code>src/services/mcp/SdkControlTransport.ts</code></td><td>SDK-level transport for programmatic control</td></tr>
226
+ <tr><td><code>src/services/mcp/normalization.ts</code></td><td>Tool name normalization between MCP and internal formats</td></tr>
227
+ <tr><td><code>src/services/mcp/envExpansion.ts</code></td><td>Environment variable expansion in server config</td></tr>
228
+ <tr><td><code>src/services/mcp/officialRegistry.ts</code></td><td>Official MCP server registry lookup</td></tr>
229
+ <tr><td><code>src/services/mcp/xaa.ts</code></td><td>XAA auth token integration for Claude-specific servers</td></tr>
230
+ <tr><td><code>src/tools.ts</code></td><td>Tool registry — assembleToolPool merges MCP tools</td></tr>
231
+ </table>
232
+
233
+ <footer class="footer">
234
+ <span>Clew Code — Open Source</span>
235
+ <div class="footer-links">
236
+ <a href="https://github.com/ClewCode/ClewCode">GitHub</a>
237
+ <a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
238
+ </div>
239
+ </footer>
240
+ </main>
241
+ <nav class="toc-sidebar"></nav>
242
+ </div>
243
+ </div>
244
+ <script src="js/main.js"></script>
245
+ </body>
246
+ </html>
247
+