Slop MCP Scripting

SLOP Scripting Guide

SLOP 語言令多工具工作流跨所有已注冊 MCP 服務器自動化。腳本經 run_slop 工具運行，亦作 customize_tools 所定義之自定義工具 body，可訪問每個已注冊 MCP 及持久記憶層。

Running Scripts

Inline Script

mcp__plugin_slop-mcp_slop-mcp__run_slop
  script: "tools.list()"

Script File

mcp__plugin_slop-mcp_slop-mcp__run_slop
  file_path: "/path/to/script.slop"

SLOP Language Basics

SLOP 為腳本語言，內置數據操作、字串處理及 MCP 工具執行函數。

Exploring Built-in Functions

列函數類別：

mcp__plugin_slop-mcp_slop-mcp__slop_reference
  list_categories: true

Categories: math, string, list, map, random, type, json, regex, time, encoding, functional, crypto, slop.

搜索函數：

mcp__plugin_slop-mcp_slop-mcp__slop_reference
  query: "split"
  verbose: true

取單個函數詳情：

mcp__plugin_slop-mcp_slop-mcp__slop_help
  name: "map"

Calling MCP Tools from SLOP

SLOP 腳本可調用任何已注冊 MCP 服務器上的任何工具。確切語法取決於 SLOP 運行時中工具的暴露方式。用 slop_reference 加 category: "slop" 查 MCP 集成函數：

mcp__plugin_slop-mcp_slop-mcp__slop_reference
  category: "slop"
  verbose: true

Example: Sequential Workflow

// Read a file, process it, write the result
content = tools.call("filesystem", "read_file", { "path": "input.txt" })
lines = split(content, "\n")
filtered = filter(lines, fn(line) { contains(line, "TODO") })
result = join(filtered, "\n")
tools.call("filesystem", "write_file", { "path": "todos.txt", "content": result })

Example: Search and Aggregate

// Search across multiple servers
results = tools.call("lci", "search", { "query": "error handling" })
count = len(results)
print("Found " + str(count) + " matches")

Example: Data Processing Pipeline

// Use built-in functions for data transformation
data = json_parse(tools.call("filesystem", "read_file", { "path": "data.json" }))
names = map(data, fn(item) { item.name })
sorted = sort(names)
json_stringify(sorted)

Built-in Function Reference

以下工具探索完整標準庫：

Common Categories

• string: split, join, trim, replace, contains, starts_with, ends_with, upper, lower
• list: map, filter, reduce, sort, reverse, flatten, unique, zip
• map: keys, values, entries, merge, get, set
• json: json_parse, json_stringify
• regex: regex_match, regex_replace, regex_find
• time: now, format_time, parse_time
• type: type_of, to_string, to_number, to_bool
• functional: map, filter, reduce, compose, pipe

Script Files

存腳本為 .slop 文件，以 run_slop 運行：

mcp__plugin_slop-mcp_slop-mcp__run_slop
  file_path: "./scripts/my-workflow.slop"

腳本最終表達式值作為結果返回。

Custom Tool Bodies

自定義工具 body 為 SLOP 腳本，由 customize_tools 之 define_custom action 保存、於 execute_tool 調用該自定義工具時運行。輸入驗證後入 args map；最終表達式（或 emit(...) 輸出）作為返回值。上游 MCP 工具不變 — 自定義工具僅為 SLOP 腳本包裝層，可組合多 MCP 調用為單一暴露工具。

Syntax Rules

• No $-prefixed variables. 變量為純標識符：doc, pages, result。與某些 SLOP 方言不同，此處無 $ 前綴。
• Map/object field access uses bracket notation: args["file_key"], page["name"]。無點式 args.file_key。
• Pipe operator | chains transforms: items | filter(|x| x["active"]) | map(|x| x["name"])。管道將左值作為首參傳入右函數。
• Anonymous functions use |param| syntax: map(list, |item| item["id"])。body 為單表達式，自動返回。
• emit(named: value, other: ...) 設命名輸出字段；省略 emit 則最後求值表達式為返回值。一 body 內僅一種模式。
• execute_tool(mcp, tool, args_map) 於 body 內可調用 — 此乃自定義工具組合其他 MCP 之機制。返回值為該工具之完整響應 map。
• Scalar shorthand binding with name collision is silently skipped. 綁頂層變量與 SLOP 內置同名者（map, len, filter, ...）遭跳過並記警告。如需 args 內 map 字段，直接以 args["map"] 訪問，勿作 map = args["map"] 綁定。

Resource Limits

• Body size cap 64 KB by default. 超限則 define_custom 拒受。環境變量 SLOP_MAX_CUSTOM_BODY 可提升（例如 SLOP_MAX_CUSTOM_BODY=131072 設 128 KB）。body 大於上限者應存為 recipe 文件，以 run_slop recipe:"<name>" 調用而非塞入 define_custom。
• Recursion depth guard 16 frames. 自定義工具可調其他自定義工具，但調用棧深過 16 frames 者返 ErrCustomToolRecursion — 為已知錯誤，非堆棧溢出。互遞歸兩工具超過此限亦觸發。

Example: Composite Body Calling Two MCPs

拉 GitHub 開放 issue，附帶 lci 倉庫統計：

// args: {repo: "owner/name"}
issues = execute_tool("github", "list_issues", {repo: args["repo"], state: "open"})
stats = execute_tool("lci", "stats", {path: args["repo"]})
titles = issues | map(|i| i["title"])
emit(
    count: len(issues),
    titles: titles,
    symbols: stats["symbol_count"]
)

execute_tool 兩次分別拉 github 與 lci；管道提取 title；emit 構造結構化返回值。代理調此自定義工具只見 {repo} 單參 schema，不見 github/lci 細節。

Memory Access from SLOP

持久記憶 mem_* 函數於任何 run_slop 腳本內皆可調，自定義工具 body 內亦可。腳本藉此存 last-seen 游標、緩存昂貴查詢、或為 monitor 腳本保存跨進程狀態。詳見 memory-system 技能。

mem_save(bank, key, value, description:, schema:)

存值至 ~/.config/slop-mcp/memory/<bank>.json 之 bank/key。description: 與 schema: 為可選 kwargs — 省略者保留既有元數據不變（非破壞性更新）。size 字段自動計算為序列化字節數，無須傳入。

// 首次保存寫全元數據
mem_save("monitor", "last_commit", "abc123",
         description: "Last seen HEAD sha from poll-git.slop",
         schema: "string")

// 後續更新僅傳值，元數據保留
mem_save("monitor", "last_commit", "def456")

mem_load(bank, key, default_value)

取值，鍵缺則返 default_value — 不拋異常。首次運行無狀態時用此平滑啟動：

last = mem_load("monitor", "last_commit", "")
if last == "":
    print("first run")

Discovery Primitives

三函數為零成本探查 — 不加載值即可查元數據。用於自定義工具 body 判斷既存狀態、或於腳本中列 bank 內容：

• mem_info(bank, key) — 返單條目之 description / schema / size / created_at / updated_at map，不含值。探大 blob 元數據而不付加載代價。
• mem_list(bank, pattern: "") — 列 bank 全部條目元數據。可選 glob pattern 過濾鍵名；輸出按鍵排序。
• mem_search(query, bank: "", include_values: false) — 跨 bank（或單 bank 若傳 bank:）大小寫不敏感子串搜索，匹配鍵名與描述。include_values: true 時亦搜索序列化值內容。

// 探 monitor bank 全部 last_* 游標
for e in mem_list("monitor", pattern: "last_*"):
    print(e["key"] + " (" + e["description"] + ")")

詳見 memory-system 技能。

Reserved _slop.* Banks

以 _slop. 開頭之 bank 名為 slop-mcp 定制層保留。自定義工具 body 內可以 mem_get 讀取 _slop.*（例如查既有覆蓋），但 mem_save / mem_delete 寫入 _slop.* 遭拒。寫路徑強制經 customize_tools 元工具 — 其在正確 scope 下更新覆蓋索引、刷新上游 schema 哈希、觸發 stale 檢測。

Example: Counter with Description

載計數器、遞增、保存。首次保存附描述，後續更新僅傳值：

count = mem_load("stats", "page_views", 0)
count = count + 1
if count == 1:
    mem_save("stats", "page_views", count,
             description: "Total landing page visits observed by tracker.slop",
             schema: "integer")
else:
    mem_save("stats", "page_views", count)
print("views: " + str(count))

第二分支省 kwargs — 既有 description / schema / created_at 原封不動，僅 updated_at 與 size 刷新。

Practical Patterns

Tool Discovery Script

// Find all file-related tools
tools.search("file")

Multi-Server Coordination

// Get data from one server, process with another
raw = tools.call("api-server", "fetch_data", { "endpoint": "/users" })
parsed = json_parse(raw)
tools.call("filesystem", "write_file", {
  "path": "users.json",
  "content": json_stringify(parsed, 2)
})

Error Handling

SLOP 腳本應處理 MCP 工具調用錯誤。查 SLOP 參考中錯誤處理構造：

mcp__plugin_slop-mcp_slop-mcp__slop_reference
  query: "error"
  verbose: true

Cross-references

• Invoke the Skill tool with skill: slop-mcp:tool-customization — customize_tools 元工具之 canonical reference，含 8 actions、3 scope 精度表、pack 導出/導入、staleness 檢測。自定義工具 body 之宿主。
• Invoke the Skill tool with skill: slop-mcp:memory-system — 雙層記憶深度指南：會話 store_* 與持久 mem_*、元數據 / 發現原語、memory-cli 互操作、_slop.* 寫屏障。
• Invoke the Skill tool with skill: slop-mcp:discovery-first — execute_tool 前須先 get_metadata / search_tools。SLOP 腳本中 tools.call / execute_tool 亦遵此律。
• Invoke the Skill tool with skill: slop-mcp:event-monitoring — slop-mcp monitor 子命令運行之 monitor 腳本亦為 SLOP，以 mem_save / mem_load 存 last-seen 游標跨進程重啟不丟狀態。