# Rootr [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/inspirio-co/rootr-cli  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/rootr

## Description
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "rootr": {
    "url": "https://rootr.io"
  }
}
```

## Documentation & README

# Rootr CLI + MCP Server

**Connect your team's living knowledge base to Claude, ChatGPT, and any AI agent.**

[Rootr](https://rootr.io) is a team knowledge & document workspace. This package is the
official way to give an AI agent **direct, permissioned access to your team's shared
documents, structured data, and institutional knowledge** — so your assistant already
knows what your team knows, instead of you copy-pasting context into every conversation.

There are two ways to connect.

## 1. Remote connector — no install (recommended)

Rootr hosts a remote MCP endpoint over **Streamable HTTP**. In Claude Desktop, claude.ai,
or ChatGPT, add a connector with just the URL and sign in with OAuth:

```
https://rootr.io/mcp
```

No JSON, no CLI, no tokens to paste. Log in, pick the workspace, and your team's docs are
available to the assistant with your existing permissions. See the
[docs](https://rootr.io/en/docs).

## 2. Local CLI / stdio MCP server (`rootr-cli`)

For the shell, or for agents that speak to a local stdio MCP server (e.g. Claude Code):

```bash
npm install -g rootr-cli
rootr config --api-key rootr_xxxx --workspace ws_xxx
rootr mcp          # start the stdio MCP server
```

The `rootr` command also works standalone: `ls`, `read`, `write`, `append`, `edit`,
`search`, `ask`, `ws`, `config`.

Pure Node.js ESM, no build step. Requires Node 18+ (uses the built-in `fetch`).

- **Homepage:** https://rootr.io
- **Docs:** https://rootr.io/en/docs
- **npm:** https://www.npmjs.com/package/rootr-cli

---

## Install

Run it straight from a clone, or install globally.

```bash
npm install -g rootr-cli
rootr --help

# or from source
cd cli && npm install
node bin/rootr.js --help
```

## Configuration

Precedence: **environment variables > `~/.rootr/config.json`**

| Env var | Config key | Description |
|---|---|---|
| `ROOTR_API_KEY` | `apiKey` | A `rootr_...` API key. Sent as the `x-api-key` header on every request. |
| `ROOTR_WORKSPACE` | `workspace` | Workspace id |
| `ROOTR_BASE_URL` | `baseUrl` | Defaults to `https://rootr.io/api/v1` |

Save to the config file (created with `chmod 600`):

```bash
rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
# optional on-prem / dev base URL
rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1

rootr config          # show current config (api key shown masked)
```

### Two kinds of key

Rootr API keys come in two kinds, and some tools require a specific one:

- **Workspace key** — scoped to a single workspace
  (`docs:read` / `docs:write` / `graph:read` / `ask` / `webhooks:manage`). Enough for most
  document, LOG, issue, webhook, and ask tools.
- **Account key (PAT)** — acts across your whole account. With the `workspaces:create`
  scope it can create new workspaces (`rootr_create_workspace`). Using a workspace key for
  an account-level action returns a `403` with a hint that an account key is required.

## CLI usage

Path rule: an argument starting with `/` is treated as a **path** (resolved to a node id
via the by-path API; needs a workspace set). Otherwise it is treated as a **node id**.

```bash
rootr ls                                   # whole tree  (TYPE<TAB>path)
rootr ls /notes                            # subtree

rootr read /notes/todo.md                  # markdown to stdout
rootr read /notes/todo.md --json           # full JSON incl. metadata

echo "# Title" | rootr write /notes/new.md # full replace (creates if missing)
rootr write /notes/new.md --file ./local.md

rootr append /notes/log.md "Deployed today"          # safe, conflict-free
rootr append /notes/log.md "- one more" --heading "## Todo"

rootr edit /notes/todo.md --find "- [ ] ship" --replace "- [x] ship"

rootr search "deploy runbook"              # path — snippet
rootr ws                                   # list workspaces (id<TAB>name)
rootr ask "why did latency go up after last week's deploy?"
```

`append` never rewrites the whole document, so it is safe to run concurrently. `write`
supports `--if-match "\"etag\""` for optimistic concurrency (a `412` means the document
changed underneath you — re-read and retry). `edit` returns `409` if `--find` is missing or
not unique; pass `--all` to replace every match. `ask` queries the workspace knowledge graph
(GraphRAG) and prints the answer plus citations (document path: quote).

## Use as an MCP server

`rootr mcp` starts a Model Context Protocol server over stdio. It exposes **80+ tools**
across the full Rootr surface, so an agent can author and query every node type:

| Group | Tools (examples) |
|---|---|
| **Documents** | `rootr_list`, `rootr_read`, `rootr_append` *(recommended, conflict-free)*, `rootr_edit`, `rootr_write`, `rootr_search`, `rootr_document_versions`, `rootr_delete_node`, `rootr_duplicate_node` |
| **Publishing & comments** | `rootr_publish_document`, `rootr_set_document_public`, `rootr_document_public_status`, `rootr_comment_document`, `rootr_list_document_comments` |
| **Workspaces & scaffolding** | `rootr_workspaces`, `rootr_scaffold_plan`, `rootr_create_workspace`, `rootr_scaffold_apply` |
| **Databases** (typed columns + board/table views) | `rootr_read_database`, `rootr_add_row`, `rootr_update_row`, `rootr_delete_row`, `rootr_list_rows` |
| **Spreadsheets** (formulas) | `rootr_create_spreadsheet`, `rootr_read_spreadsheet`, `rootr_update_spreadsheet`, `rootr_create_sheet`, `rootr_update_sheet`, `rootr_delete_sheet`, `rootr_patch_spreadsheet_cells` |
| **Whiteboards** | `rootr_create_whiteboard`, `rootr_read_whiteboard`, `rootr_update_whiteboard` |
| **Forms** | `rootr_create_form`, `rootr_read_form`, `rootr_update_form`, `rootr_list_form_responses`, `rootr_submit_form_response`, `rootr_create_form_share_link`, `rootr_list_form_share_links` |
| **CRM** | `rootr_crm_*` — companies, contacts, deals (kanban), activities, tasks, CSV import |
| **Presentations** | `rootr_create_presentation`, `rootr_read_presentation`, `rootr_update_presentation`, `rootr_update_presentation_slide`, `rootr_append_presentation_slides`, `rootr_reorder_presentation_slides` |
| **LOG datastores** | `rootr_create_log_store`, `rootr_update_log_fields`, `rootr_add_log_entries`, `rootr_query_log_entries`, `rootr_log_stats` |
| **Issues** | `rootr_create_issue_tracker`, `rootr_list_issues`, `rootr_create_issue`, `rootr_get_issue`, `rootr_update_issue`, `rootr_comment_issue` |
| **Webhooks** | `rootr_list_webhooks`, `rootr_create_webhook`, `rootr_delete_webhook` |
| **GraphRAG ask** | `rootr_ask` — natural-language root-cause Q&A over the knowledge graph, with citations |
| **Images** | `rootr_generate_image`, `rootr_remove_image_background` |

Tool descriptions steer agents to prefer `rootr_append` / `rootr_edit` over the destructive
`rootr_write`. Tools that take a `workspace` argument fall back to `ROOTR_WORKSPACE` (or the
config default) when it is omitted. All tool schemas are in English; JSON-returning tools
respond with pretty-printed JSON text.

### Register in Claude Code / Claude Desktop

Add to `~/.claude.json` (Claude Code) or your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "rootr": {
      "command": "rootr",
      "args": ["mcp"],
      "env": {
        "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
        "ROOTR_WORKSPACE": "ws_123"
      }
    }
  }
}
```

(If you did not install globally, use `"command": "node"` and
`"args": ["/path/to/rootr-cli/bin/rootr.js", "mcp"]`.)

## Error handling

On a non-2xx response the CLI prints the API `message` (when present) to stderr and exits 1:

- `401` / `403` — check the API key / workspace scope
- `412` — document changed since you read it (If-Match mismatch): re-read and retry
- `409` — the server's reason is shown verbatim (e.g. `edit` find not found / not unique)

## Layout

- `bin/rootr.js` — entry point, command dispatch
- `lib/config.js` — config load/save
- `lib/client.js` — Rootr REST API client
- `lib/resolve.js` — shared path/id target resolution
- `lib/mcp.js` — MCP stdio server, assembles all tool groups
- `lib/mcp-tools/*` — one module per tool group (documents, workspaces, databases,
  spreadsheets, whiteboards, forms, crm, presentations, logs, issues, webhooks, ask, misc)

Dependencies: `@modelcontextprotocol/sdk` (MCP server) and `zod` (tool input schemas). The
CLI core has no external dependencies. No build step — pure ESM JavaScript.

---

Made by [Inspirio](https://inspirio.co) · [rootr.io](https://rootr.io) · info@inspirio.co