REPL Tools

MCP tools for interacting with the Wippy runtime — inspect and modify the registry, execute code, manage processes, interact with services, and perform workspace file operations.

Installation

- name: dependency.repl
  kind: ns.dependency
  component: butschster/mcp-repl-tools
  version: ">=0.1.0"

Tools

File Operations

| Tool | Description | |--------------------|-------------------------------------------------------------| | wippy_list_files | List files and directories at a given path in the workspace | | wippy_read_file | Read file content from the workspace | | wippy_write_file | Write content to a file in the workspace |

Registry Operations

| Tool | Description | |---------------------------|--------------------------------------------------------------------| | wippy_entries_list | List all registry entries, optionally filtered by kind | | wippy_entries_get | Get a single registry entry by ID (namespace:name) | | wippy_entries_create | Create a new registry entry with kind, source, modules, etc. | | wippy_entries_update | Partial update of an existing entry (only specified fields change) | | wippy_entries_delete | Delete a registry entry by ID | | wippy_registry_versions | List versions, view snapshots at a version, or rollback |

Runtime Evaluation

| Tool | Description | |--------------|---------------------------------------------------------------------------| | wippy_eval | Execute Lua code in a sandboxed environment with controlled module access |

System Introspection

| Tool | Description | |---------------------------|------------------------------------------------------------------------| | wippy_system_info | Get memory stats, goroutines, CPU count, hostname, PID, loaded modules | | wippy_supervisor_status | Get status of all supervised services or a specific service |

Function Invocation

| Tool | Description | |-------------------|-------------------------------------------------------------------------| | wippy_func_call | Call any registered function by ID with arguments, context, and timeout |

Process Communication

| Tool | Description | |------------------------|-------------------------------------------------------------------| | wippy_process_send | Send a message to a running process by PID or registered name | | wippy_process_cancel | Request graceful cancellation of a process with optional deadline |

Event Bus

| Tool | Description | |---------------------|--------------------------------------------------------------| | wippy_events_send | Publish an event to the event bus for subscribers to receive |

Queue

| Tool | Description | |-----------------------|------------------------------------------------------------| | wippy_queue_publish | Publish a message to a queue for async consumer processing |

Key-Value Store

| Tool | Description | |-------------------|---------------------------------------------------------| | wippy_store_ops | Get, set, delete, or check existence of keys in a store |

MCP Prompt

| Prompt | Description | |--------------------|------------------------------------------------------------------------------------------------------------------| | wippy_repl_guide | Teaches LLMs correct tool usage, workflows, and Wippy runtime rules. Focus: all, tools, patterns, rules. |

Usage Examples

Evaluate Lua code at runtime:

wippy_eval(source="return 1 + 2")
wippy_eval(source="local j = require('json'); return j.encode({ok=true})", modules=["json"])

Check service health:

wippy_supervisor_status()
wippy_supervisor_status(service_id="app:worker")

Call a registered function:

wippy_func_call(id="app.api:get_user", args=[123])
wippy_func_call(id="app:migrate", timeout=30000)

Send a message to a process:

wippy_process_send(destination="app:session_handler", topic="refresh", payload={"user_id": "123"})

Publish an event:

wippy_events_send(system="orders", kind="order.created", path="/orders/456", data={"total": 99.99})

Store operations:

wippy_store_ops(store_id="app:cache", operation="set", key="user:123", value={"name": "Alice"}, ttl=3600)
wippy_store_ops(store_id="app:cache", operation="get", key="user:123")

Registry version history:

wippy_registry_versions(action="list")
wippy_registry_versions(action="current")
wippy_registry_versions(action="snapshot", version_id=5)
wippy_registry_versions(action="rollback", version_id=3)

List registry entries by kind:

wippy_entries_list(kind="function.lua")
wippy_entries_get(id="mcp:server")
wippy_entries_create(id="myns:handler", kind="function.lua", source="file://handler.lua", method="call")

Architecture

repl_tools/
├── _index.yaml              Tool entries with MCP metadata
├── wippy.yaml               Module metadata
├── README.md
│
│  File Operations
├── list_files.lua            List workspace files
├── read_file.lua             Read file content
├── write_file.lua            Write file content
│
│  Registry Operations
├── entries_list.lua          List registry entries
├── entries_get.lua           Get entry by ID
├── entries_create.lua        Create entry
├── entries_update.lua        Update entry
├── entries_delete.lua        Delete entry
├── registry_versions.lua     Version history & rollback
│
│  Runtime
├── eval.lua                  Execute Lua code (sandboxed)
├── system_info.lua           Runtime system information
├── supervisor_status.lua     Supervised service states
├── func_call.lua             Call registered functions
│
│  Communication
├── process_send.lua          Send message to process
├── process_cancel.lua        Cancel a process gracefully
├── events_send.lua           Publish to event bus
├── queue_publish.lua         Publish to message queue
│
│  Storage
├── store_ops.lua             Key-value store operations
│
│  Prompts
└── prompts/
    └── repl_guide.lua        LLM onboarding prompt for all tools

File tools use the fs module with fs.get("app:workspace"). Registry tools use the registry module for direct access to the running Wippy registry. Runtime tools use system, eval_runner, funcs, events, queue, and store modules. Process tools use the built-in process global.