diff --git a/docs/concepts/roots.mdx b/docs/concepts/roots.mdx new file mode 100644 index 0000000..e8d7267 --- /dev/null +++ b/docs/concepts/roots.mdx @@ -0,0 +1,79 @@ +--- +title: "Roots" +description: "Understanding roots in MCP" +--- + +Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations. + +## What are Roots? + +A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs. + +For example, roots could be: + +``` +file:///home/user/projects/myapp +https://api.example.com/v1 +``` + +## Why Use Roots? + +Roots serve several important purposes: + +1. **Guidance**: They inform servers about relevant resources and locations +2. **Clarity**: Roots make it clear which resources are part of your workspace +3. **Organization**: Multiple roots let you work with different resources simultaneously + +## How Roots Work + +When a client supports roots, it: + +1. Declares the `roots` capability during connection +2. Provides a list of suggested roots to the server +3. Notifies the server when roots change (if supported) + +While roots are informational and not strictly enforcing, servers should: + +1. Respect the provided roots +2. Use root URIs to locate and access resources +3. Prioritize operations within root boundaries + +## Common Use Cases + +Roots are commonly used to define: + +- Project directories +- Repository locations +- API endpoints +- Configuration locations +- Resource boundaries + +## Best Practices + +When working with roots: + +1. Only suggest necessary resources +2. Use clear, descriptive names for roots +3. Monitor root accessibility +4. Handle root changes gracefully + +## Example + +Here's how a typical MCP client might expose roots: + +```json +{ + "roots": [ + { + "uri": "file:///home/user/projects/frontend", + "name": "Frontend Repository" + }, + { + "uri": "https://api.example.com/v1", + "name": "API Endpoint" + } + ] +} +``` + +This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated. \ No newline at end of file diff --git a/mint.json b/mint.json index 1f47020..d5c63fd 100644 --- a/mint.json +++ b/mint.json @@ -58,6 +58,7 @@ "docs/concepts/prompts", "docs/concepts/tools", "docs/concepts/sampling", + "docs/concepts/roots", "docs/concepts/transports" ] }