@swarmclawai/swarmclaw 1.5.44 → 1.5.45

package/README.md

@@ -8,6 +8,12 @@
   <img src="https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/public/branding/swarmclaw-org-avatar.png" alt="SwarmClaw lobster logo" width="120" />
 </p>
 
+<p align="center"><strong>Self-hosted runtime for autonomous AI agents.</strong> Multi-provider, MCP-native, with memory, skills, delegation, and schedules.</p>
+
+<p align="center">
+  <img src="doc/assets/screenshots/org-chart.png" alt="SwarmClaw org chart with delegation and live agent activity" width="900" />
+</p>
+
 SwarmClaw is a self-hosted AI runtime for OpenClaw and multi-agent work. It helps you run autonomous agents and orchestrators with heartbeats, schedules, delegation, memory, runtime skills, and reviewed conversation-to-skill learning across OpenClaw gateways and other providers.
 
 GitHub: https://github.com/swarmclawai/swarmclaw  
@@ -175,6 +181,7 @@ Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
 - **Memory**: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
 - **Wallets**: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
 - **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, SwarmDock, SwarmFeed, and more.
+- **MCP Servers**: connect any Model Context Protocol server (stdio, SSE, or streamable HTTP) and inject its tools into agents alongside built-ins. Configure, test, and assign per-agent from the MCP Servers panel.
 - **Extensions**: external tool extensions, UI modules, hooks, and install/update flows.
 
 ## What SwarmClaw Focuses On
@@ -389,6 +396,12 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.45 Highlights
+
+- **SwarmVault MCP preset**: a new "SwarmVault" Quick Setup chip in the MCP server sheet pre-fills `npx -y @swarmvaultai/cli mcp` over `stdio` and prompts for the vault directory. One click registers a SwarmVault knowledge vault as an MCP server; agents pick it up via the existing per-agent MCP server selector. SwarmVault docs: https://swarmvault.ai
+- **`cwd` on stdio MCP servers**: `McpServerConfig` now has an optional `cwd` field. The MCP client passes it through to `StdioClientTransport` so servers that discover config from the working directory (SwarmVault, anything that reads from `cwd`-relative files) work correctly. Existing MCP servers are untouched (the field is optional and defaults to the SwarmClaw process cwd, which was the prior behaviour).
+- **Bundled `swarmvault` skill**: ships at `skills/swarmvault/SKILL.md` and is auto-discovered alongside the other bundled skills. Captures the schema-first / graph-query-first conventions (read `swarmvault.schema.md` before compile or query work, treat `raw/` as immutable, prefer `graph query|path|explain` over grep, preserve `page_id` / `source_ids` / `node_ids` / `freshness` / `source_hashes` frontmatter, save high-value answers to `wiki/outputs/`). Pin it on any agent that talks to a SwarmVault vault. Optional and decoupled from the MCP integration.
+
 ### v1.5.44 Highlights
 
 - **Model lists refreshed across every provider**: dropdowns now lead with the April-2026 flagship models instead of mid-2025 names. OpenAI goes to GPT-5.4 / 5.4-mini / 5.4-nano / 5.3 / o3-mini. Google and Gemini CLI lead with Gemini 3.1 Pro, Gemini 3 Flash, and 3.1 Flash-Lite, keeping 2.5 as a legacy fallback. xAI jumps from Grok 3 to Grok 4 plus the Grok 4 / 4.1 Fast reasoning and non-reasoning variants. Groq drops the deprecated `deepseek-r1-distill-llama-70b` and leads with Llama 4 Maverick, Llama 4 Scout, Kimi K2, and gpt-oss 120b/20b. Mistral moves to Magistral 1.2, Devstral 2, Codestral, and Mistral Small 4. Fireworks / Nebius / DeepInfra now lead with DeepSeek V3.2, Kimi K2.5, and Qwen 3 235B instead of the older R1-0528 checkpoint. Anthropic and Claude CLI reorder Opus 4.6 / Sonnet 4.6 / Haiku 4.5 newest-first. OpenCode Web refreshes its `providerID/modelID` seed list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.44",
+  "version": "1.5.45",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/skills/swarmvault/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: swarmvault
+description: Use when working with a SwarmVault knowledge vault (raw/, wiki/, swarmvault.schema.md). Establishes schema-first conventions and prefers graph queries over broad search.
+homepage: https://swarmvault.ai
+metadata:
+  openclaw:
+    capabilities: [knowledge-base, knowledge-graph, retrieval, vault]
+    requires:
+      bins: [npx]
+---
+
+# SwarmVault
+
+Use when the agent has a SwarmVault MCP server enabled (transport `stdio`, command `npx -y @swarmvaultai/cli mcp`) pointed at a vault directory.
+
+A SwarmVault workspace is a three-layer knowledge system:
+
+- `raw/` — immutable source inputs (PDFs, transcripts, code, emails, URLs, sheets). Never edit.
+- `wiki/` — generated markdown owned by the agent and the SwarmVault compiler. Pages carry frontmatter (`page_id`, `source_ids`, `node_ids`, `freshness`, `source_hashes`).
+- `state/` — generated indexes, graphs, and approvals. Treat as opaque output of `compile`.
+
+The vault contract lives in `swarmvault.schema.md` at the workspace root. The vault config lives in `swarmvault.config.json`.
+
+## Rules
+
+1. **Read `swarmvault.schema.md` first** before any compile or query work. It defines categories, naming, freshness rules, and grounding conventions for this specific vault.
+2. **Read `wiki/graph/report.md` before broad file searching** when it exists; otherwise start with `wiki/index.md`. Both summarize the vault structure so you don't re-scan everything.
+3. **Treat `raw/` as immutable.** Never edit, rename, or delete files there. New sources go through `ingest`.
+4. **Treat `wiki/` as compiler-owned.** Edits should preserve frontmatter fields exactly: `page_id`, `source_ids`, `node_ids`, `freshness`, `source_hashes`. If those drift, the next `compile` will overwrite or flag the page.
+5. **Prefer graph queries over grep/glob** for "how does X relate to Y" or "what depends on Z" questions. The vault's typed graph is more reliable than text search.
+6. **Save high-value answers** to `wiki/outputs/` (use the `query` or `explore` tools) instead of leaving them only in chat. That way they become first-class vault content for next time.
+
+## Tool Palette
+
+The SwarmVault MCP server exposes the following tools (names are prefixed by SwarmClaw with `mcp_<sanitized server name>_`, e.g. `mcp_SwarmVault_query_vault`). Match the user's intent to the closest tool:
+
+Vault inspection:
+- `workspace_info` — return current vault paths and high-level counts. Use this first when you've never seen this vault.
+- `list_sources` — list source manifests under `raw/`.
+- `search_pages` — full-text search across compiled wiki pages.
+- `read_page` — read a specific wiki page by its `wiki/`-relative path.
+
+Graph (prefer over grep for relational questions):
+- `graph_report` — machine-readable graph report and trust artifact. Read this before broad searching.
+- `query_graph` — traverse the graph from search seeds without calling an LLM provider.
+- `get_node` — explain a graph node, its page, community, neighbors, and group patterns.
+- `get_neighbors` — neighbors of a node or page target.
+- `get_hyperedges` — list graph hyperedges, optionally filtered.
+- `shortest_path` — shortest path between two graph targets.
+- `god_nodes` — highest-connectivity nodes (the vault's hubs).
+- `blast_radius` — impact analysis: what depends on this file or module?
+
+Question answering:
+- `query_vault` — natural-language question against the vault. Returns grounded citations. Pass `save: true` to persist the answer to `wiki/outputs/`.
+
+Ingest and maintenance:
+- `ingest_input` — add a file path or URL to `raw/` and register it as a managed source.
+- `compile_vault` — re-derive `wiki/` pages, graph, and search index. Run after ingest, after schema changes, or when freshness is stale.
+- `lint_vault` — anti-drift and vault health checks.
+
+If the MCP server is unavailable but the agent has a `shell` or `execute` tool, the same operations are available via `swarmvault <subcommand>` (or `npx -y @swarmvaultai/cli <subcommand>`) with the working directory set to the vault root.
+
+## Workflow
+
+For a fresh question against the vault:
+
+1. Call `workspace_info` if you haven't already, then read `swarmvault.schema.md`. If `wiki/graph/report.md` or `wiki/index.md` exists, skim it.
+2. Use `query_vault` (or `query_graph` / `get_node` / `shortest_path` for relational questions). Cite returned `source_ids` and `node_ids`.
+3. If the answer reveals a gap, propose `ingest_input` for the missing source, then `compile_vault`.
+4. Save the final answer with `query_vault` `save: true` so it becomes vault content under `wiki/outputs/`.
+
+For a new source the user mentions:
+
+1. `ingest_input` the file/URL.
+2. `compile_vault` to derive new wiki pages, graph, and search index.
+3. `lint_vault` to check frontmatter and links.
+4. Skim the new pages in `wiki/sources/` and confirm provenance.
+
+## Boundaries
+
+- Don't run `compile` against an unreviewed change to `swarmvault.schema.md` — `lint` first.
+- Don't promote candidate pages (`wiki/candidates/`) to `wiki/concepts/` or `wiki/entities/` without the user's confirmation; the approval flow exists for a reason.
+- Don't push the vault graph to Neo4j or export to Obsidian without an explicit ask.

package/src/app/api/mcp-servers/route.test.ts

@@ -1,4 +1,6 @@
 import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import test, { afterEach } from 'node:test'
@@ -57,12 +59,12 @@ test('MCP server routes exercise a live stdio server end to end', async () => {
   assert.equal(healthResponse.status, 200)
   const health = await healthResponse.json() as Record<string, unknown>
   assert.equal(health.ok, true)
-  assert.deepEqual(health.tools, ['mcp_smoke_ping', 'mcp_smoke_echo'])
+  assert.deepEqual(health.tools, ['mcp_smoke_ping', 'mcp_smoke_echo', 'mcp_smoke_cwd_check'])
 
   const toolsResponse = await listMcpTools(new Request(`http://local/api/mcp-servers/${serverId}/tools`), routeParams(serverId))
   assert.equal(toolsResponse.status, 200)
   const tools = await toolsResponse.json() as Array<Record<string, unknown>>
-  assert.deepEqual(tools.map((tool) => tool.name), ['ping', 'echo'])
+  assert.deepEqual(tools.map((tool) => tool.name), ['ping', 'echo', 'cwd_check'])
 
   const invokeResponse = await invokeMcpTool(new Request(`http://local/api/mcp-servers/${serverId}/invoke`, {
     method: 'POST',
@@ -85,7 +87,7 @@ test('MCP server routes exercise a live stdio server end to end', async () => {
   assert.equal(conformanceResponse.status, 200)
   const conformance = await conformanceResponse.json() as Record<string, unknown>
   assert.equal(conformance.ok, true)
-  assert.equal(conformance.toolsCount, 2)
+  assert.equal(conformance.toolsCount, 3)
   assert.equal(conformance.smokeToolName, 'ping')
 
   const updateResponse = await updateMcpServer(new Request(`http://local/api/mcp-servers/${serverId}`, {
@@ -104,6 +106,50 @@ test('MCP server routes exercise a live stdio server end to end', async () => {
   assert.equal(loadMcpServers()[serverId], undefined)
 })
 
+test('cwd is persisted and forwarded to the spawned MCP server', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-cwd-'))
+  // Resolve symlinks (macOS /var → /private/var) so the comparison matches what the child process reports.
+  const resolvedTmpDir = fs.realpathSync(tmpDir)
+
+  try {
+    const createResponse = await createMcpServer(new Request('http://local/api/mcp-servers', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        name: 'cwd-smoke',
+        transport: 'stdio',
+        command: process.execPath,
+        args: [fixturePath],
+        cwd: resolvedTmpDir,
+      }),
+    }))
+    assert.equal(createResponse.status, 200)
+    const created = await createResponse.json() as Record<string, unknown>
+    const serverId = String(created.id)
+    assert.equal(created.cwd, resolvedTmpDir, 'POST should persist cwd on the saved record')
+
+    const detailResponse = await getMcpServer(new Request(`http://local/api/mcp-servers/${serverId}`), routeParams(serverId))
+    const detail = await detailResponse.json() as Record<string, unknown>
+    assert.equal(detail.cwd, resolvedTmpDir, 'GET should return the persisted cwd')
+
+    const invokeResponse = await invokeMcpTool(new Request(`http://local/api/mcp-servers/${serverId}/invoke`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ toolName: 'cwd_check', args: '{}' }),
+    }), routeParams(serverId))
+    assert.equal(invokeResponse.status, 200)
+    const invokePayload = await invokeResponse.json() as Record<string, unknown>
+    assert.equal(invokePayload.ok, true)
+    assert.equal(
+      invokePayload.text,
+      `cwd: ${resolvedTmpDir}`,
+      'Spawned MCP server should report the cwd we configured, not SwarmClaw\'s process cwd',
+    )
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  }
+})
+
 test('MCP invoke route validates required fields before connecting', async () => {
   const serverId = 'mcp-validate-smoke'
   const servers = loadMcpServers()

package/src/app/api/mcp-servers/route.ts

@@ -20,6 +20,7 @@ export async function POST(req: Request) {
     transport: body.transport,
     command: body.command,
     args: body.args,
+    cwd: body.cwd,
     url: body.url,
     env: body.env,
     headers: body.headers,

package/src/components/mcp-servers/mcp-server-sheet.tsx

@@ -4,11 +4,40 @@ import { useState } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
 import { BottomSheet } from '@/components/shared/bottom-sheet'
 import { ConfirmDialog } from '@/components/shared/confirm-dialog'
+import { HintTip } from '@/components/shared/hint-tip'
 import { api } from '@/lib/app/api-client'
 import { toast } from 'sonner'
 import type { McpServerConfig, McpTransport } from '@/types'
 import { useMountedRef } from '@/hooks/use-mounted-ref'
 
+interface McpPreset {
+  id: string
+  label: string
+  description: string
+  helpUrl?: string
+  transport: McpTransport
+  command?: string
+  args?: string[]
+  needsCwd?: boolean
+  cwdHint?: string
+  defaultName: string
+}
+
+const MCP_PRESETS: McpPreset[] = [
+  {
+    id: 'swarmvault',
+    label: 'SwarmVault',
+    description: 'Local-first knowledge vault. Point this at a directory containing swarmvault.config.json.',
+    helpUrl: 'https://swarmvault.ai',
+    transport: 'stdio',
+    command: 'npx',
+    args: ['-y', '@swarmvaultai/cli', 'mcp'],
+    needsCwd: true,
+    cwdHint: 'Absolute path to a SwarmVault workspace (the directory containing swarmvault.config.json). Run `npx @swarmvaultai/cli init` there first if you haven\'t.',
+    defaultName: 'SwarmVault',
+  },
+]
+
 function McpServerForm({ editing, onClose, loadMcpServers }: {
   editing: McpServerConfig | null
   onClose: () => void
@@ -19,6 +48,8 @@ function McpServerForm({ editing, onClose, loadMcpServers }: {
   const [transport, setTransport] = useState<McpTransport>(editing?.transport || 'stdio')
   const [command, setCommand] = useState(editing?.command || '')
   const [args, setArgs] = useState(editing?.args?.join(', ') || '')
+  const [cwd, setCwd] = useState(editing?.cwd || '')
+  const [activePresetId, setActivePresetId] = useState<string | null>(null)
   const [url, setUrl] = useState(editing?.url || '')
   const [envText, setEnvText] = useState(
     editing?.env ? Object.entries(editing.env).map(([k, v]) => `${k}=${v}`).join('\n') : '',
@@ -61,6 +92,7 @@ function McpServerForm({ editing, onClose, loadMcpServers }: {
     if (transport === 'stdio') {
       data.command = command.trim()
       data.args = args.trim() ? args.split(',').map((a) => a.trim()).filter(Boolean) : []
+      data.cwd = cwd.trim() || undefined
     } else {
       data.url = url.trim()
     }
@@ -122,6 +154,16 @@ function McpServerForm({ editing, onClose, loadMcpServers }: {
 
   const canSave = name.trim() && (transport === 'stdio' ? command.trim() : url.trim())
 
+  const applyPreset = (preset: McpPreset) => {
+    setActivePresetId(preset.id)
+    setTransport(preset.transport)
+    if (preset.command !== undefined) setCommand(preset.command)
+    if (preset.args !== undefined) setArgs(preset.args.join(', '))
+    if (!name.trim()) setName(preset.defaultName)
+  }
+
+  const activePreset = activePresetId ? MCP_PRESETS.find((p) => p.id === activePresetId) ?? null : null
+
   const inputClass = "w-full px-4 py-3.5 rounded-[14px] border border-white/[0.08] bg-surface text-text text-[15px] outline-none transition-all duration-200 placeholder:text-text-3/50 focus-glow"
   const labelClass = "block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-3"
 
@@ -134,6 +176,44 @@ function McpServerForm({ editing, onClose, loadMcpServers }: {
         <p className="text-[14px] text-text-3">Configure an MCP server to provide tools to agents</p>
       </div>
 
+      {!editing && MCP_PRESETS.length > 0 && (
+        <div className="mb-8">
+          <label className={labelClass}>Quick Setup</label>
+          <div className="flex flex-wrap gap-2">
+            {MCP_PRESETS.map((preset) => {
+              const isActive = activePresetId === preset.id
+              return (
+                <button
+                  key={preset.id}
+                  type="button"
+                  onClick={() => applyPreset(preset)}
+                  className={`py-2 px-4 rounded-[12px] border text-[13px] font-600 cursor-pointer transition-all ${
+                    isActive
+                      ? 'border-accent-bright bg-accent-bright/10 text-accent-bright'
+                      : 'border-white/[0.08] bg-transparent text-text-2 hover:bg-surface-2'
+                  }`}
+                  style={{ fontFamily: 'inherit' }}
+                  title={preset.description}
+                >
+                  {preset.label}
+                </button>
+              )
+            })}
+          </div>
+          {activePreset && (
+            <p className="mt-3 text-[12px] text-text-3">
+              {activePreset.description}
+              {activePreset.helpUrl && (
+                <>
+                  {' '}
+                  <a href={activePreset.helpUrl} target="_blank" rel="noopener noreferrer" className="text-accent-bright hover:underline">Learn more</a>
+                </>
+              )}
+            </p>
+          )}
+        </div>
+      )}
+
       <div className="mb-8">
         <label className={labelClass}>Name</label>
         <input type="text" value={name} onChange={(e) => setName(e.target.value)} placeholder="e.g. Filesystem Server" className={inputClass} style={{ fontFamily: 'inherit' }} />
@@ -165,6 +245,22 @@ function McpServerForm({ editing, onClose, loadMcpServers }: {
             </label>
             <input type="text" value={args} onChange={(e) => setArgs(e.target.value)} placeholder="e.g. /path/to/dir, --verbose" className={inputClass} style={{ fontFamily: 'inherit' }} />
           </div>
+          <div className="mb-8">
+            <label className={labelClass}>
+              <span className="inline-flex items-center gap-2">
+                Working Directory <span className="normal-case tracking-normal font-normal text-text-3">(optional)</span>
+                <HintTip text={activePreset?.cwdHint || 'Working directory for the spawned process. Useful when the MCP server discovers config from cwd (e.g. SwarmVault).'} />
+              </span>
+            </label>
+            <input
+              type="text"
+              value={cwd}
+              onChange={(e) => setCwd(e.target.value)}
+              placeholder={activePreset?.needsCwd ? 'e.g. /Users/you/my-vault' : 'e.g. /path/to/working/dir'}
+              className={inputClass}
+              style={{ fontFamily: 'inherit' }}
+            />
+          </div>
         </>
       ) : (
         <div className="mb-8">

package/src/lib/server/__fixtures__/fake-mcp-stdio-server.mjs

@@ -23,5 +23,12 @@ server.registerTool('echo', {
   content: [{ type: 'text', text: `echo: ${message}` }],
 }))
 
+server.registerTool('cwd_check', {
+  description: 'Returns the working directory the server was launched in',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: `cwd: ${process.cwd()}` }],
+}))
+
 const transport = new StdioServerTransport()
 await server.connect(transport)

package/src/lib/server/mcp-client.ts

@@ -77,6 +77,7 @@ export async function connectMcpServer(
     transport = new StdioClientTransport({
       command: config.command!,
       args: config.args ?? [],
+      cwd: config.cwd || undefined,
       env: { ...process.env, ...config.env } as Record<string, string>,
     })
   } else if (config.transport === 'sse') {

package/src/types/misc.ts

@@ -613,6 +613,7 @@ export interface McpServerConfig {
   transport: McpTransport
   command?: string             // for stdio transport
   args?: string[]              // for stdio transport
+  cwd?: string                 // working directory for stdio transport (e.g. SwarmVault vault dir)
   url?: string                 // for sse/streamable-http transport
   env?: Record<string, string> // environment variables
   headers?: Record<string, string> // HTTP headers for sse/streamable-http