SmileWork

SmileWork 是跨代理共用的本機 MCP 伺服器。它透過 stdio 連上 Claude Code、OpenCode、Codex 等宿主，讓同一個專案的工作、證據、知識與對話索引由同一份資料庫管理。資料保存在 ~/.smilework/，伺服器本身不呼叫 LLM，也不連網。

目前版本是 0.1.1，已發佈到 npm。用 bun add -g smilework 安裝後執行 smilework，也可以從原始碼執行。

提供什麼

• 21 個 MCP 工具，分成工作、驗證、狀態、訊號、知識與對話六個領域。

• 三種工具 profile：worker 12 個、curator 15 個、full 21 個。

• 工作流程：建立、更新、依賴、可開始清單、審查、結案。結案會檢查驗收結果、證據、依賴與高風險核准。

• 伺服器驗證：verify_run 只能執行白名單 runner（bun、npm、pytest、cargo、gradle、swift），輸出寫成可追查的伺服器證據。

• 知識：寫入前檢查、版本、歷史、還原、退役與升級。

• 訊號：記錄糾正、失敗、修好、審查退回與教訓。

• 對話：索引 Claude Code、Codex 與 OpenCode 的對話紀錄，支援搜尋與讀取。

• 匯出與匯入：舊版 .ultrawork/ 匯出成 smilework-export v1，再匯入本機資料庫。

• MCP resources 與 prompts：工作看板、單一工作、知識索引，以及派工、審查、整理三個提示。

Related MCP server: todos

需求

• Bun 1.3 以上

• 一個 git 專案（工作會綁定專案根目錄）

安裝與檢查

從 npm 全域安裝：

bun add -g smilework
smilework --help

從原始碼開發時：

bun install
bun run typecheck
bun test
bun run build

查看 CLI 說明：

bun run src/cli/index.ts --help

檢查環境：

bun run src/cli/index.ts doctor --json

doctor 只讀取現有狀態。資料庫或對話索引尚未建立時，它會回報警告與下一步，不會自動寫入資料。

連上宿主

先設定共用環境變數：

export SMILEWORK_ACTOR=my-agent
export SMILEWORK_MODEL=my-model
export SMILEWORK_PROFILE=worker

SMILEWORK_ACTOR 與 SMILEWORK_MODEL 會寫進工作、證據與事件紀錄。SMILEWORK_PROFILE 選擇工具清單；未設定時預設 worker。SMILEWORK_PROJECT 可以指定專案根目錄，省略時從程序的工作目錄往上找 git 根目錄。

設定範例

Claude Code 的專案 .mcp.json：

{
  "mcpServers": {
    "smilework": {
      "command": "/Users/you/.bun/bin/bun",
      "args": ["/Users/you/src/SmileWork/src/cli/index.ts", "mcp"],
      "env": {
        "SMILEWORK_PROFILE": "worker",
        "SMILEWORK_ACTOR": "claude-code",
        "SMILEWORK_MODEL": "claude-sonnet-4-5",
        "SMILEWORK_PROJECT": "/Users/you/src/your-project"
      }
    }
  }
}

OpenCode 的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "smilework": {
      "type": "local",
      "command": ["/Users/you/.bun/bin/bun", "/Users/you/src/SmileWork/src/cli/index.ts", "mcp"],
      "enabled": true,
      "environment": {
        "SMILEWORK_PROFILE": "worker",
        "SMILEWORK_ACTOR": "opencode",
        "SMILEWORK_MODEL": "your-model",
        "SMILEWORK_PROJECT": "/Users/you/src/your-project"
      }
    }
  }
}

Codex 的 ~/.codex/config.toml：

[mcp_servers.smilework]
command = "/Users/you/.bun/bin/bun"
args = ["/Users/you/src/SmileWork/src/cli/index.ts", "mcp"]
cwd = "/Users/you/src/your-project"
env = { SMILEWORK_PROFILE = "worker", SMILEWORK_ACTOR = "codex", SMILEWORK_MODEL = "your-model", SMILEWORK_PROJECT = "/Users/you/src/your-project" }

整理代理用同一個指令，把 SMILEWORK_PROFILE 改成 curator，並換一個伺服器名稱（例如 smilework-curator），避免和執行代理混在一起。三家宿主的完整範例：

• Claude Code

• OpenCode

• Codex

• 整理代理

• 共同設定與 profile 說明

跑完一輪工作

連線成功後，請代理依序呼叫：

1. work_create：建立工作，填 title、objective、acceptance 與 risk。高風險工作要設 risk: "high"。

2. work_update：把 status 改成 in_progress。人工證據可以在這裡用 evidence 一起寫入。

3. verify_run：指定 workId、runner 與 script，由伺服器執行驗證並建立伺服器證據。例如 runner: "bun"、script: "test"。

4. work_review：由非 owner 的審查者記錄 approve、concerns 或 reject。高風險工作一定要有非 owner 的 approve。

5. work_complete：逐項回報驗收結果，met: true 的項目要附 evidenceIds。缺少驗收、證據、依賴或高風險核准時，結案會失敗並回報原因。

完成後用 work_get 讀回工作，確認狀態是 done、resolution 是 completed，而且證據與審查都留下紀錄。

CLI

下表用安裝後的 smilework。從原始碼執行時，把 smilework 換成 bun run src/cli/index.ts。

每個子命令都支援 --help。

資料位置

SMILEWORK_HOME 可以改掉整個資料目錄。多個宿主共用同一個資料庫時，SQLite 以 WAL 模式開啟，並設定 busy_timeout；同時大量寫入仍可能遇到忙碌，重試即可。

文件

• 文件索引

• 宿主設定

• 匯出格式 v1

開發

bun install
bun test
bun run typecheck
bun run build

• 測試使用 bun test，型別檢查使用 tsc --noEmit。

• bun.lock 要進版控，不要手動編輯。

• 研究筆記與 spike 放在 .ultrawork/research/，不進版控。

目前限制

• 只提供 stdio 傳輸，沒有 HTTP 常駐程式。

• 三個 profile 的工具數量固定為 12、15、21；專案層設定只能停用工具，不能改 profile。

• 不做雲端同步，也不在伺服器內呼叫 LLM。