# Introduction

A Rust SDK, terminal UI, and MCP server for [Roam Research](https://roamresearch.com).

The `roam-sdk` crate provides three things in one package:

* **SDK** — a Rust client for the Roam Research API. Use it to build your own tools, scripts, or integrations.
* **TUI** — a terminal-based interface for navigating and editing your Roam graph.
* **MCP Server** — expose your Roam graph to AI assistants via the Model Context Protocol.

## Quick links

| I want to...                 | Go to                                                                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use the terminal app         | [TUI Installation](https://roam-tui.avelino.run/tui/installation)                                                                                       |
| Configure the app            | [Configuration](https://roam-tui.avelino.run/tui/configuration)                                                                                         |
| Learn keybindings            | [Keybindings](https://roam-tui.avelino.run/tui/keybindings)                                                                                             |
| Export notes                 | [Export](https://roam-tui.avelino.run/export)                                                                                                           |
| Select multiple blocks       | [Multi-Block Selection](https://roam-tui.avelino.run/tui/multi-select)                                                                                  |
| Set up MCP for AI assistants | [MCP Setup](https://roam-tui.avelino.run/mcp-server/setup)                                                                                              |
| See MCP tools                | [Tools Reference](https://roam-tui.avelino.run/mcp-server/tools)                                                                                        |
| Use the Rust SDK             | [SDK Getting Started](https://roam-tui.avelino.run/sdk/getting-started)                                                                                 |
| See API reference            | [Client](https://roam-tui.avelino.run/sdk/client), [Types](https://roam-tui.avelino.run/sdk/types), [Queries](https://roam-tui.avelino.run/sdk/queries) |

## Architecture

```
roam-sdk (crate)
├── lib.rs          → SDK: RoamClient, types, queries, errors
├── main.rs         → TUI: terminal interface using the SDK
├── mcp.rs          → MCP: stdio server with 18 tools
└── export.rs       → Export: markdown and JSON formatters
```

The TUI is built on [Ratatui](https://ratatui.rs) + [Tokio](https://tokio.rs) and uses the SDK internally. The MCP server uses [rmcp](https://crates.io/crates/rmcp) for the Model Context Protocol implementation. Both ship from the same crate — install the binary with `cargo install roam-sdk`, or add the library with `cargo add roam-sdk`.