Skip to content

Expose terraphim_rlm tools via terraphim_mcp_server (agent training / nanocode parity) #480

@AlexMikhalev

Description

@AlexMikhalev

Goal

Make Terraphim easy to "teach" to coding agents (Claude Code / OpenCode) by providing a stable, self-documenting tool surface and deterministic guardrails.

This issue focuses on the RLM branch work needed to reach nanocode-like parity: expose terraphim_rlm MCP tools through terraphim_mcp_server, with clear session handling and docs.

Why

  • crates/terraphim_rlm already implements an RLM query loop + executor abstraction + MCP tool service (rlm_code, rlm_bash, rlm_query, rlm_context, rlm_snapshot, rlm_status).
  • But those tools are not currently visible/dispatchable from the main MCP server, which is what external agents integrate with.

Proposed changes

1) Wire RLM MCP tools into terraphim_mcp_server

  • Add terraphim_rlm dependency to crates/terraphim_mcp_server.
  • Instantiate TerraphimRlm + RlmMcpService during MCP server init.
  • Extend MCP list_tools to include RlmMcpService::get_tools().
  • Extend MCP call_tool to delegate rlm_* tool calls to RlmMcpService.

2) Decide/implement session UX

Pick one (recommend explicit session tools for deterministic external orchestration):

  • Option A: Add rlm_session_create, rlm_session_set_current, rlm_session_destroy tools.
  • Option B: Require session_id on all rlm_* calls and provide a default session if omitted.

3) Backend readiness / fallbacks

  • Document requirements for Firecracker backend (Linux + /dev/kvm).
  • Ensure a non-Firecracker fallback works (e.g., SSH/local) for dev environments.

4) Docs for agent integration (Claude Code / OpenCode)

Add a short doc describing:

  • the tool list + expected JSON schemas
  • recommended "roles" workflow (Retriever/Planner/Executor/Verifier)
  • where to plug deterministic replacements (hooks) vs relying on model memory

Acceptance criteria

  • tools/list from MCP includes all rlm_* tools.
  • call_tool works for:
    • rlm_bash (simple command)
    • rlm_code (simple Python snippet)
    • rlm_query (iterative loop until FINAL)
  • Session handling is documented and testable.
  • Minimal E2E demo documented (MCP client → rlm_query to solve a small task).

Notes

If needed, scope to the feat/terraphim-rlm-experimental branch first, then merge back once stable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions