H2oslabs Elfiee Elfiee Client

Elfiee MCP Tools

Elfiee exposes MCP tools and resources for interacting with .elf files. Two connection modes:

Prohibited Actions

When Elfiee MCP is connected, ALL content managed by .elf blocks MUST be read and written through Elfiee MCP tools.

NEVER do these:

Why this matters:

• .elf uses event sourcing — direct filesystem edits bypass the event log and will be lost or overwritten
• Permissions are enforced through CBAC (Capability-Based Access Control) — only MCP tools check authorization
• Block snapshots (physical files) are derived data regenerated from events — editing them directly has no lasting effect

MCP Connection Failure Protocol

If any elfiee_* MCP tool returns a connection error, timeout, or "server unavailable":

1. STOP all Elfiee-related operations immediately
2. DO NOT fall back to filesystem tools (Read, Write, Edit, Bash) to modify block content
3. DO NOT try to read or modify files in .claude/, .elf/, or any path that corresponds to .elf block directories
4. REPORT the connection failure to the human user
5. WAIT for human confirmation before taking any further action

Why this matters:

• When Elfiee GUI is running, it holds the event store lock
• Direct filesystem modifications bypass event sourcing and WILL be overwritten
• The human user can check if Elfiee needs to be restarted or the agent re-enabled

The only exception:

• elfiee_directory_export explicitly exports block content to the filesystem for external use (e.g., git commit). Files created by export ARE normal filesystem files and can be read/edited normally after export.

Standalone Mode

Run elfiee mcp-server --elf /path/to/project.elf as a subprocess. Configure in .claude/mcp.json:

{
  "mcpServers": {
    "elfiee": {
      "command": "elfiee",
      "args": ["mcp-server", "--elf", "/path/to/project.elf"]
    }
  }
}

Standalone mode auto-creates an mcp-agent editor with full permissions. Uses SQLite WAL mode for concurrent access.

Quick Start

1. Call elfiee_file_list to get open projects and their paths
2. Use the project path (e.g., "./my.elf") in all subsequent calls
3. Call elfiee_block_list to discover blocks
4. Use type-specific tools to read/write content

Common Parameter: project

Every tool (except elfiee_file_list) requires project -- the .elf file path as returned by elfiee_file_list.

Block Types

markdown | code | directory | terminal | task

Tool Reference

File Discovery

Block CRUD

Block Relations

Relation type: implement (the only allowed relation type). Semantic: A → B means "A's change caused B's change".

Content Read/Write

Directory Operations

Terminal Operations

Task Operations

Permission (CBAC)

Capability IDs: core.create, core.read, core.link, core.unlink, core.delete, core.grant, core.revoke, core.update_metadata, core.rename, core.change_type, markdown.write, markdown.read, code.write, code.read, directory.create, directory.delete, directory.rename, directory.write, directory.import, directory.export, terminal.init, terminal.execute, terminal.save, terminal.close, task.write, task.read, task.commit, agent.create, agent.enable, agent.disable.

Agent permission note: Agents do NOT have core.grant / core.revoke capabilities. Permission management is reserved for human owners via the Elfiee GUI. Do not attempt to call elfiee_grant / elfiee_revoke — they will fail with authorization errors.

Editor Management

Generic Execution

Use elfiee_exec for capabilities not covered by dedicated tools.

Workflow Examples

Read all markdown blocks

1. elfiee_file_list -> get project path
2. elfiee_block_list(project) -> find blocks where block_type == "markdown"
3. elfiee_markdown_read(project, block_id) -> for each markdown block

Create a code file in a directory block

1. elfiee_file_list -> get project path
2. elfiee_block_list(project) -> find directory block
3. elfiee_directory_create(project, block_id, path="src/main.rs",
     type="file", source="outline", content="fn main() {}",
     block_type="code")

Execute a terminal command

1. elfiee_file_list -> get project path
2. elfiee_block_list(project) -> find terminal block
3. elfiee_terminal_init(project, block_id)
4. elfiee_terminal_execute(project, block_id, command="cargo build")
5. elfiee_terminal_close(project, block_id)

Link blocks with implement relation

1. elfiee_block_link(project, parent_id=task_block_id, child_id=code_block_id, relation="implement")

/new-task workflow

When the user says /new-task or asks you to create a task:

Step 1: Create task

elfiee_task_create(project, name="Task name", description="What needs to be done")
-> Store returned task_block_id as ACTIVE_TASK

Step 2: Work on implementation For EVERY code/markdown block you create or modify while working on this task:

elfiee_code_write(project, block_id, content)       # or markdown_write
elfiee_task_link(project, task_id=ACTIVE_TASK, block_id=block_id)  # auto-link

The link is idempotent — calling it multiple times for the same pair is safe.

Step 3: Commit

elfiee_task_commit(project, block_id=ACTIVE_TASK)
-> Exports implement-linked blocks to their git repos
-> Creates branch: feat/{task_name}
-> Git commit with task description
-> Returns: { commit_hash, branch_name, exported_files }

Step 4: Test (optional)

elfiee_terminal_execute(project, terminal_block_id, command="cd /repo && cargo test")
-> If tests fail: fix code -> commit again -> test again
-> If tests pass: task complete

Causal Linking Protocol

This is the core of Elfiee editing. Every modification must be traceable to its cause through implement links.

Rule: Link Before You Modify

Before modifying Block B because of Block A, create the causal link first:

elfiee_block_link(project, parent_id=A, child_id=B, relation="implement")
elfiee_code_write(project, block_id=B, content=...)  # then modify

When to Create Links

When NOT to Link

• You only read a block for reference (no causal dependency)
• The two blocks are unrelated
• The link already exists (linking is idempotent, but check first to avoid noise)

DAG Constraint and Cycle Rejection

The relationship graph is a strict Directed Acyclic Graph (DAG). Elfiee automatically detects cycles and rejects link creation if a cycle would form.

Link direction rule: Arrow points from cause to effect — from the upstream block that drove the change to the downstream block that was changed.

cause → effect
Task  → Code       ✓ (task drives code writing)
Code  → Test       ✓ (code drives test writing)
Test  → Code       ✗ CYCLE if Code → Test already exists!

If elfiee_block_link returns a cycle error:

1. The link direction is wrong — re-examine the causal relationship
2. The driving force is probably an upstream block (e.g., Task), not the sibling
3. Do NOT create reverse links to work around the constraint

TDD Best Practice

In TDD workflows, tests and code may be modified alternately. The correct link structure:

Task → Code → Test

• Task → Code: Task requirement drives code implementation
• Code → Test: Code implementation drives test writing

When test failure reveals a code bug:

• The root cause is still the Task (not the test)
• Do NOT create Test → Code — this would form a cycle with Code → Test
• The existing Task → Code link already captures the causal chain
• Fix the code, update the test — no new links needed

Multi-block Modification Workflow

When a single task requires modifying multiple blocks:

1. elfiee_task_create(project, name="Add auth")  → task_id
2. For each block to modify:
   a. elfiee_block_link(project, parent_id=task_id, child_id=block_id, relation="implement")
   b. elfiee_code_write(project, block_id, content=...)
3. elfiee_task_commit(project, block_id=task_id)  → exports all linked code to git

Graph-First Context Navigation

Rule: When you need context, traverse the relationship graph BEFORE searching unrelated blocks.

Algorithm

1. Read the target block
2. List all blocks (elfiee_block_list) and examine their children to build a parent-child map
3. Traverse up (parents → grandparents → root) to understand why this block exists
4. Traverse down (children → grandchildren) to understand what this block produced
5. Read siblings (other children of the same parent) to understand related work
6. Only then search unrelated blocks if the graph doesn't provide enough context

Example: Understanding a Code Block

1. elfiee_code_read(project, block_id="src/auth.rs")         # read the code
2. elfiee_block_list(project)                                  # get all blocks
3. Find: Task "Add auth" has children: [src/auth.rs, src/middleware.rs, tests/auth_test.rs]
4. elfiee_task_read(project, block_id=task_block)              # understand the requirement (parent)
5. elfiee_code_read(project, block_id="src/middleware.rs")     # read sibling implementation
6. elfiee_code_read(project, block_id="tests/auth_test.rs")   # read downstream test

This gives you the full causal context: why (task), what (code), verification (test) — without searching unrelated blocks.

MCP Resources

Read-only data accessible via ReadMcpResourceTool (server: elfiee).

Static Resources

Dynamic Resources (per project)

Replace {project} with the project path (e.g., ./my.elf) and {block_id} with the block ID.

Error Handling

Converted and distributed by TomeVault — claim your Tome and manage your conversions.