clew-code 0.2.4 → 0.2.6

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 +264 -292
  2. package/dist/clew-dev.js +5118 -2840
  3. package/dist/main.js +2315 -2090
  4. package/docs/_config.yml +1 -1
  5. package/docs/architecture.html +145 -166
  6. package/docs/architecture.th.html +2 -23
  7. package/docs/commands.html +1 -22
  8. package/docs/commands.th.html +1 -22
  9. package/docs/configuration.html +145 -166
  10. package/docs/configuration.th.html +2 -23
  11. package/docs/css/styles.css +22 -0
  12. package/docs/daemon.html +128 -160
  13. package/docs/daemon.th.html +2 -30
  14. package/docs/features/bridge-mode.html +98 -98
  15. package/docs/features/bridge-mode.th.html +1 -1
  16. package/docs/features/evals.html +181 -181
  17. package/docs/features/evals.th.html +1 -1
  18. package/docs/features/searxng-search.html +150 -150
  19. package/docs/features/searxng-search.th.html +1 -1
  20. package/docs/features/sentry-setup.html +156 -156
  21. package/docs/features/sentry-setup.th.html +1 -1
  22. package/docs/index.html +298 -333
  23. package/docs/index.th.html +1 -36
  24. package/docs/installation.html +103 -124
  25. package/docs/installation.th.html +2 -23
  26. package/docs/internals/growthbook-ab-testing.html +112 -112
  27. package/docs/internals/growthbook-ab-testing.th.html +1 -1
  28. package/docs/internals/hidden-features.html +147 -147
  29. package/docs/internals/hidden-features.th.html +1 -1
  30. package/docs/js/main.js +78 -7
  31. package/docs/loop.html +180 -0
  32. package/docs/loop.th.html +226 -0
  33. package/docs/mcp.html +246 -157
  34. package/docs/mcp.th.html +156 -60
  35. package/docs/models.html +1 -22
  36. package/docs/models.th.html +1 -22
  37. package/docs/peer.html +235 -0
  38. package/docs/peer.th.html +279 -0
  39. package/docs/permission-model.html +101 -122
  40. package/docs/permission-model.th.html +2 -23
  41. package/docs/plugins.html +101 -122
  42. package/docs/plugins.th.html +2 -23
  43. package/docs/providers.html +117 -138
  44. package/docs/providers.th.html +2 -23
  45. package/docs/quick-start.html +92 -120
  46. package/docs/quick-start.th.html +1 -29
  47. package/docs/research-memory.html +79 -111
  48. package/docs/research-memory.th.html +2 -30
  49. package/docs/skills.html +116 -137
  50. package/docs/skills.th.html +2 -23
  51. package/docs/taste.html +96 -29
  52. package/docs/taste.th.html +193 -54
  53. package/docs/tools.html +169 -190
  54. package/docs/tools.th.html +2 -23
  55. package/docs/troubleshooting.html +105 -126
  56. package/docs/troubleshooting.th.html +2 -23
  57. package/package.json +5 -3
package/docs/mcp.html CHANGED
@@ -1,157 +1,246 @@
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</title>
7
- <meta name="description" content="Model Context Protocol (MCP) server management — connect external tools, resources, and services to Clew.">
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">
16
- <div class="header-inner">
17
- <a href="index.html" class="logo">
18
- <span>Clew Code</span>
19
- </a>
20
- <nav class="header-nav">
21
- <a href="index.html">Home</a>
22
- <a href="index.html#features">Features</a>
23
- <a href="index.html#commands">Commands</a>
24
- <a href="quick-start.html" class="active">Docs</a>
25
- <a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a>
26
- <div class="lang-wrap">
27
- <button class="lang-btn">🌐</button>
28
- <div class="lang-menu">
29
- <a href="../readme/README.zh.md">中文</a>
30
- <a href="../readme/README.th.md">ไทย</a>
31
- <a href="../readme/README.ja.md">日本語</a>
32
- <a href="../readme/README.ko.md">한국어</a>
33
- <a href="../readme/README.es.md">Español</a>
34
- <a href="../readme/README.fr.md">Français</a>
35
- <a href="../readme/README.de.md">Deutsch</a>
36
- <a href="../readme/README.pt.md">Português</a>
37
- <a href="../readme/README.vi.md">Tiếng Việt</a>
38
- <a href="../readme/README.id.md">Bahasa Indonesia</a>
39
- <a href="../readme/README.ru.md">Русский</a>
40
- <a href="../readme/README.hi.md">हिन्दी</a>
41
- <a href="../README.md">English</a>
42
- </div>
43
- </div>
44
- </nav>
45
- <button class="menu-btn" id="menuToggle" aria-label="Toggle navigation"><span></span><span></span><span></span></button>
46
- </div>
47
- </header>
48
- <div class="app">
49
- <aside class="sidebar" id="sidebar"></aside>
50
- <div class="sidebar-overlay" id="sidebarOverlay"></div>
51
- <div class="content-wrap">
52
- <main class="content">
53
- <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>MCP</span></div>
54
- <h1>Model Context Protocol (MCP)</h1>
55
- <p class="section-subtitle">Connect Clew to external tools, data sources, and services via the Model Context Protocol — an open standard for AI-application integration.</p>
56
-
57
- <p>MCP support is implemented in <code>src/services/mcp/</code>. Servers are discovered at startup and their tools, resources, and prompts are merged into Clew's runtime.</p>
58
-
59
- <h2>How It Works</h2>
60
- <pre><code> MCP Server Config (JSON or inline)
61
- |
62
- v
63
- + MCP Manager (src/services/mcp/)
64
- | Server connection lifecycle
65
- | Tool discovery via tools/list
66
- | Resource access via resources/read
67
- | Paginated responses
68
- |
69
- + Tool Pool (assembleToolPool)
70
- | MCP tools merged with built-in tools
71
- | Availability toggled by permission rules
72
- |
73
- + Query Loop
74
- Model sees MCP tools alongside built-ins
75
- Tool calls routed to the appropriate MCP server</code></pre>
76
-
77
- <h2>MCP Commands</h2>
78
- <table>
79
- <tr><th>Command</th><th>Description</th></tr>
80
- <tr><td><code>/mcp</code></td><td>Manage MCP servers — list, add, remove, view status</td></tr>
81
- </table>
82
-
83
- <h2>CLI Configuration</h2>
84
- <p>MCP servers are configured at startup via CLI flags:</p>
85
- <pre><code># Load servers from a JSON config file
86
- clew --mcp-config ./mcp-servers.json
87
-
88
- # Load multiple configs
89
- clew --mcp-config ./servers.json ./extra.json
90
-
91
- # Pass inline JSON
92
- clew --mcp-config '{"servers":{...}}'
93
-
94
- # Strict mode (only use MCP servers, no built-ins)
95
- clew --strict-mcp-config</code></pre>
96
-
97
- <h2>MCP Server Config Format</h2>
98
- <p>Each MCP server is defined with a command, arguments, and environment variables:</p>
99
- <pre><code>{
100
- "servers": {
101
- "filesystem": {
102
- "command": "npx",
103
- "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
104
- "env": {}
105
- },
106
- "database": {
107
- "command": "node",
108
- "args": ["./mcp/db-server.js"],
109
- "env": { "DB_URL": "postgresql://..." }
110
- }
111
- }
112
- }</code></pre>
113
-
114
- <h2>Tool Discovery</h2>
115
- <p>When an MCP server connects, Clew:</p>
116
- <ol>
117
- <li>Sends <code>tools/list</code> to discover available tools</li>
118
- <li>Merges discovered tools into the global tool pool via <code>assembleToolPool()</code></li>
119
- <li>Handles paginated responses for servers with many tools</li>
120
- <li>Makes tools available to the model alongside built-in tools</li>
121
- </ol>
122
-
123
- <p>MCP-provided tools inherit their schemas from the server and go through the same permission gating and hook system as built-in tools.</p>
124
-
125
- <h2>Resources</h2>
126
- <p>MCP servers can also expose resources — structured data that Clew can read:</p>
127
- <ul>
128
- <li><strong>ListMcpResources</strong> — List available resources from all connected servers</li>
129
- <li><strong>ReadMcpResource</strong> Read a specific resource by URI</li>
130
- </ul>
131
-
132
- <p>Resources are useful for accessing database schemas, API documentation, configuration files, and other structured data through MCP servers.</p>
133
-
134
- <h2>Plugin-Bundled MCP Servers</h2>
135
- <p>Plugins can declare MCP servers in their manifest. These are automatically started when the plugin is loaded and stopped when the plugin is unloaded. See <a href="plugins.html">Plugins</a> for details.</p>
136
-
137
- <h2>Architecture Files</h2>
138
- <table>
139
- <tr><th>Path</th><th>Role</th></tr>
140
- <tr><td><code>src/services/mcp/</code></td><td>MCP server connection management, tool discovery, resource access</td></tr>
141
- <tr><td><code>src/tools.ts</code></td><td>Tool registry — MCP tools merged via assembleToolPool()</td></tr>
142
- </table>
143
-
144
- <footer class="footer">
145
- <span>Clew v0.1.2 — Open Source</span>
146
- <div class="footer-links">
147
- <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
148
- <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
149
- </div>
150
- </footer>
151
- </main>
152
- <nav class="toc-sidebar"></nav>
153
- </div>
154
- </div>
155
- <script src="js/main.js"></script>
156
- </body>
157
- </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/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>