clew-code 0.2.21 → 0.2.23
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.
- package/README.md +45 -45
- package/dist/main.js +2906 -2722
- package/docs/architecture.html +91 -148
- package/docs/assets/clew-agent-loop.png +0 -0
- package/docs/assets/clew-general-architecture.png +0 -0
- package/docs/assets/clew-mcp-architecture.png +0 -0
- package/docs/assets/clew-p2p-swarm.png +0 -0
- package/docs/changelog.html +150 -0
- package/docs/cli-reference.html +90 -0
- package/docs/commands.html +133 -241
- package/docs/configuration.html +85 -147
- package/docs/contributing.html +91 -0
- package/docs/css/styles.css +272 -152
- package/docs/daemon.html +62 -129
- package/docs/features/bridge-mode.html +61 -66
- package/docs/features/evals.html +57 -149
- package/docs/features/searxng-search.html +58 -118
- package/docs/features/sentry-setup.html +61 -124
- package/docs/index.html +185 -148
- package/docs/installation.html +77 -105
- package/docs/internals/growthbook-ab-testing.html +69 -91
- package/docs/internals/hidden-features.html +81 -143
- package/docs/js/main.js +29 -0
- package/docs/loop.html +69 -181
- package/docs/mcp.html +99 -247
- package/docs/models.html +63 -92
- package/docs/permission-model.html +86 -102
- package/docs/plugins.html +84 -102
- package/docs/providers.html +87 -127
- package/docs/quick-start.html +81 -93
- package/docs/research-memory.html +71 -102
- package/docs/security.html +71 -0
- package/docs/skills.html +67 -117
- package/docs/swarm.html +78 -236
- package/docs/tools.html +183 -171
- package/docs/troubleshooting.html +86 -106
- package/docs/voice-mode.html +79 -0
- package/package.json +1 -1
- package/docs/architecture.th.html +0 -79
- package/docs/clew-code-architecture.html +0 -1126
- package/docs/commands.th.html +0 -269
- package/docs/configuration.th.html +0 -108
- package/docs/daemon.th.html +0 -73
- package/docs/features/bridge-mode.th.html +0 -62
- package/docs/features/evals.th.html +0 -62
- package/docs/features/searxng-search.th.html +0 -67
- package/docs/features/sentry-setup.th.html +0 -69
- package/docs/features/swarm.html +0 -156
- package/docs/generated/providers.html +0 -625
- package/docs/generated/tools.html +0 -558
- package/docs/index.th.html +0 -292
- package/docs/installation.th.html +0 -105
- package/docs/internals/growthbook-ab-testing.th.html +0 -60
- package/docs/internals/hidden-features.th.html +0 -107
- package/docs/loop.th.html +0 -227
- package/docs/mcp.th.html +0 -207
- package/docs/models.th.html +0 -61
- package/docs/permission-model.th.html +0 -67
- package/docs/plugins.th.html +0 -79
- package/docs/prompts-and-features.html +0 -806
- package/docs/providers.th.html +0 -81
- package/docs/quick-start.th.html +0 -89
- package/docs/research-memory.th.html +0 -72
- package/docs/skills.th.html +0 -90
- package/docs/swarm.th.html +0 -280
- package/docs/tools.th.html +0 -84
- package/docs/troubleshooting.th.html +0 -85
package/docs/loop.html
CHANGED
|
@@ -1,181 +1,69 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
<head>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
<
|
|
15
|
-
<
|
|
16
|
-
<
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
│ [timeout 30m] → stopWorker │ │
|
|
71
|
-
│ → releaseLease│ │
|
|
72
|
-
│ → retryTask() │ │</code></pre>
|
|
73
|
-
|
|
74
|
-
<h3>Retry with Exponential Backoff</h3>
|
|
75
|
-
<pre><code>Retry attempt Backoff delay Cumulative wait
|
|
76
|
-
───────────── ───────────── ──────────────
|
|
77
|
-
1 base × 2¹ = 30s 30s
|
|
78
|
-
2 base × 2² = 60s 90s
|
|
79
|
-
3 base × 2³ = 120s 210s
|
|
80
|
-
4 base × 2⁴ = 240s 450s
|
|
81
|
-
5 (max) base × 2⁵ = 480s 930s (~15 min)
|
|
82
|
-
|
|
83
|
-
After max retries → dead_letter queue
|
|
84
|
-
Dead-letter preserves: title, description, lastError, errorLog, retryCount</code></pre>
|
|
85
|
-
<ul>
|
|
86
|
-
<li><strong>Exponential backoff</strong> — base = 15s, factor = 2</li>
|
|
87
|
-
<li><strong>Max retries</strong> — 5 per task (default)</li>
|
|
88
|
-
<li><strong>Dead-letter queue</strong> — exhausted tasks are moved to <code>dead_letter</code> status with reason + error log</li>
|
|
89
|
-
</ul>
|
|
90
|
-
|
|
91
|
-
<h3>Worker Lifecycle + Concurrent Cap</h3>
|
|
92
|
-
<ul>
|
|
93
|
-
<li><strong>MAX_CONCURRENT_WORKERS = 3</strong> — prevents resource exhaustion</li>
|
|
94
|
-
<li><strong>Worker timeout = 30 min</strong> — long-running tasks are killed to free resources</li>
|
|
95
|
-
<li><strong>Worker poll = 10s</strong> — status checks via supervisor IPC</li>
|
|
96
|
-
<li><strong>Loop sleep = 5s</strong> — idle interval when no tasks or workers full</li>
|
|
97
|
-
</ul>
|
|
98
|
-
|
|
99
|
-
<h3>Supervisor Integration</h3>
|
|
100
|
-
<p>Workers are spawned through a <strong>Supervisor process</strong> (child_process) for crash isolation:</p>
|
|
101
|
-
<ul>
|
|
102
|
-
<li><strong>Crash isolation</strong> — worker crash doesn't crash the loop</li>
|
|
103
|
-
<li><strong>Output capture</strong> — stdout/stderr saved to <code>~/.clew/daemon/jobs/{sessionId}/output.log</code></li>
|
|
104
|
-
<li><strong>Health via IPC</strong> — loop checks status through supervisor, not raw PID (avoids PID reuse bugs)</li>
|
|
105
|
-
</ul>
|
|
106
|
-
|
|
107
|
-
<h3>Integration Points</h3>
|
|
108
|
-
<ul>
|
|
109
|
-
<li><strong>Peer todo listener</strong> — receives tasks from remote peers via <code>/peer-todo</code> HTTP endpoint → adds to queue</li>
|
|
110
|
-
<li><strong>Cron scheduler</strong> — fires scheduled tasks → adds to queue</li>
|
|
111
|
-
<li><strong>File watcher</strong> — <code>fs.watch</code> on queue file detects new tasks from other processes (e.g. CLI <code>/task add</code>)</li>
|
|
112
|
-
</ul>
|
|
113
|
-
|
|
114
|
-
<h3>Crash Recovery</h3>
|
|
115
|
-
<pre><code>Previous Run Crash
|
|
116
|
-
│
|
|
117
|
-
▼
|
|
118
|
-
startLoop() called
|
|
119
|
-
│
|
|
120
|
-
├── loadQueue() — restore queue from disk
|
|
121
|
-
├── sleep(2000ms) — ensure old process is dead
|
|
122
|
-
├── expireLeases() — clear all stale leases
|
|
123
|
-
├── start heartbeat (every 60s)
|
|
124
|
-
├── start cron scheduler
|
|
125
|
-
├── start peer sharing
|
|
126
|
-
├── start file watcher
|
|
127
|
-
└── MAIN LOOP ──► getNextTask() → processTask() → loop</code></pre>
|
|
128
|
-
|
|
129
|
-
<h2>Task Lifecycle (State Machine)</h2>
|
|
130
|
-
<pre><code> ┌──────────┐
|
|
131
|
-
│ pending │◄──────────────────────────────┐
|
|
132
|
-
└────┬─────┘ │
|
|
133
|
-
│ leaseTask() │
|
|
134
|
-
▼ │
|
|
135
|
-
┌──────────┐ │
|
|
136
|
-
│in_progress│ │
|
|
137
|
-
└────┬─────┘ │
|
|
138
|
-
┌───────────┼───────────┐ │
|
|
139
|
-
▼ ▼ ▼ │
|
|
140
|
-
┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
141
|
-
│completed │ │ failed │ │cancelled │ │
|
|
142
|
-
└──────────┘ └────┬─────┘ └──────────┘ │
|
|
143
|
-
│ retryTask() │
|
|
144
|
-
├── retryCount < max → backoff → ────┘
|
|
145
|
-
│
|
|
146
|
-
└── retryCount ≥ max
|
|
147
|
-
│
|
|
148
|
-
▼
|
|
149
|
-
┌──────────────┐
|
|
150
|
-
│ dead_letter │
|
|
151
|
-
│ (preserved │
|
|
152
|
-
│ for review) │
|
|
153
|
-
└──────────────┘</code></pre>
|
|
154
|
-
|
|
155
|
-
<h2>Related Files</h2>
|
|
156
|
-
<table>
|
|
157
|
-
<tr><th>File</th><th>Role</th></tr>
|
|
158
|
-
<tr><td><code>src/services/autonomous/agentLoop.ts</code></td><td>Main loop — start, stop, processTask, worker lifecycle</td></tr>
|
|
159
|
-
<tr><td><code>src/services/autonomous/taskQueue.ts</code></td><td>Queue CRUD, lease management, retry, dead-letter, file watcher</td></tr>
|
|
160
|
-
<tr><td><code>src/services/autonomous/daemonMode.ts</code></td><td>Daemon entry point — calls startLoop/stopLoop</td></tr>
|
|
161
|
-
<tr><td><code>src/Task.ts</code></td><td>Task type definitions, state machine, task ID generation</td></tr>
|
|
162
|
-
<tr><td><code>src/tasks/LocalAgentTask/</code></td><td>Local worker task — UI + lifecycle</td></tr>
|
|
163
|
-
<tr><td><code>src/tasks/RemoteAgentTask/</code></td><td>Remote worker task — UI + lifecycle</td></tr>
|
|
164
|
-
<tr><td><code>src/components/AutonomousExecutionAccordion.tsx</code></td><td>UI component for task queue display in REPL</td></tr>
|
|
165
|
-
</table>
|
|
166
|
-
|
|
167
|
-
<footer class="footer">
|
|
168
|
-
<span>Clew Code — Open Source</span>
|
|
169
|
-
<div class="footer-links">
|
|
170
|
-
<a href="https://github.com/ClewCode/ClewCode">GitHub</a>
|
|
171
|
-
<a href="https://github.com/ClewCode/ClewCode/issues">Issues</a>
|
|
172
|
-
</div>
|
|
173
|
-
</footer>
|
|
174
|
-
</main>
|
|
175
|
-
<nav class="toc-sidebar"></nav>
|
|
176
|
-
</div>
|
|
177
|
-
</div>
|
|
178
|
-
<script src="js/main.js"></script>
|
|
179
|
-
</body>
|
|
180
|
-
</html>
|
|
181
|
-
|
|
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>Agent Loop — Clew Code</title>
|
|
7
|
+
<meta name="description" content="24/7 autonomous agent loop for background task execution.">
|
|
8
|
+
<link rel="icon" type="image/svg+xml" href="assets/clew.svg">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
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
|
+
</head>
|
|
13
|
+
<body>
|
|
14
|
+
<header class="header"></header>
|
|
15
|
+
<div id="sidebarOverlay" class="sidebar-overlay"></div>
|
|
16
|
+
<aside id="sidebar" class="sidebar"></aside>
|
|
17
|
+
|
|
18
|
+
<div class="content-wrap">
|
|
19
|
+
<div class="content">
|
|
20
|
+
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span class="current">Agent Loop</span></div>
|
|
22
|
+
|
|
23
|
+
<h1>Agent Loop</h1>
|
|
24
|
+
<p class="sub">Run Clew Code autonomously with a 24/7 background agent loop.</p>
|
|
25
|
+
|
|
26
|
+
<h2 id="overview">Overview</h2>
|
|
27
|
+
<p>The autonomous agent loop runs Clew Code continuously in the background, processing tasks from a persistent queue. It's ideal for monitoring, scheduled maintenance, automated code review, and recurring development workflows.</p>
|
|
28
|
+
|
|
29
|
+
<h2 id="commands">Loop Commands</h2>
|
|
30
|
+
<pre><code class="language-bash">❯ /loop start # start the autonomous loop
|
|
31
|
+
❯ /loop stop # stop the loop
|
|
32
|
+
❯ /loop status # check loop status and queue depth
|
|
33
|
+
</code></pre>
|
|
34
|
+
|
|
35
|
+
<h2 id="loop-skill">Loop Skill</h2>
|
|
36
|
+
<p>Use the built-in loop skill to run recurring requests:</p>
|
|
37
|
+
<pre><code class="language-bash">❯ /loop 5m /check-status # run /check-status every 5 minutes
|
|
38
|
+
❯ /loop 1h "summarize recent changes"
|
|
39
|
+
</code></pre>
|
|
40
|
+
<p>Default interval is 10 minutes if not specified.</p>
|
|
41
|
+
|
|
42
|
+
<h2 id="task-queue">Task Queue</h2>
|
|
43
|
+
<p>The loop integrates with the daemon's persistent task queue:</p>
|
|
44
|
+
<ul>
|
|
45
|
+
<li><strong>Lease-based concurrency</strong> — up to 3 workers run simultaneously</li>
|
|
46
|
+
<li><strong>Exponential backoff</strong> — retries with increasing delays on failure</li>
|
|
47
|
+
<li><strong>Dead-letter queue</strong> — failed tasks are stored for later analysis</li>
|
|
48
|
+
</ul>
|
|
49
|
+
|
|
50
|
+
<h2 id="scheduling">Cron Scheduling</h2>
|
|
51
|
+
<p>Schedule recurring tasks with cron expressions:</p>
|
|
52
|
+
<pre><code class="language-bash">❯ /task add "0 9 * * 1-5" "weekday morning review"
|
|
53
|
+
❯ /task add "0 0 * * 0" "weekly cleanup"
|
|
54
|
+
</code></pre>
|
|
55
|
+
|
|
56
|
+
<h2 id="use-cases">Use Cases</h2>
|
|
57
|
+
<ul>
|
|
58
|
+
<li>Automated code review on schedule</li>
|
|
59
|
+
<li>Dependency update checks</li>
|
|
60
|
+
<li>Performance monitoring and alerting</li>
|
|
61
|
+
<li>Scheduled documentation generation</li>
|
|
62
|
+
<li>Automated testing and regression checks</li>
|
|
63
|
+
</ul>
|
|
64
|
+
</div>
|
|
65
|
+
</div>
|
|
66
|
+
|
|
67
|
+
<script src="js/main.js"></script>
|
|
68
|
+
</body>
|
|
69
|
+
</html>
|
package/docs/mcp.html
CHANGED
|
@@ -1,247 +1,99 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="en">
|
|
3
|
-
<head>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
<
|
|
15
|
-
<
|
|
16
|
-
<
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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> — 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 <name> <command> [args...]</code></td><td>Add a new stdio MCP server</td></tr>
|
|
163
|
-
<tr><td><code>/mcp remove <name></code></td><td>Remove a connected MCP server</td></tr>
|
|
164
|
-
<tr><td><code>/mcp reconnect <name></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 MCP 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
|
-
|
|
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" href="Model Context Protocol (MCP) integration in Clew Code.">
|
|
8
|
+
<link rel="icon" type="image/svg+xml" href="assets/clew.svg">
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
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
|
+
</head>
|
|
13
|
+
<body>
|
|
14
|
+
<header class="header"></header>
|
|
15
|
+
<div id="sidebarOverlay" class="sidebar-overlay"></div>
|
|
16
|
+
<aside id="sidebar" class="sidebar"></aside>
|
|
17
|
+
|
|
18
|
+
<div class="content-wrap">
|
|
19
|
+
<div class="content">
|
|
20
|
+
|
|
21
|
+
<div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span class="current">MCP</span></div>
|
|
22
|
+
|
|
23
|
+
<h1>MCP — Model Context Protocol</h1>
|
|
24
|
+
<p class="sub">Connect external tools and data sources via the Model Context Protocol. Clew Code supports stdio, SSE, and DirectConnect transports.</p>
|
|
25
|
+
|
|
26
|
+
<h2 id="overview">Overview</h2>
|
|
27
|
+
<p>MCP (Model Context Protocol) is an open standard for connecting AI agents with external tools and data sources. Clew Code implements the full MCP specification as both a client and server.</p>
|
|
28
|
+
|
|
29
|
+
<h2 id="transports">Transport Types</h2>
|
|
30
|
+
<table>
|
|
31
|
+
<thead>
|
|
32
|
+
<tr><th>Transport</th><th>Description</th></tr>
|
|
33
|
+
</thead>
|
|
34
|
+
<tbody>
|
|
35
|
+
<tr><td>stdio</td><td>Local subprocess — spawns an MCP server as a child process and communicates via stdin/stdout</td></tr>
|
|
36
|
+
<tr><td>SSE</td><td>Remote servers with optional OAuth authentication via Server-Sent Events</td></tr>
|
|
37
|
+
<tr><td>DirectConnect</td><td>In-process plugin servers — runs MCP servers as plugins within the same process</td></tr>
|
|
38
|
+
</tbody>
|
|
39
|
+
</table>
|
|
40
|
+
|
|
41
|
+
<h2 id="configuration">Configuration</h2>
|
|
42
|
+
<p>MCP servers are configured in <code>.mcp.json</code> at the project root:</p>
|
|
43
|
+
<pre><code class="language-json">{
|
|
44
|
+
"mcpServers": {
|
|
45
|
+
"filesystem": {
|
|
46
|
+
"command": "npx",
|
|
47
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
|
|
48
|
+
},
|
|
49
|
+
"github": {
|
|
50
|
+
"command": "npx",
|
|
51
|
+
"args": ["-y", "@modelcontextprotocol/server-github"],
|
|
52
|
+
"env": {
|
|
53
|
+
"GITHUB_TOKEN": "ghp_..."
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"remote-api": {
|
|
57
|
+
"url": "https://my-mcp-server.example.com/sse",
|
|
58
|
+
"auth": {
|
|
59
|
+
"type": "oauth2"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
</code></pre>
|
|
65
|
+
|
|
66
|
+
<h2 id="commands">MCP Commands</h2>
|
|
67
|
+
<pre><code class="language-bash">❯ /mcp list # list connected MCP servers and their tools
|
|
68
|
+
❯ /mcp add # add a new MCP server configuration
|
|
69
|
+
❯ /mcp remove <id> # remove an MCP server
|
|
70
|
+
</code></pre>
|
|
71
|
+
|
|
72
|
+
<h2 id="cli-tools">CLI MCP Tools</h2>
|
|
73
|
+
<p>The built-in MCP tools allow the AI to interact with connected servers:</p>
|
|
74
|
+
<table>
|
|
75
|
+
<thead>
|
|
76
|
+
<tr><th>Tool</th><th>Description</th></tr>
|
|
77
|
+
</thead>
|
|
78
|
+
<tbody>
|
|
79
|
+
<tr><td>ListMcpResourcesTool</td><td>List available resources from connected MCP servers</td></tr>
|
|
80
|
+
<tr><td>ReadMcpResourceTool</td><td>Read a specific resource from an MCP server</td></tr>
|
|
81
|
+
</tbody>
|
|
82
|
+
</table>
|
|
83
|
+
|
|
84
|
+
<h2 id="mcp-servers">Example MCP Servers</h2>
|
|
85
|
+
<ul>
|
|
86
|
+
<li><strong>Filesystem</strong> — safe file access with path restrictions</li>
|
|
87
|
+
<li><strong>GitHub</strong> — repository management, PRs, issues</li>
|
|
88
|
+
<li><strong>Playwright</strong> — browser automation</li>
|
|
89
|
+
<li><strong>Slack</strong> — workspace integration</li>
|
|
90
|
+
<li><strong>PostgreSQL</strong> — database schema exploration and queries</li>
|
|
91
|
+
<li><strong>Sentry</strong> — error tracking and issue management</li>
|
|
92
|
+
</ul>
|
|
93
|
+
<p>Browse the <a href="https://github.com/modelcontextprotocol/servers">official MCP server repository</a> for more.</p>
|
|
94
|
+
</div>
|
|
95
|
+
</div>
|
|
96
|
+
|
|
97
|
+
<script src="js/main.js"></script>
|
|
98
|
+
</body>
|
|
99
|
+
</html>
|