roots-demo

Purpose

Demonstrate MCP roots protocol

Description

The roots-demo tool demonstrates how MCP servers can expose filesystem or project roots to clients. Roots help clients understand the server's directory structure, making it easier to work with file operations and understand project organization.

A "root" in MCP is a top-level directory or project location that the server can access. By exposing roots, servers enable clients to:

• Navigate project structures intelligently
• Suggest relevant file paths
• Understand workspace organization
• Provide better file-based completions

This is particularly useful for development tools, file managers, and any application that works with project structures.

Parameters

Parameter	Type	Required	Description
action	enum	No	Action: list, info, structure (default: list)
rootName	string	No	Specific root to show info for (required when action=info)

Example Usage

Ask Claude:

"List the available project roots"
"Show information about the Main Project root"
"What's the directory structure exposed through roots?"
"Demonstrate how MCP roots work"

Response

Action: list

## Available Roots

1. **Main Project**
   - URI: file:///workspace/project
   - Primary application source code

2. **Shared Libraries**
   - URI: file:///workspace/libs
   - Reusable library code

3. **Documentation**
   - URI: file:///workspace/docs
   - Project documentation and guides

Action: info

## Root Details: Main Project

**URI:** file:///workspace/project
**Name:** Main Project
**Description:** Primary application source code

This root contains:
- Source code for the main application
- Configuration files
- Build artifacts
- Test files

Use this root when working with the core application code.

Action: structure

## Example Directory Structure

Root: file:///workspace/project
├── src/
│   ├── components/
│   ├── services/
│   └── utils/
├── tests/
├── config/
└── package.json

How to use roots in file operations:
- Reference files relative to roots
- Use root URIs as base paths
- Navigate project structure efficiently

Actions

list

Shows all available roots with their URIs and descriptions.

Use cases:

• Discovering available workspaces
• Understanding project organization
• Finding relevant code locations

Example:

"What project roots are available?"

info

Shows detailed information about a specific root.

Use cases:

• Learning about a specific workspace
• Understanding what a root contains
• Getting usage guidance

Example:

"Tell me about the Documentation root"

structure

Shows example directory structures and path usage.

Use cases:

• Understanding project layout
• Learning navigation patterns
• Seeing typical file organization

Example:

"Show me the project structure"

Authentication

Required: No

The roots-demo tool is a demonstration tool and does not require authentication.

How MCP Roots Work

The roots protocol enables servers to expose their file structure:

1. Server defines roots for accessible directories
2. Client requests roots list to discover available locations
3. Client displays roots in file picker or navigator
4. User selects root as starting point for file operations
5. Client uses root URI as base for file paths

This provides a structured way to navigate complex projects without exposing the entire filesystem.

Root Structure

Each root includes:

{
  uri: string,           // URI of the root (e.g., file:///workspace/project)
  name?: string,         // Human-readable name (e.g., "Main Project")
  description?: string   // What this root contains
}

URI Schemes

Roots can use various URI schemes:

Scheme	Example	Description
file://	file:///workspace/project	Local filesystem path
git://	git://github.com/user/repo	Git repository
http://	http://example.com/files	Remote HTTP location
custom://	custom://internal/docs	Custom protocol

The most common is file:// for local directories.

Common Use Cases

Project Navigation

"Show me the project roots so I know where to find files"

Workspace Discovery

"What workspaces are available in this server?"

File Operations

"List files in the Main Project root"
"Search the Documentation root for markdown files"

IDE Integration

Client shows roots in file tree
→ User expands root to browse contents
→ Faster navigation than full filesystem

Real-World Examples

Multi-Project Workspace

Roots:
- Frontend (file:///workspace/frontend)
- Backend (file:///workspace/backend)
- Shared (file:///workspace/shared)

User can navigate each project independently

Monorepo Structure

Roots:
- Packages (file:///workspace/packages)
- Apps (file:///workspace/apps)
- Tools (file:///workspace/tools)

Clear separation of monorepo components

Documentation Site

Roots:
- Content (file:///workspace/content)
- Assets (file:///workspace/public)
- Templates (file:///workspace/templates)

Easy access to different content types

Client Integration

MCP clients can use roots to:

File Tree Display

Show roots as top-level folders
└── Main Project
    ├── src/
    ├── tests/
    └── config/

Path Suggestions

When user types file path:
→ Suggest based on root structure
→ Autocomplete with root context

Search Scoping

User searches for files
→ Option to search within specific root
→ Faster, more relevant results

Workspace Management

Switch between roots
→ Filter files by root
→ Organize multi-project work

Benefits of Roots

Security

• Limits filesystem access to defined roots
• Prevents access to system directories
• Controlled exposure of project structure

Organization

• Clear project boundaries
• Logical grouping of related files
• Easier navigation for users

Performance

• Clients can cache root structure
• Faster file operations within known roots
• Reduced scanning of irrelevant directories

Usability

• Intuitive project navigation
• Consistent path handling
• Better file picker UX

Related Tools

• log-demo - Demonstrate MCP logging protocol
• trigger-notification - Demonstrate MCP notification protocol
• sampling-demo - Demonstrate MCP sampling protocol

Next Steps

• All Tools - Return to tools overview
• Development Guide - Learn to build MCP tools
• MCP Protocol Specification - Full MCP protocol documentation